DisplacementHandler
DisplacementInterface

Availability  LightWave® 6.0
Component  Layout
Header  lwdisplce.h

Displacement plug-ins deform objects by moving their points at each time step.

Handler Activation Function

   XCALL_( int ) MyDisplacement( int version, GlobalFunc *global,
      LWDisplacementHandler *local, void *serverData );

The local argument to a displacement plug-in's activation function is an LWDisplacementHandler.

   typedef struct st_LWDisplacementHandler {
      LWInstanceFuncs *inst;
      LWItemFuncs     *item;
      LWRenderFuncs   *rend;
      void            (*evaluate) (LWInstance, LWDisplacementAccess *);
      unsigned int    (*flags)    (LWInstance);
   } LWDisplacementHandler;

The first three members of this structure are the standard handler functions. The context argument to the inst->create function is the LWItemID of the object associated with this instance.

In addition to the standard functions, a displacement plug-in provides an evaluation function and a flags function.

evaluate( instance, access )

This is where the displacement happens. At each time step, the evaluation function is called for each vertex in the object. The position of the vertex is examined and modified through the access structure described below.

f = flags( instance )

Returns bit flags combined using bitwise-or. The following flags tell Layout whether the displacement will be in world coordinates and whether it should occur after morphing, or before or after the object has been deformed by bones.
Only one of these flags should be set.

LWDMF_WORLD
LWDMF_BEFOREBONES
LWDMF_AFTERMORPH

Another flag specifies if a per vertex normal is needed, only if this flag is returned, the wNorm member of LWDisplacementAccess will be filled with valid data.

LWDMF_NEED_NORMALS

Interface Activation Function

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

This is the standard interface activation for handlers.

Displacement Access

The LWDisplacementAccess passed to the evaluation function contains two point positions, the point ID, and a mesh info for the object the point belongs to.

   typedef struct st_LWDisplacementAccess {
      LWDVector    oPos;
      LWDVector    source;
      LWPntID      point;
      LWMeshInfo  *info;
      LWDVector    wNorm;      
   } LWDisplacementAccess;

oPos

The original point location in object coordinates. This is read-only.

source

The location to be transformed in place by the displacement. If the flags function returned the LWDMF_WORLD bit, the source is in world coordinates and has already been modified by morphing, bones and object motion. Otherwise the source is in object coordinates (after morphing, before item motion, and before or after bone effects, depending on whether the flags function returned LWDMF_BEFOREBONES).

point

The point ID. This can be used to retrieve other information about the point from the mesh info structure.

info

A mesh info structure for the object.

wNorm

The average normal of the polygon normals of the polygons surrounding the currently evaluated vertex. This member will only be filled with valid data when the LWDMF_NEED_NORMALS flag has been specified.

History

In LightWave® 7.0, LWDISPLACEMENT_VERSION was incremented to 5. This reflects additions to the LWMeshInfo structure, but in all other respects, displacement handlers were unchanged.

Example

The inertia sample is a displacement handler that causes points to "lag behind" as the object moves. This plug-in was formerly known as LazyPoints.