LayoutTool MeshDataEdit Classes Table of Contents

MasterHandler

Availability  LightWave® 6.0
Component  Layout
Header  lwmaster.h

Masters can issue commands like generics, but unlike generics, masters can respond to the user's changes to a scene as the scene is being composed. Masters are handlers, so they have persistent instances that can be saved in scene files. Masters can be used to record a sequence of commands for scripting or as a central point of control for a suite of handler plug-ins.

Activation Function 

   XCALL_( int ) MyMaster( int version, GlobalFunc *global,
      LWMasterHandler *local, void *serverData );
The local argument to a master's activation function is an LWMasterHandler. 
   typedef struct st_LWMasterHandler {
      LWInstanceFuncs *inst;
      LWItemFuncs     *item;
      int              type;
      double          (*event) (LWInstance, const LWMasterAccess *);
      unsigned int    (*flags) (LWInstance);
   } LWMasterHandler;
The first two members of this structure point to standard handler functions. In addition to these, a master handler provides a type code, an event function and a flags function.
 
type
This can be one of the following.
 
LWMAST_SCENE
LWMAST_OBJECTS
LWMAST_EFFECTS

LWMAST_LAYOUT
The SCENE type is the most common. OBJECTS and EFFECTS types are reserved for future enhancement of the class. LAYOUT masters are like SCENE masters, but they survive scene clearing and can therefore be used to automate scene management.
val = event( instance, access )
The event function is called to notify the handler that something has happened. Information about the event is included in the access structure, described below. The handler can respond to the event by issuing commands through functions provided in the access structure. The return value is currently ignored and should be set to 0.

f = flags( instance )
Returns flag bits combined using bitwise-or. No flags are currently defined, so this function should simply return 0. 
Interface Activation Function 
   XCALL_( int ) MyInterface( int version, GlobalFunc *global,
      LWInterface *local, void *serverData );
This is the standard interface activation for handlers.

Master Access

This is the structure passed to the handler's event function.  

   typedef struct st_LWMasterAccess {
      int            eventCode;
      void          *eventData;
      void          *data;
      LWCommandCode (*lookup)   (void *, const char *cmdName);
      int           (*execute)  (void *, LWCommandCode cmd, int argc,
                                   const DynaValue *argv,
                                   DynaValue *result);
      int           (*evaluate) (void *, const char *command);
   } LWMasterAccess;
eventCode
eventData
The type of event and its associated data. The event can be one of the following.
LWEVNT_NOTHING
Not currently used.
LWEVNT_COMMAND
A user action corresponding to a command. The eventData is a string containing the command and its arguments, written in the same format used by the evaluate function to issue commands.
LWEVNT_TIME
Sent whenever the frame slider is moved, which includes playing the scene, but not playing back a preview. This allows masters to remain synchronized in time with the Layout interface.
LWEVNT_SELECT (LW7.0+)
Sent when the item selection has changed.
LWEVNT_RENDER_DONE (LW7.5+)
Sent when a render has been completed.

There are some new event codes available to master handlers via the event callback. These will only appear when the 'flags' callback returns the correct flags. These new events can occur in ScreamerNet as well as Layout. The flags available are:

LWMASTF_LAYOUT
This flag signals that this master handler should be considered a layout level plugin instead of a scene level plugin for the purposes of saving handler data.
LWMASTF_RECEIVE_NOTIFICATIONS
This flag signals that this master handler wants to receive LWEVNT_NOTIFY_ events.
LWMASTF_RECEIVE_NOTIFICATIONS_MESHPOINTS
This flag signals that this master handler wants to receive the LWEVNT_NOTIFY_MESHPOINTS_ALTERED event. It is necessary to specify the LWMASTF_RECEIVE_NOTIFICATIONS flag as well, in this case.

When the LWEVNTF_RECEIVE_NOTIFICATIONS flag is returned, the following events will be received:

LWEVNT_NOTIFY_MOTION_UPDATE_STARTING
This indicates item motion is about to be computed. 'eventData' is the item id being affected or LWITEM_NULL for all items. This will be received during mouse manipulation of an item as well.
LWEVNT_NOTIFY_MOTION_UPDATE_COMPLETE
This indicates item motion is done being computed. 'eventData' is the item id being affected or LWITEM_NULL for all items. This will be received during mouse manipulation of an item as well. This notification is also useful to indicate that all meshes are in their final position. So, the MeshInfo::pntOtherPos() values are valid at this point. The pntOtherPos() values do not include any transformations of the mesh's owner such as item position, rotation, and shearing.
LWEVNT_NOTIFY_MESH_REPLACED
This indicates an object's mesh source has been replaced. This is a more drastic mesh change than just transforming an existing mesh by displacement. 'eventData' is the item id the object whose mesh has changed.
LWEVNT_NOTIFY_MESH_UPDATE_STARTING
This indicates a single mesh is about to be transformed. 'eventData' is the object item id being affected. This does not mean that the mesh is actually going to change from its current shape, however. MeshInfo::pntOtherPos() values are not valid at this point.
LWEVNT_NOTIFY_MESH_UPDATE_AFTERMORPHING
This indicates a mesh vertexes represent their 'after morphing' positions. 'eventData' is an item id. MeshInfo::pntOtherPos() values may be used.
LWEVNT_NOTIFY_MESH_UPDATE_AFTERBONES
indicates a mesh vertexes represent their 'after bones' positions. 'eventData' is an item id. MeshInfo::pntOtherPos() values may be used.
LWEVNT_NOTIFY_MESH_UPDATE_AFTERLOCALDISPLACEMENTS
indicates a mesh vertexes represent their 'after local displacements' positions. 'eventData' is an item id. MeshInfo::pntOtherPos() values may be used.
LWEVNT_NOTIFY_MESH_UPDATE_AFTERMOTION
indicates a mesh vertexes represent their 'after motion' positions. 'eventData' is an item id. MeshInfo::pntOtherPos() values may be used.
LWEVNT_NOTIFY_MESH_UPDATE_COMPLETE
This indicates a single mesh is done being transformed. 'eventData' is the object item id that was affected. This does not mean that the mesh was actually altered from its previous shape.
LWEVNT_NOTIFY_RENDER_FRAME_STARTING
This indicates a frame is about to be rendered. 'eventData' is the time being rendered.
LWEVNT_NOTIFY_RENDER_FRAME_COMPLETE
This indicates a frame has completed being rendered. 'eventData' is the time being rendered.
LWEVNT_NOTIFY_RENDER_STARTING
This indicates a sequence of frames are about to be rendered.
LWEVNT_NOTIFY_RENDER_ABORTED
This indicates that the "Abort" action was engaged by the user (either by pressing the button, or the Escape key) during a render. This event will always be followed by LWEVNT_NOTIFY_RENDER_COMPLETE.
LWEVNT_NOTIFY_RENDER_COMPLETE
This indicates a sequence of frames has completed being rendered.
LWEVNT_NOTIFY_SCENE_CLEAR_STARTING
This indicates a scene is about to be cleared. Of course, an existing master handler needs to exist to detect this. 'eventData' is the name of the scene before it was cleared.
LWEVNT_NOTIFY_SCENE_CLEAR_COMPLETE
This indicates a scene has just been cleared. Only a master handler that survives a scene clear (LAYOUT type) will still be around to detect this. 'eventData' is the name of the scene as it exists as a cleared scene.
LWEVNT_NOTIFY_SCENE_LOAD_STARTING
This indicates a scene is about to be loaded. 'eventData' is the name of the scene file being loaded. If you wish to retain this name, you must make a copy of it.
LWEVNT_NOTIFY_SCENE_LOAD_COMPLETE
This indicates a scene has just been loaded. 'eventData' is the name of the scene file that was loaded. If you wish to retain this name, you must make a copy of it.
LWEVNT_NOTIFY_SCENE_SAVE_STARTING
This indicates a scene is about to be saved. 'eventData' is the name of the scene being saved. If you wish to retain this name, you must make a copy of it.
LWEVNT_NOTIFY_SCENE_SAVE_COMPLETE
This indicates a scene has just been saved. 'eventData' is the name of the scene file that was saved. If you wish to retain this name, you must make a copy of it.
LWEVNT_NOTIFY_ITEM_ADDED
This indicates an item has been added. An item is considered an object, light, camera, or bone; null items and objects. 'eventData' is the item id that was added.
LWEVNT_NOTIFY_ITEM_REMOVING
This indicates an item is about to be removed. 'eventData' is the item id that is going to be removed.
LWEVNT_NOTIFY_ITEM_REPARENTED
This indicates an item's parent has changed. 'eventData' is the item id that had its parent changed.
LWEVNT_NOTIFY_SURFACE_ALTERED
This indicates a surface was altered in some way. 'eventData' is a SurfID
LWEVNT_NOTIFY_MESHPOINTS_ALTERED
This indicates a change to the world position of a vertex in an object was altered. 'eventData' is an item ID. The world vertex position can be altered by simple movement or rotation as well. By looking for constant movement and orientation, one can rule out those as being the cause of the alteration.
LWEVNT_NOTIFY_PLUGIN_CHANGED
This indicates the state of a plugin was changed. 'eventData' is a pointer to a structure containing information about the change: 
typedef struct st_LWEventNotifyPluginChange
{
    const char *classname;
    const char *servername;
    unsigned int pluginevent;
} LWEventNotifyPluginChange;
The class and server names are the class and server name of the plugin. The plugin event code is one of:
LWEVNT_PLUGIN_UPDATED
The plugin indicated a change in its instance data through the instance update global.
LWEVNT_PLUGIN_CREATED
A plugin instance was created.
LWEVNT_PLUGIN_DESTROYED
A plugin instance was destroyed.
LWEVNT_PLUGIN_ENABLED
A plugin instance was enabled.
LWEVNT_PLUGIN_DISABLED
A plugin instance was disabled.
LWEVNT_PLUGIN_DESTROYING
A plugin instance is about to be destroyed.
LWEVNT_NOTIFY_TEXTURE_REMOVING
This indicates a texture is about to be removed from a surface. 'eventData' is the LWTextureID that is going to be removed.
LWEVNT_NOTIFY_TEXTURE_ALTERED
This indicates a texture was altered in some way. 'eventData' is a LWTextureID
LWEVNT_NOTIFY_IMAGE_REMOVING
This indicates an image item is about to be removed. 'eventData' is the LWImageID that is going to be removed.
LWEVNT_NOTIFY_IMAGE_ALTERED
This indicates a clip from the clip editor was altered in some way. 'eventData' is a LWImageID. The alteration is something that would affect the images generated by the clip settings including a complete replacement of the clip image.
LWEVNT_NOTIFY_LIST_UPDATE_OBJECTS
This event indicates that the order of objects in Layout's internal list has been altered in some way. 'eventData' is unused.
LWEVNT_NOTIFY_LIST_UPDATE_LIGHTS
This event indicates that the order of lights in Layout's internal list has been altered in some way. 'eventData' is unused.
LWEVNT_NOTIFY_LIST_UPDATE_CAMERAS
This event indicates that the order of cameras in Layout's internal list has been altered in some way. 'eventData' is unused.
LWEVNT_NOTIFY_LIST_UPDATE_BONES
This event indicates that the order of bones belonging to a Layout object has been altered in some way. 'eventData' is the LWItemID of the parent object.
data
An opaque pointer to data used internally by Layout. Pass this as the first argument to the lookup, execute and evaluate functions.
cmdcode = lookup( data, cmdname )
Returns an integer code corresponding to the command name. The command is issued by passing the command code to the execute function. Command codes are constant for a given Layout session, so this only needs to be called once per command, after which the codes can be cached and used multiple times.
result = execute( data, cmdcode, argc, argv, cmdresult )
Issue the command given by the command code argument. argv is an array of DynaValue arguments. argc is the number of arguments in the argv array. The result of the command is written in cmdresult. The function returns 1 if it succeeds or 0 if it does not.
result = evaluate( data, cmdstring )
Issue the command with the name and arguments in the command string. This is an alternative to using lookup and execute. The command and its arguments are written to a single string and delimited by spaces. The function returns 1 if it succeeds or 0 if it does not.
See the Commands pages for a complete list of the commands that can be issued in Layout, as well as a detailed explanation of the formatting of command arguments for both the execute and evaluate methods.

Example

The macro sample is a master that records a sequence of commands and saves it as an LScript.