Adding API Functions

Add the following code to RpAName.c:

    const char *
    RpAtomicNameSetName(RpAtomic *atom, const char *name)
    {
        RwInt32 len = rwstrlen(name);
        if ((rpExtensionOffset > 0) & (len > 0))
        {
            char **extData = RPEXTFROMATOMIC(atom);
            /* blow away any old name */
            if (*extData)
            {
                RwFree(*extData);
            }
            *extData = RwMalloc(len + 1, rwID_NAOBJECT);
            rwstrcpy(*extData, name);
            return name;
        }
        /* plugin not initialized or no name provided */
        return NULL;

    const char *
    RpAtomicNameGetName(RpAtomic *atom)
    {
        if (rpExtensionOffset > 0)
        {
            char **extData = RPEXTFROMATOMIC(atom);
            return *extData;
        }
        /* plugin not initialized */
        return NULL;

Add the appropriate externs to RpAName.h:

    extern const char *RpAtomicNameSetName(RpAtomic *atom, const char *name);

    extern const char *RpAtomicNameGetName(RpAtomic *atom);

Modify main.c to make use of the RpAtomicNameGetName() API call. Change the DisplayOnScreenInfo() function to extract the name of the atomic, and to prefix the atomic's translation. If no name is assigned to the atomic, then we will display "NoName" instead.

            if (PickedAtomic)
            {
                RwFrame *f = RpAtomicGetFrame(PickedAtomic);
                RwMatrix *m = RwFrameGetLTM(f);
                const RwChar *s;
                s = RpAtomicNameGetName(PickedAtomic);
                RsSprintf(caption, RWSTRING("<%s>:%4.2f %4.2f %4.2f"), 
                    s?s:"NoName", m->pos.x, m->pos.y, m->pos.z);
                RsCharsetPrint( Charset, caption, 0, 2, rsPRINTPOSTOPRIGHT );
            }

Compile and test your code. You should see that all atomics currently have no name.

Make the picking persistent by commenting out the PickedAtomic = NULL assignment at the bottom of the main.c source file:

        case MMPickAndZTranslateObject :
            PickAtomic(MMZTranslateObject);
            break;
        case MMZTranslateObject :
            ZTranslateAtomic();
            break;
        default:
            //PickedAtomic = NULL;
            break;
        }
        Render();

Define an array of names in main.c that we can use to assign to atomics:

    #define NUMNAMES 6
    static const RwChar *AtomicNames[NUMNAMES] = {
        "Cube",
        "Banana",
        "Bob",
        "Jim",
        "Julie",
        "Auberon"
    };
    static RwInt32 SelectedName = 0;

Then add a menu entry that uses this list of names. This menu entry uses the list of names to know what to display in the menu. In the code we just use an integer variable.

    /* InitializeMenu function */
    static RwBool 
    InitializeMenu(void)
    {   
        static RwChar fpsLabel[] = RWSTRING("FPS_F");
        static RwChar nearLabel[] = RWSTRING("Near Clip");
        static RwChar farLabel[] = RWSTRING("Far Clip");
        static RwChar showPosLabel[] = RWSTRING("Show Position");
        static RwChar namesLabel[] = RWSTRING("Name Choice");

        if( MenuOpen(TRUE, &ForegroundColor, &BackgroundColor) )
        {
            MenuAddEntryBool(fpsLabel, &FPSOn, NULL);
            MenuAddEntryReal(nearLabel, &NearClip, NULL, 0.1f, 10.0f, 0.1f);
            MenuAddEntryReal( farLabel, & FarClip, NULL, 10.0f, 100.0f, 1.0f);
            MenuAddEntryBool(showPosLabel, &ShowPos, NULL);
            MenuAddEntryInt(namesLabel, &SelectedName, NULL, 0, NUMNAMES-1, 1, AtomicNames);

            return TRUE;
        }

        return FALSE;
    }

Compile and test your code. You should be able to select between the list of names, but we have yet to propagate this to an atomic.

Add a menu trigger. When the user selects this trigger a callback function will be called. The callback will be called assignNameTrigger().

    /* InitializeMenu function */
    static RwBool 
    InitializeMenu(void)
    {   
        static RwChar fpsLabel[] = RWSTRING("FPS_F");
        static RwChar nearLabel[] = RWSTRING("Near Clip");
        static RwChar farLabel[] = RWSTRING("Far Clip");
        static RwChar showPosLabel[] = RWSTRING("Show Position");
        static RwChar namesLabel[] = RWSTRING("Name Choice");
        static RwChar assignLabel[] = RWSTRING("Assign Name");

        if( MenuOpen(TRUE, &ForegroundColor, &BackgroundColor) )
        {
            MenuAddEntryBool(fpsLabel, &FPSOn, NULL);
            MenuAddEntryReal(nearLabel, &NearClip, NULL, 0.1f, 10.0f, 0.1f);
            MenuAddEntryReal( farLabel, & FarClip, NULL, 10.0f, 100.0f, 1.0f);
            MenuAddEntryBool(showPosLabel, &ShowPos, NULL);
            MenuAddEntryInt(namesLabel, &SelectedName, NULL, 0, NUMNAMES-1, 1, AtomicNames);
            MenuAddEntryTrigger(assignLabel, assignNameTrigger);

            return TRUE;
        }

        return FALSE;
    }

Finally write the assignNameTrigger() callback function. If there is an atomic selected, then the code will call the RpAtomicNameSetName() API.

    assignNameTrigger(RwBool check)
    {
        if (PickedAtomic && !check)
        {
            RpAtomicNameSetName(PickedAtomic, AtomicNames[SelectedName]);
        }

        return TRUE;
    }

Compile and run the program. Create an atomic (or drag one onto the application). Then use the menu to select a name, and assign it using the bottom menu item. Turn on the "Show Position" option, and you should see that the atomic has been given a name. Load a few more atomics and give each a unique name. Confirm that each atomic stores its name correctly. This shows that the plugin is working as expected. The application can use the plugin to store a name with each atomic. In the screenshot below, the banana has been given the name "Auberon".

Adding API Functions [Tutorial 4 - Writing a Plugin]

Adding API Functions
[Tutorial 4 - Writing a Plugin]