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 nonzerokeep
value. LWT_TEST_REJECT
- Discard the last operation. The
end
callback is called with akeep
value of 0. LWT_TEST_CLONE
- Keep the last operation and begin a new one. The
end
callback is called with a nonzerokeep
value, and then thebuild
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 andaz
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.