Handlers
Formally, handlers are plug-in classes that manage persistent instance data through callbacks identified in the activation function. Handlers don't simply run and exit. They tell LightWave in their activation functions where they can be reached, and then they hang around, waiting for LightWave to call them.
Instance Functions
An instance is a block of data you create to describe a specific invocation of your handler plug-in. An ItemMotionHandler, for example, can be invoked for any number of items in the scene, and might even be invoked more than once for a given item, but for each slot it occupies, the plug-in will create and use an instance specifically for that item slot. The instance data is where the plug-in settings for that invocation are stored, and every one of the plug-in's callbacks receives this data as one of its arguments.
The instance callbacks are where your plug-in creates, destroys, copies, loads, saves and describes each instance data block. They're collected together in an LWInstanceFuncs structure which is part of the local data passed to your activation function. Your activation function needs to fill in this structure to tell LightWave where your instance callbacks are.
typedef struct st_LWInstanceFuncs { void *priv; LWInstance (*create) (void *priv, void *context, LWError *); void (*destroy) (LWInstance); LWError (*copy) (LWInstance, LWInstance from); LWError (*load) (LWInstance, const LWLoadState *); LWError (*save) (LWInstance, const LWSaveState *); const char * (*descln) (LWInstance); } LWInstanceFuncs;
priv
- Passed as the first argument to
create
. Set this to point to data you'd like yourcreate
function to have. instance = create( priv, context, error )
- Create an instance. Called, for example, when the user selects your plug-in on the
interface and when Layout loads a scene or an object file that refers to your plug-in.
Typically, you'll use
malloc
to allocate memory for a data structure, fill in some of the structure's fields with default values, and return the pointer to this structure.priv
is the same as thepriv
field of the LWInstanceFuncs structure and contains whatever your activation function put there. Thecontext
varies depending on the plug-in class, but this is often an item ID for the item this instance will be associated with. If you can't create an instance, seterror
to an error message string and return NULL. destroy( instance )
- Destroy an instance. Called, for example, when the user deselects your plug-in and when
the scene is cleared. Typically you'll free any memory and resources obtained in
create
when this instance was created. copy( dest, source )
- Copy the contents of the
source
instance todest
. If your instance data contains pointers, you may have to allocate memory for the pointer fields indest
. load( instance, loadstate )
- Read instance data from a file. LightWave provides an LWLoadState containing functions used to read the data. See the File I/O page.
save( instance, savestate )
- Write instance data to a file using the LWSaveState functions. See the File I/O page.
descln( instance )
- Provide a human-readable description of the instance data. This is a single string displayed to the user on the LightWave interface and should be short enough to fit there. It can contain anything, but typically it contains shorthand descriptions of the most important settings. This serves as a reminder to the user, who would otherwise have to open your plug-in's interface to check these settings.
Item Handler Extensions
Handler classes that work on items in the scene provide a pair of callbacks that allow them to manage dependencies on other items.
typedef struct st_LWItemFuncs { const LWItemID * (*useItems) (LWInstance); void (*changeID) (LWInstance, const LWItemID *); } LWItemFuncs;
idlist = useItems( instance )
- Returns an array of items this instance depends on. If your plug-in's behavior is
based on the parameters of other items (such as the positions of objects), you'll want to
be re-evaluated after those parameters change, and you use this function to inform Layout
of that. The array is terminated by
LWITEM_NULL
. The function can return NULL if the instance doesn't use any items. It can also returnLWITEM_ALL
to indicate that it wants to be evaluated after any change occurs. changeID( instance, idlist )
- Notification about a change in item IDs. This function is called if the IDs of items are
going to change for any reason. The null-terminated item array passed to this function is
of the form "old-1, new-1, old-2, new-2, ..." where the old ID is the value that
is changing and the new ID is its new value. Clients should be careful to renumber each
item only once.
The
changeID
callback may also be called when an item's data, such as the geometry of an object, has changed, and when called for this reason, the old and new item IDs will be the same.
Handlers with an LWItemFuncs in their local data are ordinarily called by Layout, but
some handler classes (currently image and pixel filters, shaders
and textures) can also be called by Modeler for
previewing. When called by Modeler, the LWItemFuncs pointer will be NULL. Handlers
must test the value of the LWItemFuncs pointer before attempting to fill in the useItems
and changeID
fields.
Render Handler Extensions
Certain handlers involved directly in rendering also provide callbacks for the start and end of a render session and the start of a new sampling pass.
typedef struct st_LWRenderFuncs { LWError (*init) (LWInstance, int); void (*cleanup) (LWInstance); LWError (*newTime) (LWInstance, LWFrame, LWTime); } LWRenderFuncs;
errormsg = init( instance, mode )
- Prepare the instance for a new rendering session. This is called before the first frame
of a rendering session is begun. The mode will be either
LWINIT_PREVIEW
orLWINIT_RENDER
. Returns a string containing an error message if an error occurs, otherwise returns NULL. cleanup( instance )
- Called after the last frame of a rendering session is completed.
errormsg = newTime( instance, frame, time )
- Called at the start of a new sampling pass. This may be called more than once for the same frame but for slightly different times. Returns an error message string or NULL.
Example
This activation function is for an environment handler. The local data includes both the item and render extensions. All of the names on the right side of the equals sign are functions your plug-in provides.
XCALL_( static int ) Handler( long version, GlobalFunc *global, LWEnvironmentHandler *local, void *serverData ) { if ( version != LWENVIRONMENT_VERSION ) return AFUNC_BADVERSION; local->inst->create = Create; local->inst->destroy = Destroy; local->inst->copy = Copy; local->inst->load = Load; local->inst->save = Save; local->inst->descln = Descln; if ( local->item ) { local->item->useItems = UseItems; local->item->changeID = ChangeID; } local->rend->init = Init; local->rend->cleanup = Cleanup; local->rend->newTime = NewTime; local->evaluate = Evaluate; local->flags = Flags; return AFUNC_OK; }
The Interface Class
Each handler class has an associated interface class with its own activation function. As mentioned in the server description documentation, LightWave matches handlers with their interfaces by finding matching name strings in the ServerRecord array for a plug-in file.
The interface activation function receives the instance data as the first field of an
LWInterface structure. This is the pointer returned by the handler's create
function. The interface activation fills in the other fields of the LWInterface to tell
LightWave how the plug-in wants its interface to be presented to the user.
typedef struct st_LWInterface { LWInstance inst; LWXPanelID panel; LWError (*options) (LWInstance); LWError (*command) (LWInstance, const char *); } LWInterface;
inst
- An instance returned by the handler's
create
function. This is read-only. panel
- An xpanel containing the controls for a user interface. The xpanel is created by calling
the functions returned by the XPanels global. If this is
NULL, LightWave will use the
options
callback instead. Some classes receive real estate on LightWave's panels for displaying their non-modal xpanel interfaces, so for those classes, the plug-in's interface is "always on," rather than being explicitly invoked by the user. error = options( instance )
- A callback that typically displays a modal panel. This is equivalent to the way the
interface activation function itself worked in versions of LightWave prior to 6.0.
LightWave calls this whenever the user explicitly opens the interface for the associated
handler, often by double-clicking on the handler's name in a list. If
options
is NULL, LightWave uses thepanel
to display the plug-in's interface. (Exactly one of thepanel
andoptions
fields should be non-NULL.) error = command( instance, cmdstring )
- A callback that processes batch commands. This isn't used in LightWave 6.0 and can safely be set to NULL.
Example
The avisave sample plug-in uses the options
function to display the standard Windows codec selection dialog. This is also the approach
to take if you're going to display a classic panels
interface.
XCALL_( int ) Interface( long version, GlobalFunc *global, LWInterface *local, void *serverData ) { if ( version != LWINTERFACE_VERSION ) return AFUNC_BADVERSION; local->panel = NULL; local->options = Options; local->command = NULL; return AFUNC_OK; }
Options
uses the Win32 ICCompressorChoose
function to display the
dialog. The window handle of Layout's main window, obtained from the Host Display Info global, is passed as the parent
window for the dialog.
XCALL_( static LWError ) Options( SampleAVI *avi ) { ... result = ICCompressorChoose( hdi->window, ICMF_CHOOSE_ALLCOMPRESSORS, NULL, NULL, &cv, "SampleAVI Options" ); ... return NULL; }
The NoisyChan sample creates an LWXP_VIEW
xpanel that draws its controls in the lower right
corner of Layout's graph editor window.
XCALL_( static int ) NoisyChannel_UI( long version, GlobalFunc *global, LWInterface *UI, void *serverData ) { if ( version != LWINTERFACE_VERSION ) return AFUNC_BADVERSION; GGlobal = global; UI->panel = NoisyXPanel( global, UI->inst ); UI->options = NULL; UI->command = NULL; return AFUNC_OK; }
The NoisyXPanel
function creates the xpanel.
LWXPanelID NoisyXPanel( GlobalFunc *global, NoisyData *dat ) { LWXPanelFuncs *lwxpf = NULL; LWXPanelID panID = NULL; static LWXPanelHint hint[] = { XpLABEL(0,"Noisy Channel"), XpEND }; lwxpf = (LWXPanelFuncs*)(*global)( LWXPANELFUNCS_GLOBAL, GFUSE_TRANSIENT ); if ( lwxpf ) { panID = (*lwxpf->create)( LWXP_VIEW, ctrl_list ); if ( panID ) { (*lwxpf->hint) ( panID, 0, hint ); (*lwxpf->describe)( panID, data_descrip, NoiseData_get, NoiseData_set ); (*lwxpf->viewInst)( panID, dat ); (*lwxpf->setData) ( panID, 0, dat); } } return panID; }