Compiling Globals Table of Contents

Common Elements

The 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;
className
A string containing the class of the plug-in. The class identifies what kind of plug-in this is, for example, "ItemMotionHandler" or "ImageSaver". See the Classes document for a complete list of class names and descriptions.
name
A string containing the name by which LightWave will uniquely identify your plug-in. This is the name LightWave uses internally and saves in scene and object files. It's also the name displayed to the user if the plug-in doesn't supply a list of userNames.
activate
The activation function.
userNames
An array of plug-in names in different languages. This is the name that will be displayed to your users in LightWave's interface. Each string contains a version of the name in a different language. The language is given by an associated code page identifier. This field is optional, as are the languages you choose to support.

The userNames field is an array of ServerUserName structures.

   typedef struct st_ServerUserName {
      const char *userName;
      long        langID;
   } ServerUserName;
userName
A string containing the locale-specific name of the plug-in. Japanese strings should be encoded as JIS on Windows and EUC on Unix.
name
A code indicating the language for the name string. A partial list:

0x0407 LANGID_GERMAN
0x0409 LANGID_USENGLISH
0x0809 LANGID_UKENGLISH
0x040a LANGID_SPANISH
0x040c LANGID_FRENCH
0x0410 LANGID_ITALIAN
0x0411 LANGID_JAPANESE
0x0419 LANGID_RUSSIAN
0x041D LANGID_SWEDISH

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 );
version
A class-specific version number. As development of LightWave continues, the interaction between the host and a given plug-in class is sometimes redefined. This number tells you, among other things, what version of the local data the host has passed.
global
A function that gives your plug-in access to services provided by the host and by Global class plug-ins. See the pages about the global function and Global plug-ins for more information.
local
Class-specific data.  Each plug-in class receives different data through this argument. For many classes, this points to a structure that the plug-in needs to fill. The host gets pointers to other functions in your plug-in this way. For interface class plug-ins (the interface counterpart of handler plug-ins), this argument is a pointer to the handler's own instance data, which the interface allows the user to modify.
serverData
The data pointer returned by the startup function. Unless you replaced the default startup function, you should ignore this argument. In particular, don't try to dereference the pointer, since on most systems it contains an invalid (although non-NULL) address.

The activation function returns a code that tells the host whether the plug-in was activated successfully.

AFUNC_BADVERSION
The version argument differs from what your plug-in supports. In some cases the host will try again with a lower version number.
AFUNC_BADGLOBAL
A call to the global function failed.
AFUNC_BADLOCAL
Your plug-in doesn't like something in the local data.
AFUNC_BADAPP
The host is a program you don't support.
AFUNC_OK
Return this when none of the other values is appropriate.

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.