### 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.