---

First Steps
[Tutorial 4 - Writing a Plugin]

There are a number of housekeeping issues that must be addressed when writing a plugin. Every plugin requires very similar code. The first decision to make is what data needs to be added to the RenderWare Graphics object. In this tutorial we only require adding a single char * variable to each atomic.

As RenderWare Graphics starts up we need to inform RenderWare Graphics that every atomic that gets created must increase in size by enough bytes to store a character pointer. This is why plugins must register with RenderWare Graphics. First of all we will write a plugin API call to initialize the plugin.

• Create new files RpAName.c and RpAName.h and add them to the project.
• Add the following code to RpAName.h:

      /* Function prototypes */
      #ifndef RPANAME_H
      #define RPANAME_H
      #ifdef    __cplusplus
      extern "C"
      {
      #endif                          /* __cplusplus */
      extern RwInt32 RpAtomicNameInitialize(void);
  

      #ifdef    __cplusplus
      }
      #endif                          /* __cplusplus */
      #endif /* RPANAME_H */
  

• Add the following code to RpAName.c. This code tells RenderWare Graphics that each atomic must grow in size by the size of a character pointer. The code also registers two callbacks, one used to initialize the plugin data, and one to destroy the data.

      #include <rwcore.h>
      #include <rpworld.h>
      #include "RpAName.h"
      /****************************************************************************/
      /* Local defines */
  

      /* note that this is a hack and should be a registered plugin ID */
      #define rwID_EXAMPLE 0xff
      /****************************************************************************/
      /* Local variables */
      static RwInt32 rpExtensionOffset = -1;
      /****************************************************************************/
      /* Local functions for the atomic name plugin */
  

      /*   Atomic Name Application Programming Interface    */
      /*********************************************************************************/
      RwInt32
      RpAtomicNameInitialize(void)
      {
          rpExtensionOffset =
              RpAtomicRegisterPlugin(sizeof(char *),
                     MAKECHUNKID(rwVENDORID_CRITERIONTK, rwID_EXAMPLE),
                     rpConstructor,
                     rpDestructor,
                     NULL);
  

          /* return the offset */
          return (rpExtensionOffset);
      }
  

  This code informs RenderWare Graphics that each atomic must be increased in size by sizeof(char *) bytes. Also, the call to RpAtomicRegisterPlugin() passes in a unique value used to identify the extension data in the .DFF file format. It is essential that this chunk ID is unique. In the tutorial we have used the Criterion Software vendor ID, and an unused plugin ID to create the chunk ID. Note that developers must obtain their own plugin vendor ID from Criterion, and must ensure that their plugins have distinct numbers. The call to RpAtomicRegisterPlugin() also provides the names of two functions (as yet unwritten). These functions are called when RenderWare Graphics creates and later destroys an atomic. The purposes of these functions are to initialize and clean up the extension data. In a few moments we will write these functions. Finally, the code we have added to RpAName.c stores the offset from the beginning of an atomic to the extension data in the variable rpExtensionOffset. This value is needed by the plugin.

  Next we must implement the construction and destruction callbacks. To begin with, we will implement basic stub functions that simply call RwDebugSendMessage() to inform us that the functions have been called.

• Write the functions rpConstructor() and rpDestructor(). Both functions take three arguments, a void pointer, and two RwInt32's - offset and size. Make calls to RwDebugSendMessage() to report that the functions have been called. You might need to check the API reference for the arguments you need to pass to this function.

      /* Local functions for the atomic name plugin */
      static void *
      rpConstructor(void *atom,
                    RwInt32 offset __RWUNUSED__, RwInt32 size __RWUNUSED__)
      {
  

          RwDebugSendMessage(rwDEBUGMESSAGE,
                             "rpConstructor",
                             "Atomic constructor called.");
  

          /* success */
          return (atom);
      }
  

      static void *
      rpDestructor(void *atom,
                   RwInt32 offset __RWUNUSED__, RwInt32 size __RWUNUSED__)
      {
  

          RwDebugSendMessage(rwDEBUGMESSAGE,
                             "rpDestructor",
                             "Atomic destructor called.");
  

          /* success */
          return (atom);
      }
  

• Add the RpAName.h header file to main.c, and in the AttachPlugins() function, make a call to RpAtomicNameInitialize() to register the atomic extension.

• Build your application and debug it. Create an atomic by pressing the F1 key, and then exit the application. Look in the debug log. You should see debug messages to say that the constructor and destructor functions were called. This shows that the plugin is being called as atomics are created and destroyed. Not that when you call the RpClumpStreamRead() API to load an atomic from disk, internally this API will call RpAtomicCreate(), and this is when the rpConstructor() function is called.

  Now we should initialize the extension data when the constructor is called, and destroy any extension data when the destructor is called. In our application when an atomic is created it will have no name. This will be denoted by the normal convention of the character pointer being NULL. Later on we will create space for the name by using RwMalloc(), so the destructor will call RwFree(). Note that the constructor and destructor get passed a void *. If we add the value of rpExtensionOffset to the address of the void * pointer we get a pointer to our extension data. If is helpful to define a macro to convert the void * into a pointer to our data.

• Add the following macro definition to RpAName.c. This converts a pointer to an atomic to our extension data.

      /* Local defines */
      /* Given an atomic, return a pointer to the extension */
      #define RPEXTFROMATOMIC(a)\
          ((char **)(((RwUInt8 *)(a)) + rpExtensionOffset))
      /* note that this is a hack and should be a registered plugin ID */
      #define rwID_EXAMPLE 0xff
  

• Next modify the constructor and destructor:

      static void *
      rpConstructor(void *atom,
                    RwInt32 offset __RWUNUSED__, RwInt32 size __RWUNUSED__)
      {
          if (rpExtensionOffset > 0)
          {
              char **extData = RPEXTFROMATOMIC(atom);
              /* atomics have no name to start with */
              *extData = NULL;
          }
          /* success */
          return (atom);
  

      }
  

      static void *
      rpDestructor(void *atom,
                   RwInt32 offset __RWUNUSED__, RwInt32 size __RWUNUSED__)
      {
          if (rpExtensionOffset > 0)
          {
              char **extData = RPEXTFROMATOMIC(atom);
              if (*extData)
              {
                  RwFree(*extData);
              }
          }
          /* success */
          return (atom);
  

      }
  

• Compile and debug this code. Place breakpoints on the constructor and destructor functions, and check that this code is called and works as expected. Note that currently we do not call RwMalloc(), and so the call to RwFree() will never be made.

  Note:

  The return type from the RPEXTFROMATOMIC macro is a pointer to our extension data, and not the extension data itself, which is why extData is typed as a pointer to a pointer to a character.

Next...

---