MeshEditTool

Availability  LightWave 6.0
Component  Modeler
Header  lwmodtool.h, lwtool.h

Mesh edit tools are interactive versions of MeshDataEdit plug-ins. For users they behave like Modeler's built-in tools. You supply callbacks for drawing the tool, for creating "handles" that can be manipulated by the user, and for generating the geometry the tool creates or modifies.

Activation Function

   XCALL_( int ) MyMETool( long version, GlobalFunc *global,
      LWMeshEditTool *local, void *serverData );

The local argument to a mesh edit plug-in's activation function is an LWMeshEditTool.

   typedef struct st_LWMeshEditTool {
      LWInstance   instance;
      LWToolFuncs *tool;
      int         (*test)  (LWInstance);
      LWError     (*build) (LWInstance, MeshEditOp *);
      void        (*end)   (LWInstance, int keep);
   } LWMeshEditTool;

instance

Set this to point to your instance data. Typically this is a structure that holds all of the data your plug-in needs to perform its function.

tool

A set of tool callbacks you need to define. See below.

action = test( inst )

Returns a code for the edit action that should be performed. The action can be one of the following.

LWT_TEST_NOTHING

Do nothing. The edit state remains unchanged.

LWT_TEST_UPDATE

Reapply the operation with new settings. The build function will be called.

LWT_TEST_ACCEPT

Keep the last operation. The end callback is called with a nonzero keep value.

LWT_TEST_REJECT

Discard the last operation. The end callback is called with a keep value of 0.

LWT_TEST_CLONE

Keep the last operation and begin a new one. The end callback is called with a nonzero keep value, and then the build function is called again.

lwerr = build( inst, edit )

Perform the tool's mesh edit operation. A tool that creates a primitive would add the points and polygons of the primitive within this callback. The edit argument points to the same MeshEditOp structure passed to MeshDataEdit plug-ins.

end( inst, keep )

Clear the state when the last edit action is completed. This can be a result of a call to test, or it can be triggered by an external action.

Tool Functions

Your plug-in fills in an LWToolFuncs structure to tell Modeler where your tool callbacks are located.

   typedef struct st_LWToolFuncs {
      void         (*done)   (LWInstance);
      void         (*draw)   (LWInstance, LWWireDrawAccess *);
      const char * (*help)   (LWInstance, LWToolEvent *);
      int          (*dirty)  (LWInstance);
      int          (*count)  (LWInstance, LWToolEvent *);
      int          (*handle) (LWInstance, LWToolEvent *, int i,
                                LWDVector pos);
      int          (*start)  (LWInstance, LWToolEvent *);
      int          (*adjust) (LWInstance, LWToolEvent *, int i);
      int          (*down)   (LWInstance, LWToolEvent *);
      void         (*move)   (LWInstance, LWToolEvent *);
      void         (*up)     (LWInstance, LWToolEvent *);
      void         (*event)  (LWInstance, int code);
      LWXPanelID   (*panel)  (LWInstance);
   } LWToolFuncs;

done( instance )

Destroy the instance. Called when the user discards the tool.

draw( instance, draw_access )

Display a wireframe representation of the tool in a 3D viewport using the drawing functions in the LWWireDrawAccess, described below.

helptext = help( instance, eventinfo )

Returns a text string to be displayed as a help tip for this tool.

dcode = dirty( instance )

Returns flag bits indicating whether the wireframe or the help string need to be refreshed. The bits are combined using bitwise-or. Return 0 if nothing needs to be refreshed, or any combination of the following.

LWT_DIRTY_WIREFRAME

LWT_DIRTY_HELPTEXT

nhandles = count( instance, eventinfo )

Returns the number of handles. A "handle" is a component of the tool's wireframe that the user can move independently. If this returns 0, then the start callback is used to set the initial handle point.

priority = handle( instance, eventinfo, hnum, pos )

Returns the 3D location and priority of handle hnum, or 0 if the handle is currently invalid. Handles have a "pick size," a region on the screen in which a mouse click will select it. They also have a rank used to choose among handles that overlap. When the priority is positive, the handle has a small fixed size, and when it's negative, the handle has an infinite size. The absolute value of the priority is the relative rank of a handle (handles of rank 1 are picked first). Fixed size handles always take precedence over infinite ones.

hnum = start( instance, eventinfo )

Take an initial mouse-down position and return the index of the handle that should be dragged.

hdrag = adjust( instance, eventinfo, hnum )

Drag the handle to a new location. Returns the index of the handle that should continue being dragged (typically the same as hnum).

domouse = down( instance, eventinfo )

Process a mouse-down event. If this function returns 0, handle processing will be done instead of raw mouse event processing.

move( instance, eventinfo )

Process a mouse-move event. This will only be called if the down function returned a nonzero value.

up( instance, eventinfo )

Process a mouse-up event. This will only be called if the down function returned a nonzero value.

event( instance, code )

Process a general event indicated by one of the following codes.

LWT_EVENT_DROP

The tool has been dropped. The user has clicked on an empty area of the interface, or pressed the spacebar, or selected another tool.

LWT_EVENT_RESET

The user has requested that the tool return to its initial state. Numeric parameters should be reset to their default values.

LWT_EVENT_ACTIVATE

The tool has been activated.

xpanel = panel( instance )

Create an LWXP_VIEW xpanel for the tool instance.

Event Information

Most of the tool functions take an LWToolEvent as an argument.

   typedef struct st_LWToolEvent {
      LWDVector posRaw, posSnap;
      LWDVector deltaRaw, deltaSnap;
      LWDVector axis;
      LWDVector ax, ay, az;
      double    pxRaw, pxSnap;
      double    pyRaw, pySnap;
      int       dx, dy;
      int       portAxis;
      int       flags;
   } LWToolEvent;

posRaw, posSnap

The event position in 3D space. The snap vector is the raw vector after quantizing to the nearest grid intersection in 3D.

deltaRaw, deltaSnap

The vector from the initial mouse-down event to the current event location. This is just the difference between the initial and current positions.

axis

The event axis. All the points under the mouse location are along this axis through pos.

ax, ay, az

Screen coordinate system. ax points to the right, ay points up and az points into the screen. Movement by 1.0 along each vector corresponds to approximately one pixel of screen space movement.

pxRaw, pxSnap
pyRaw, pySnap

Parametric translation values. These are the mouse offsets converted to values in model space. They provide a method for computing abstract distance measures from left/right and up/down mouse movement roughly scaled to the magnification of the viewport..

dx, dy

Screen movement in pixels. This is the total raw mouse offset from the starting position.

portAxis

The view type. 0, 1 or 2 for orthogonal views, or -1 for perspective views.

flags

This contains flag bits assembled using bitwise-or. It can be some combination of the following.

LWTOOLF_CONSTRAIN

The action of the tool is constrained. Activated by a standard key or mouse combination.

LWTOOLF_CONS_X
LWTOOLF_CONS_Y

The direction of constraint for orthogonal moves. Initially neither bit is set, but as the user moves enough to select a primary direction, one or the other will be set.

LWTOOLF_ALT_BUTTON

Alternate mouse button event, usually the right button.

LWTOOLF_MULTICLICK

Multiple mouse click event.

Draw Access

The draw callback is given an LWWireDrawAccess containing a set of drawing functions for rendering the visual representation of the tool in the interface.

   typedef struct st_LWWireDrawAccess {
      void  *data;
      void  (*moveTo) (void *, LWFVector, int);
      void  (*lineTo) (void *, LWFVector, int);
      void  (*spline) (void *, LWFVector, LWFVector, LWFVector, int);
      void  (*circle) (void *, double, int);
      int    axis;
      void  (*text)   (void *, const char *, int);
      double pxScale;
   } LWWireDrawAccess;

data

An opaque pointer to data used by Modeler. Pass this as the first argument to the drawing functions.

moveTo( data, pos, line_style )

Move the drawing point to the new position. Use this to set one endpoint of a line or a spline or the center of a circle. The third argument sets the line style for the drawing functions and can be one of the following.

LWWIRE_SOLID

LWWIRE_DASH

lineTo( data, pos, coord_type )

Draw a line segment from the current drawing point to the given position. The coordinate type can be one of the following.

LWWIRE_ABSOLUTE

Absolute coordinates in model space.

LWWIRE_RELATIVE

Relative coordinates in model space. The pos argument is an offset from the current drawing point, which is the most recent position specified in a previous call to a drawing function.

LWWIRE_SCREEN

Relative coordinates in screen space. A distance of 1.0 in this coordinate system corresponds to about 20 pixels. Tool handles will typically be drawn in screen space, so that they remain the same displayed size regardless of the zoom level of the view.

spline( data, LWFVector, LWFVector, LWFVector, coord_type )

Draw a curve from the current drawing point. The vectors are Bezier control points, with the current drawing point acting as the first of the required four points. When using relative coordinates, each position vector is an offset from the previous one.

circle( data, radius, coord_type )

Draw a circle centered at the current drawing point.

axis

The view in which you're drawing. This can be 0, 1 or 2 for the x, y and z axis views, or -1 for a perspective view.

text( data, textline, justify )

Draw a single line of text. The justify argument positions the text relative to the current drawing point and can be one of the following.

LWWIRE_TEXT_L
LWWIRE_TEXT_C
LWWIRE_TEXT_R

pxScale

The approximate size of a pixel in the current view.

History

In LightWave 7.0, the text function and the pxScale field were added to LWWireDrawAccess, but LWMESHEDITTOOL_VERSION was not incremented. If your activation accepts a version of 4, use the Product Info global to determine whether these items are available.

Example

The boxes/box4 sample is a simple example of a mesh edit tool. It's described in the Boxes tutorial. The mesh edit tool samples also include capsule, which creates a capsule shaped primitive, superq for making ellipsoidal and toroidal superquadrics, and spikeytool for adding spikes during subdivision.