ObjReplacementHandler
ObjReplacementInterface

Availability  LightWave® 6.0
Component  Layout
Header  lwobjrep.h

Object replacement handlers are called at each time step to decide whether Layout should use a different object file to represent an object. An object's geometry might be replaced depending on its camera distance (level of detail replacement), or a time (object sequence loading), or some other criterion (previewing versus rendering, for example).

Object replacement can be used in combination with ObjectLoaders to perform procedural object animation. The replacement plug-in might write a brief description file for the parameters of a time step, which the object import server would then convert into a complete mesh during loading.

Handler Activation Function

   XCALL_( int ) MyObjReplace( int version, GlobalFunc *global,
      LWObjReplacementHandler *local, void *serverData );

The local argument to an object replacement's activation function is an LWObjReplacementHandler.

   typedef struct st_LWObjReplacementHandler {
      LWInstanceFuncs *inst;
      LWItemFuncs     *item;
      void            (*evaluate) (LWInstance, LWObjReplacementAccess *);
   } LWObjReplacementHandler;

The first two members of this structure are standard handler functions. The context argument to the inst->create function is the LWItemID of the item associated with this instance. An object replacement handler provides an evaluation function in addition to the standard handler functions.

evaluate( instance, access )

This is where the object replacement happens. The access structure passed to this function contains information about the currently loaded object and the evaluation time. You compare these and provide a new filename if a different object should be loaded. If the currently loaded geometry can be used for the new frame and time, set the new filename to NULL.

Interface Activation Function

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

This is the standard interface activation for handlers.

Object Replacement Access

The access structure is the data passed to the handler's evaluation function. All of the fields of this structure are read-only except for newFilename.

   typedef struct st_LWObjReplacementAccess {
      LWItemID    objectID;
      LWFrame     curFrame, newFrame;
      LWTime      curTime,  newTime;
      int         curType,  newType;
      const char *curFilename;
      const char *newFilename;
      int         force;
   } LWObjReplacementAccess;

objectID

Item ID of the object.

curFrame, curTime

The frame number and time at which the currently loaded object file was most recently evaluated.

newFrame, newTime

The evaluation frame and time. If you provide a new filename, this is the time at which that object file will be loaded. Because of network rendering, the new frame and time may not follow the curFrame and curTime values sequentially.

curType, newType

These describe the current geometry and the type needed for the new time. An object replacement handler might ignore the time values and only perform replacements when the types differ. The type can be

LWOBJREP_NONE

The current geometry for the object is a null object. This value only appears in curType.

LWOBJREP_PREVIEW

The object will be used during previewing and user interaction with the interface.

LWOBJREP_RENDER

The object will be used during rendering.

curFilename

The filename of the currently loaded object file. This will be NULL if the curType is LWOBJREP_NONE.

 

newFilename

If you want to replace the currently loaded object file, set this to the name of a different file. Set this to NULL if the object file shouldn't be changed. The memory that holds this string must persist after the evaluation function returns.

force (LW8.0+)

force object replacement even if filename or file contents have not changed

Example

The objseq sample lets the user select a list of files from a file dialog. It sorts the selected filenames and then replaces the object at frame 1 with the first file, at frame 2 with the second file, and so on.