If you've been following these tutorials from the start then you should have a "Gravity.p" plugin. This automatically bounces an object, either at a y value of zero or based on 2 nulls. When the object bounces, however, it does not deform. The aim of this tutorial is to introduce displacement maps by creating a plugin to deform our object. To use this download the tutorial files for this project and extract them to a new folder called "Squash". (The tutorial files for this tutorial are different from the previous ones.)

Displacement handlers and Displacement access

Again you will find a blank displacement map file included ready for you to create a Displacement Map plugin. To follow the tutorial crank up Visual C++ and open the workspace "Squash.dsw". Looking into the file "Squash.c" you will find a commented out copy of how the Lightwave SDK include files define the handler and access structure for a Displacement Map:

typedef struct st_DisplacementAccess {
   double           oPos[3];
   double           source[3];
} DisplacementAccess;
typedef struct st_DisplacementHandler {
   LWInstance      (*create) (LWError *, LWItemID);
   void            (*destroy) (LWInstance);
   LWError         (*copy) (LWInstance from, LWInstance to, LWItemID);
   LWError         (*load) (LWInstance, const LWLoadState *);
   LWError         (*save) (LWInstance, const LWSaveState *);
   LWError         (*newTime) (LWInstance, LWItemID, LWFrame, LWTime);
   void            (*evaluate) (LWInstance, DisplacementAccess *);
   unsigned int    (*flags) (LWInstance);
   const char *    (*descln) (LWInstance);
   const LWItemID* (*useItems) (LWInstance);
   void            (*changeID) (LWInstance, const LWItemID *);
} DisplacementHandler;

Much of this is identical to the Item Motion Plugins we've been looking at. The additional function that we need to define is "newTime". An Item Motion Handler's evaluate function is called for each new frame and contains time information. A Displacement Map is called for each point and does not contain time information. You must save this information in your instance using the "newTime" function. So we add time and frame parameters to our instance structure.

// Displacement Map instance structure.
typedef struct stDMINST{
    LWItemID id;
    LWTime time;
    LWFrame frame;
    int numpts;
    LWFrame firstframe,lastframe;
    int count;
    char desc[80];
    VECTOR *pts;
    int mode;
}DMINST;

The other elements are

• numpts: How many points in the object
• firstframe: First frame in the scene
• count: Used to follow which point we are currently displacing.
• pts: A pointer to an array of point values. The number of points is the duration times the number of points in the object

The newTime function

No rocket science here, just a few things to set:

// Newtime initialization.  For each new time and item we cache the
// time and the item ID.
    XCALL_(static LWError)
newtime(LWInstance inst,LWItemID id,LWFrame f,LWTime t)
{
    DMINST *dm;

    XCALL_INIT;
    dm = (DMINST *) inst;
    dm->frame=f;
    dm->time=t;
    dm->count=0;
    return (NULL);
}

Some displacement maps can operate using the limited information available via the Displacement Access pointer that is passed to the process function. But this information contains just the original location of a point, (as it would be in modeller) and the displaced position either in world or local coordinates. This is very little to use. Our sample scene "bounce4.lws" uses the Gravity plugin we created earlier to move the ball. By so doing if we used the Lightwave SDK function for Item Info param, and asked for position information it would report the position at frame zero, all through the scene. We need a way to get at the real information, our thechnique is to do a point scan. Frequently, when writing a Displacement map you will create memory for a set of points for the entire object and deform the object once per frame, possibly via the newTime function. In this plugin we go one step further we create an array of points for every point in the object for every frame. So we can calculate once and then display the result. This is convenient but not very interactive, to use this method for a useful plugin you should add an options box so that your plugin can be informed to recalculate the points array.

I'm getting very confused

OK, maybe we are rushing ahead here. How do we display an object in 3D? We define a set of points and polygons and let Lightwave do the rest. Displacement maps don't care two figs about polygons, Lightwave already knows about them, they care about points. If we move a point via our Displacement map then that is where it will appear. So we allocate memory for the position of all the points in the object for every frame in the scene.

//Global - functions===============================================
void CreatePointMemory(DMINST *dm){
    int dur,size;
    dur=dm->lastframe-dm->firstframe+1;
    size=dur*sizeof(VECTOR)*dm->numpts;
    dm->pts=(VECTOR*)malloc(size);
    if (!dm->pts) return;
    memset(dm->pts,0,size);
}

The reason we use memset to set everything to zero is that our VECTOR includes a set parameter. We want to know where Lightwave will put every point on every frame, if we do nothing. So the first step is to retrieve this information. When our process function is called with mode set to 0 (just created) or 2 (just loaded) it creates the point memory then waits for the user to either create a preview, which is guaranteed to go through every point, or use the play button. Every newTime the points are scanned to see if they have been set yet. When every point has been set we are ready to move them. Here's how the scan function looks

int PointScan(DMINST *dm){
    int f,i=1,total,count=0;
    total=(dm->lastframe-dm->firstframe+1)*dm->numpts;
    for (f=0;f<total;f++){
        if (!dm->pts[f].set){
            i=0;
            break;
        }
        count++;
    }
    return i;
}

Calculating the squash

The squash function is only called when we know where every point in our scene should be. But any deformations want to take place with respect to the centre of our object. We will step through the frames in our scene one by one. We find the current centre of the object in world coordinates and also the top and bottom points. Once we have this information we find the height and the adjusted new height. Then we set our point pointer to the first object point for the current frame:

void CalcSquash(DMINST *dm){
    int i,j,dur;
    double swell,top,bottom,height,deltaheight,newheight,minheight;
    VECTOR *pt,centre;
    dur=dm->lastframe-dm->firstframe+1;

    //Now we have everything we need to go through frame by frame
    for (i=0;i<dur;i++){
        //....and point by point
        //Find centre: zero first and get first point for frame
        //and find top and bottom
        centre.x=0.0; centre.y=0.0; centre.z=0.0;
        pt=&dm->pts[i*dm->numpts];
        top=pt->y; bottom=pt->y;
        for(j=0;j<dm->numpts;j++){
            centre.x+=pt->x;
            centre.y+=pt->y;
            centre.z+=pt->z;
            if (pt->y>top) top=pt->y;
            if (pt->y<bottom) bottom=pt->y;
            pt++;
        }
        centre.x/=dm->numpts;
        centre.y/=dm->numpts;
        centre.z/=dm->numpts;
        height=top-bottom;
        minheight=height*0.1;
        newheight=top*0.9+minheight;
        if (newheight<minheight) newheight=minheight;
        //Now we know the centre we can deform if necessary
        pt=&dm->pts[i*dm->numpts];

Now we must iterate through every point if the bottom has gone through y=0.0. (Note as provided the plugin will not work if the gravity plugin uses nulls). If bottom is above y then we need do nothing further as no deformation is required.

        for(j=0;j<dm->numpts;j++){
            //Adjust point and swell
            if (bottom<0){
                deltaheight=pt->y/height;
                if (deltaheight<0.0) deltaheight=0.0;
                swell=cos(deltaheight*HALF_PI)*MAX_SWELL;
                if (swell<1.0) swell=1.0;
                pt->x=(pt->x-centre.x)*swell+centre.x;
                pt->z=(pt->z-centre.z)*swell+centre.z;
                pt->y=deltaheight*newheight;
            }else break;
            pt++;
        }
    }
    //Everything went OK so let process do the work
    dm->mode=1;
}

If we need to deform then we use a bit of trig to generate a reasonable shape for the deformation. Remember trig functions work with radians, sin(0)=0, sin(PI/2)=1, cos(0)=1, cos(PI/2)=0. Using these functions we can smooth the ramp between not doing something and doing it. The only way to understand stuff like that is to play with the numbers. Try using a spreadsheets and playing with the data and perhaps charting it to get a better visualisation of the trig functions.

The process function

So the process function is quite simple. We are either scanning or setting. Scanning is terminated when every point has been scanned.

    XCALL_(static void)
process(LWInstance inst,DisplacementAccess *da)
{
    DMINST *dm;
    VECTOR *pt;

    XCALL_INIT;
    dm = (DMINST *) inst;
    if (dm->count>=dm->numpts) return;
    switch (dm->mode){
    case 2://Just loaded
    case 0://Just created
        if (dm->pts==NULL) CreatePointMemory(dm);
        if (dm->frame>=dm->firstframe && dm->frame<=dm->lastframe
            && dm->pts){
            //In range
            pt=&dm->pts[(dm->frame-dm->firstframe)*dm->numpts + dm->count];
            pt->x=da->source[0];
            pt->y=da->source[1];
            pt->z=da->source[2];
            pt->set=1;
            if (dm->count==0 && PointScan(dm)) CalcSquash(dm);
        }
        break;
    case 1://Ready to work with
        if (dm->frame>=dm->firstframe && dm->frame<=dm->lastframe
            && dm->pts){
            //In range
            pt=&dm->pts[(dm->frame-dm->firstframe)*dm->numpts + dm->count];
            da->source[0]=pt->x;
            da->source[1]=pt->y;
            da->source[2]=pt->z;
        }
        break;
    }
    dm->count++;
}

You may have found some of the code in this tutorial a little harder to follow. But, persevere. There is nothing quite so satisfying as the plugin that you have laboured over finally coming good. If you are unfamiliar with pointers then you will almost certainly crash the machine every now and then. Don't worry, we all do this. Try to remember to NULL a new pointer, free any memory you create, and never write beyond the boundaries of your memory allocation. If you remember those golden rules then you will be fine.

Summary

Now you've come to the end of this short series of tutorials. If they have spurred you on to write a plugin then please send me the results, or any comments you have that might enable me to improve the series. There is far more to learn but hopefully now you have a better idea where to look. Good luck with the plugins!!

Lesson 1 - Introduction, compiling your first plugin.
Lesson 2 - Loading, saving and options boxes.
Lesson 3 - Using bitmaps and callbacks in your options box.