Classes: ItemMotionHandler

ItemMotionHandler
ItemMotionInterface

Availability  LightWave 6.0
Component  Layout
Header  lwmotion.h

Motion handlers apply procedural translation, rotation and scaling to an item. They can be associated with any item in a scene that can be keyframed (objects, lights, cameras, bones).

Handler Activation Function

   XCALL_( int ) MyItemMotion( long version, GlobalFunc *global,
      LWItemMotionHandler *local, void *serverData );

The local argument to a motion handler's activation function is an LWItemMotionHandler.

   typedef struct st_LWItemMotionHandler {
      LWInstanceFuncs *inst;
      LWItemFuncs     *item;
      void            (*evaluate)(LWInstance, const LWItemMotionAccess *);
      unsigned int    (*flags)   (LWInstance);
   } LWItemMotionHandler;

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.

In addition to the standard handler functions, a motion handler provides an evaluation function and a flags function.

evaluate( instance, access )

This is where the motion handler does its work. LightWave calls the evaluation function at every point in the animation at which an item's motion parameters need to be calculated. The access structure, described below, tells you the item being animated and the frame and time of the evaluation, and provides functions to set motion parameters for the current time and to get the item's motion parameters for any time.

f = flags( instance )

Returns an integer containing flags combined using bitwise-or. Currently the only flag is LWIMF_AFTERIK, which specifies that the plug-in will be evaluated after LightWave has performed the inverse kinematics calculations for the item.

Interface Activation Function

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

The interface activation's local data is the standard interface structure for handlers.

Motion Access

The evaluation function receives an LWItemMotionAccess structure. The data members are read-only. The functions provide the means to get and set motion parameters.

   typedef struct st_LWItemMotionAccess {
      LWItemID  item;
      LWFrame   frame;
      LWTime    time;
      void     (*getParam) (LWItemParam, LWTime, LWDVector);
      void     (*setParam) (LWItemParam, const LWDVector);
   } LWItemMotionAccess;

item

The ID for the item to be affected by the procedural motion.

frame

The frame number at which the motion should be evaluated.

time

The animation time for which the motion should be evaluated.

getParam( param, lwtime, vec )

Returns a motion parameter for the item at any given time. Only the LWIP_POSITION, LWIP_ROTATION and LWIP_SCALING parameters may be queried.

setParam( param, vec )

Used by the evaluation function to set the computed motion of the item at the current time. Only the LWIP_POSITION, LWIP_ROTATION and LWIP_SCALING parameters may be set.

Example

If you want to modify an item's motion, rather than completely replace it, call getParam for the current time to find out what the item's unmodified motion would be, then calculate a new motion based on that and call setParam.

   XCALL_( static void )
   Evaluate( MyInstance *inst, const LWItemMotionAccess *access )
   {
      LWDVector pos;

      access->getParam( LWIP_POSITION, access->time, pos );
      ...do something to pos[]...
      access->setParam( LWIP_POSITION, pos );
   }

The kepler sample is a motion handler that moves an item in an elliptical orbit