Classes: MasterHandler

MasterHandler

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( long version, GlobalFunc *global,
      LWMasterHandler *local, void *serverData );

   typedef struct st_LWMasterHandler {
      LWInstanceFuncs *inst;
      LWItemFuncs     *item;
      int              type;
      double          (*event) (LWInstance, const LWMasterAccess *);
      unsigned int    (*flags) (LWInstance);
   } LWMasterHandler;

 

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. 

   XCALL_( int ) MyInterface( long version, GlobalFunc *global,
      LWInterface *local, void *serverData );

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

Sent when the item selection has changed.

LWEVNT_RENDER_DONE

Sent when a render has been completed.

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.

History

The LWEVNT_SELECT event code was added in LightWave 7.0. The LWEVNT_RENDER_DONE event code was added in LightWave 7.5.

Example

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