![]() |
![]() |
![]() |
Common ElementsThe host is the program, either Layout or Modeler, that runs your plug-ins. A plug-in module is a file, usually with a .p extension, that contains one or more LightWave plug-ins. Any number of plug-ins can be compiled together into a single module--it's common for an image loader and an image saver to be together in the same file, for example. Every plug-in file needs a server description that lists the plug-ins in the file, and every plug-in needs a special entry point function, its activation function. Both of these are defined in the lwserver.h header file. Each plug-in file also contains initialization and cleanup functions called Startup and Shutdown. Server Description The server description lists what your plug-in file contains. It's the first thing the host examines when it loads your module. The list appears in your source code as an array of ServerRecords. typedef struct st_ServerRecord { const char *className; const char *name; ActivateFunc *activate; ServerUserName *userNames; } ServerRecord;
The userNames field is an array of ServerUserName structures. typedef struct st_ServerUserName { const char *userName; long langID; } ServerUserName;
Activation Function The activation function is the entry point for the service provided by your plug-in. For some plug-in classes, this may be the only function the host calls in your plug-in (other than the startup and shutdown functions). For others, the activation function is where the host finds out about the plug-in's callback functions. XCALL_( int ) MyActivate( long version, GlobalFunc *global, void *local, void *serverData );
The activation function returns a code that tells the host whether the plug-in was activated successfully.
Startup and Shutdown (If you're new to writing LightWave plug-ins, you can safely skip this part.) These two optional entry points allow the module to initialize itself when it is first loaded and to clean itself up before being unloaded. void *Startup( void ); void Shutdown( void *serverData ); Most plug-in files don't require module-level initialization and cleanup. They use the empty startup and shutdown functions supplied by the SDK linker library. The startup function is called when the plug-in is first loaded by the host. The return value is the data passed to the activation and shutdown functions as the serverData argument. Returning NULL from the startup function indicates failure, so even if a module has no real server data, it should still return something. The module's shutdown function is called just before the host unloads the module. Any allocated server data should be freed at this point. Calling Convention Functions in the plug-in get called directly by the host, and this is a funky thing in some systems since they are different environments. The XCALL_ macro takes care of everything for all different systems and compilers, so these can be used to make multi-platform servers from a single source code. XCALL_ is used on the return type, e.g. XCALL_(int) for an external entry point returning an int. The activation function as well as any function pointers returned from the activation function need the XCALL treatment. Startup and Shutdown do not. |