MeshDataEdit

Availability LightWave 6.0 | Component Modeler | Header lwmeshedt.h

Mesh edit plug-ins create and modify geometry at the point and polygon level. This class is a subset of the CommandSequence class, which provides access to both mesh editing and commands, and of the MeshEditTool class, an interactive version of MeshDataEdit.

Activation Function

   XCALL_( int ) MyMeshEdit( long version, GlobalFunc *global,
      MeshEditBegin *local, void *serverData );

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

   typedef MeshEditOp *
      MeshEditBegin (int pntBuf, int polBuf, EltOpSelect);

This function returns a MeshEditOp structure containing the mesh editing functions. It can be called only once for each activation.

The MeshEditBegin function can allocate a user data buffer for each point and polygon. This is memory you can use to store per-point and per-polygon information during the edit. Modeler automatically frees these buffers when the edit is completed. The pntBuf and polBuf arguments set the sizes of the buffers.

EltOpSelect

When the edit begins, Modeler sets a selection flag for each point and polygon. The EltOpSelect code determines which geometry is flagged as selected, and it can be one of the following.

OPSEL_GLOBAL: All elements, whether or not they're selected by the user.
OPSEL_USER: Only those elements selected by the user. This includes the implicit selection of all elements when nothing is explicitly selected, and selections by volume.
OPSEL_DIRECT: Elements selected directly with the point or polygon selection tools. This applies to both points and polygons regardless of which is currently active in the interface.
OPSEL_MODIFY: This activates a special mesh edit mode that can change the selection state of specific points and polygons. The mesh editing functions for adding and changing geometry aren't available in this mode, but the query functions can be used. The selection state of a point or polygon is modified by calling the MeshEditOp pntSelect or polSelect functions, typically within a pointScan or polyScan callback. OPSEL_MODIFY must be combined with one of the other selection modes in the MeshEditBegin call.

EltOpLayer

Many of the MeshEditOp functions operate on a specific set of layers, and these are identified by an EltOpLayer code.

OPLYR_PRIMARY: The primary layer. This is the single active layer affected by mesh edits, normally the lowest numbered foreground layer.
OPLYR_FG: Foreground layers, which are active and displayed.
OPLYR_BG: Background layers, which are inactive but still displayed.
OPLYR_SELECT: Both foreground and background layers.
OPLYR_ALL: All layers in the Modeler system whether they contain data or not.
OPLYR_EMPTY: Empty layers are those that contain no geometry.
OPLYR_NONEMPTY: Non-empty layers are any layers which contain some data (the complement of OPLYR_EMPTY).
Individual Layers: In addition to the defined values, codes starting at 101 (for layer 1) can be used to select the individual layers by number.

Error Codes

Most of the mesh edit functions return an error state defined by one of the following codes. One of these is also passed to the MeshEditOp done function.

EDERR_NONE: Success.
EDERR_NOMEMORY: A memory allocation failed.
EDERR_BADLAYER: An operation was attempted in an invalid layer.
EDERR_BADSURF: The edit created an invalid surface name.
EDERR_USERABORT: The user (or the plug-in) ended the edit before it was completed.
EDERR_BADVMAP: The operation involved an invalid vertex map.
EDERR_BADARGS: The function failed for a reason not covered by the other error codes.

MeshEditOp

The MeshEditBegin function returns a MeshEditOp containing data and functions for performing mesh edits.

   typedef struct st_MeshEditOp {
      EDStateRef       state;
      int              layerNum;
      void            (*done)      (EDStateRef, EDError, int selm);
      int             (*pointCount)(EDStateRef, EltOpLayer, int mode);
      int             (*polyCount) (EDStateRef, EltOpLayer, int mode);
      EDError         (*pointScan) (EDStateRef, EDPointScanFunc *,
                                      void *, EltOpLayer);
      EDError         (*polyScan)  (EDStateRef, EDPolyScanFunc *,
                                      void *, EltOpLayer);
      EDPointInfo *   (*pointInfo) (EDStateRef, LWPntID);
      EDPolygonInfo * (*polyInfo)  (EDStateRef, LWPolID);
      int             (*polyNormal)(EDStateRef, LWPolID, double[3]);
      LWPntID         (*addPoint)  (EDStateRef, double *xyz);
      LWPolID         (*addFace)   (EDStateRef, const char *surf,
                                      int numPnt, const LWPntID *);
      LWPolID         (*addCurve)  (EDStateRef, const char *surf,
                                      int numPnt, const LWPntID *,
                                      int flags);
      EDError         (*addQuad)   (EDStateRef, LWPntID, LWPntID,
                                      LWPntID, LWPntID);
      EDError         (*addTri)    (EDStateRef, LWPntID, LWPntID,
                                      LWPntID);
      EDError         (*addPatch)  (EDStateRef, int nr, int nc, int lr,
                                      int lc, EDBoundCv *r0,
                                      EDBoundCv *r1, EDBoundCv *c0,
                                      EDBoundCv *c1);
      EDError         (*remPoint)  (EDStateRef, LWPntID);
      EDError         (*remPoly)   (EDStateRef, LWPolID);
      EDError         (*pntMove)   (EDStateRef, LWPntID, const double *);
      EDError         (*polSurf)   (EDStateRef, LWPolID, const char *);
      EDError         (*polPnts)   (EDStateRef, LWPolID, int,
                                      const LWPntID *);
      EDError         (*polFlag)   (EDStateRef, LWPolID, int mask,
                                      int value);
      EDError         (*polTag)    (EDStateRef, LWPolID, LWID,
                                      const char *);
      EDError         (*pntVMap)   (EDStateRef, LWPntID, LWID,
                                      const char *, int, float *);
      LWPolID         (*addPoly)   (EDStateRef, LWID type, LWPolID,
                                      const char *surf, int numPnt,
                                      const LWPntID *);
      LWPntID         (*addIPnt)   (EDStateRef, double *xyz, int numPnt,
                                      const LWPntID *, const double *wt);
      EDError         (*initUV)    (EDStateRef, float *uv);
      void *          (*pointVSet) (EDStateRef, void *, LWID,
                                      const char *);
      int             (*pointVGet) (EDStateRef, LWPntID, float *);
      const char *    (*polyTag)   (EDStateRef, LWPolID, LWID);
      EDError         (*pntSelect) (EDStateRef, LWPntID, int);
      EDError         (*polSelect) (EDStateRef, LWPolID, int);
      int             (*pointVPGet)(EDStateRef, LWPntID, LWPolID,
                                      float *);
      int             (*pointVEval)(EDStateRef, LWPntID, LWPolID,
                                      float *);
      EDError         (*pntVPMap)  (EDStateRef, LWPntID, LWPolID,
                                      LWID, const char *, int, float *);
   } MeshEditOp;

state

An opaque pointer to data used internally by Modeler during the mesh edit. Pass this as the first argument to all of the edit functions.

layerNum

Points and polygons may only be created or modified in the primary active layer, which is given by this layer number. The primary layer is the lowest numbered foreground layer.

done( state, error, selset )

Call this when the edit is complete. As changes are made during an edit, they are buffered through Modeler's undo mechanism, so they are not reflected in the data until done is called, and not at all if done sets the error argument.

In general, if one of the edit functions returns an error, you'll pass that error to done. If you just want the edit to stop or be discarded, possibly because the user pressed the Cancel button in a progress monitor, you'll pass EDERR_USERABORT. If an error occurs in your plug-in, you'll pass EDERR_NOMEMORY (for memory allocation errors) or EDERR_BADARGS (for everything else). And if the edit was successful, you'll use EDERR_NONE.

The selset argument tells Modeler how you want the selection to appear to the user after the edit has been applied. It contains flags combined using bitwise-or, and can include the following.

EDSELM_CLEARCURRENT: Deselect elements that were selected when the edit began.
EDSELM_SELECTNEW: Select elements created by the edit.
EDSELM_FORCEVRTS: Force selection of newly created vertices.
EDSELM_FORCEPOLS: Force selection of newly created polygons.

A value of 0 leaves all directly selected elements selected after the edit. The CLEARCURRENT and SELECTNEW flags are polite hints; they won't override selection settings made by the user. The force flags will always force direct selection of the points or polygons created by the edit.

npoints = pointCount( state, oplayer, selmode ) npolygons = polyCount( state, oplayer, selmode )

Returns the number of points or polygons that meet the layer and selection criteria. The selection mode can be one of the following.

EDCOUNT_ALL: Both selected and unselected points or polygons.
EDCOUNT_SELECT: Only selected points or polygons.
EDCOUNT_DELETE: Only points or polygons flagged for deletion by this mesh edit.

err = pointScan( state, scanfunc, userdata, oplayer ) err = polyScan( state, scanfunc, userdata, oplayer )

Enumerate the points or polygons in the specified layers. For each element, Modeler calls the callback function you supply. The callbacks are defined this way.

typedef EDError EDPointScanFunc (void *, const EDPointInfo *);
typedef EDError EDPolyScanFunc (void *, const EDPolygonInfo *);

The userdata pointer is passed as the first argument to your callbacks, and it can be whatever is useful to you. The point and polygon info structures passed as the second argument are described later. If your callback returns an error, the scan is stopped and the callback's error is returned.

Point and polygon scans will enumerate all of the geometry in the layers you request, regardless of what geometry is selected, even if you begin the edit with OPSEL_USER or OPSEL_DIRECT. To find out whether a given element is selected (as defined by your choice of EltOpSelect), you need to test the EDPointInfo or EDPolygonInfo flags field for the EDDF_SELECT bit. Similarly, if you've deleted geometry during the mesh edit, it will still be enumerated, but the flags field of the info structure will contain EDDF_DELETE.

info = pointInfo( state, point ) info = polyInfo( state, polygon )

Returns information about a point or polygon. These return the same EDPointInfo and EDPolygonInfo structures that are passed to the scan callbacks.

ok = polyNormal( state, polygon, norm )

Get a polygon's normal. The normal is a unit vector perpendicular to the plane defined by the first, second and last vertex of the polygon. If the polygon has fewer than three vertices, or is somehow degenerate, norm isn't changed and the function returns 0. Otherwise it returns 1 and norm receives the normal.

point = addPoint( state, pos )

Create a point.

polygon = addFace( state, surfname, npoints, point_array )

Create a polygon. If the surface name is NULL, the polygon will be assigned the current default surface. The vertices are defined by an array of point IDs listed in clockwise order. The polygon normal will be inferred from the first, second and last points.

polygon = addCurve( state, surfname, npoints, point_array, flags )

Create a curve (a polygon of type LWPOLTYPE_CURV). The EDPF_CCSTART and EDPF_CCEND flags specify that the first and last points in the point array should serve as control points and not be included in the curve itself.

To create a closed curve, both of these flags must be set, and the first three point IDs in the array must be the same as the last three. (The first point in the array is the start control point and the second to last point in the curve. The second point in the array is both the first and last point of the curve. The third point in the array is the second point of the curve and the end control point.)

err = addQuad( state, v1, v2, v3, v4 ) err = addTri( state, v1, v2, v3 )

Create a quadrangle or a triangle with the current default surface. These two functions respect the user's settings for new geometry. Two collocated polygons with opposite normals will be created if the user has set the double-sided option, and quads will be split into two triangles if the user has set the triangles-only option.

err = addPatch( state, nr, nc, lr, lc, r0, r1, c0, c1 )

Create a polygonal patch defined by three or four bounding curves. The first two arguments (after the EditStateRef) give the number of patch divisions in the R (row) and C (column) directions. The second two arguments are booleans; if 0, the divisions are equally spaced along the curve, and if 1, the spacing is determined by the positions of the curve knots. The last four arguments are the bounding curves, each defined by an EDBoundCV structure.

typedef struct st_EDBoundCv {
   LWPolID curve;
   int     start, end;
} EDBoundCv;

The start and end indexes are the points on the curve that should be used as endpoints for patching. The first and second curves define the R boundaries. The third and optional fourth curve define the C boundaries.

err = remPoint( state, point )

Delete the point. Modeler will flag the point as deleted, but will actually remove it from the database only after done is called.

err = remPoly( state, polygon )

Delete the polygon.

err = pntMove( state, point, pos )

Put a point in a new position.

err = polSurf( state, polygon, surfname )

Change the surface assigned to a polygon.

err = polPnts( state, polygon, npoints, point_array )

Replace the point list of a polygon.

err = polFlag( state, polygon, mask, value )

Set polygon flags. The mask contains 1 bits for each flag you want to change, and the value contains the new flag settings (0 or 1 for each 1 bit in the mask). Currently, the flags that can be changed are the EDPF_START and EDPF_END flags for curves.

err = polTag( state, polygon, tagtype, tag )

Add a polygon tag to a polygon, or change an existing tag. If the tag type is LWPTAG_SURF, the tag is the surface name. If the tag type is LWPTAG_PART, the tag is the part (or group) name. For anything other than surface tags, passing a NULL tag will remove an existing tag of the specified type.

err = pntVMap( state, point, type, name, nvalues, val_array )

Add a vmap vector to a point. The vmap type can be one of the following, or something else.

LWVMAP_PICK - selection set
LWVMAP_WGHT - weight map
LWVMAP_MNVW - subpatch weight map
LWVMAP_TXUV - texture UV coordinates
LWVMAP_MORF - relative vertex displacement (morph)
LWVMAP_SPOT - absolute vertex displacement (morph)
LWVMAP_RGB, LWVMAP_RGBA - vertex color

Pass a NULL val_array to remove a vmap vector from the point.

polygon = addPoly( state, type, template, surf, npoints, point_array )

Create a polygon. If a template polygon is supplied, Modeler copies the polygon tags for the new polygon from the template. If the surface name is NULL, the surface will be that of the template, or the current default surface if the template is NULL. The vertices of the new polygon are listed in clockwise order, and the normal will be inferred from the first, second and last vertex.

point = addIPnt( state, pos, npoints, point_array, weight_array )

Create an "interpolated" point. The new point's vmap values are calculated as a weighted average of the vmaps of the points in the points array. If pos is NULL, the position is also computed as a weighted average. If the weight array is NULL, the averaging over the point list is uniform. The weights are renormalized to sum to 1.0.

err = initUV( state, uv )

Set the texture UV for a point or polygon you're about to create. If a texture map is selected in Modeler's interface, the UVs will be assigned to that map as points or polygons are created. You'll typically want to give the user the option of whether or not to create UVs for new points and polygons.

When creating points, pass initUV an array of two floats and then call any of the functions that create a point. The two floats will be used as the U and V for the point, after which the initUV state will be cleared so that subsequent points have no UV unless the function is called again.

To initialize per-polygon, or discontinuous, UVs, call initUV with a pointer to 2n floats before creating a polygon with n vertices. For each vertex, if the point's continuous UV value is different from the UV in the array, then a polygon-specific UV is set for the vertex. If the point has no continuous UV, then the continuous value for the point is set to the polygon UV.

Any combination of these two methods can be used to assign UVs to new data. If only polygon UVs are specified, continuous UVs will still be created where polygons share UV values. Alternately, plug-ins can assign UVs to points and only specify polygon UVs along seam polygons.

vmapID = pointVSet( state, vmapID, vmaptype, vmapname )

Select a vmap for reading vectors. Returns an opaque pointer that can be used to select the same vmap in later calls to this function. The first time this is called for a given vmap, the pointer can be NULL, and Modeler will locate and select the vmap using the type and name arguments.

ismapped = pointVGet( state, point, val )

Read the vmap vector for a point. The vector is read from the vmap selected by a previous call to pointVSet. If the point is mapped (has a vmap value in the selected vmap), the val array is filled with the vmap vector for the point, and pointVGet returns true. If you don't already know the dimension of the vmap (the number of values per point, and therefore the required size of the val array), you can use the scene objects global to find out.

See also pointVPGet and pointVEval. pointVGet is equivalent to reading values from a VMAP chunk in an object file. It returns the continuous, or per-point, vector. For the raw discontinuous, or per-polygon-vertex value, use pointVPGet, and for the combined value accounting for both sources, use pointVEval.

tag = polyTag( state, polygon, tagtype )

Returns a tag string associated with the polygon. For the LWPTAG_SURF tag type, the surface name is returned.

err = pntSelect( state, point, setsel ) err = polSelect( state, polygon, setsel )

Set the selection state of a point or polygon. These can only be called during OPSEL_MODIFY mesh edits. The element is selected if setsel is true and deselected if it's false.

ismapped = pointVPGet( state, point, polygon, val )

Read the vmap vector for a polygon vertex. This is like pointVGet, but it returns the discontinuous vmap value, equivalent to reading entries in a VMAD chunk.

ismapped = pointVEval( state, point, polygon, val )

Read the vmap vector for a point, accounting for both continuous and discontinuous values. Generally, if a discontinuous value exists for the point, that value will be returned. Otherwise the continuous value is used.

err = pntVPMap( state, point, polygon, type, name, dim, val )

Add a discontinuous vmap vector to a polygon vertex. This is the vector returned by pointVPGet. See pntVMap for a partial list of vmap types.

Point and Polygon Info

The info and scan functions use EDPointInfo and EDPolygonInfo structures to provide information about points and polygons. Modeler maintains only one of each of these. It overwrites the structure each time data for a different point or polygon is required, so if you need to keep data for multiple points or polygons, you must copy it from the structure and store it locally.

   typedef struct st_EDPointInfo {
      LWPntID  pnt;
      void    *userData;
      int      layer;
      int      flags;
      double   position[3];
      float   *vmapVec;
   } EDPointInfo;

pnt: The ID of the point.
userData: Your per-point data buffer, allocated by the MeshEditBegin call.
layer: The layer in which the point resides.
flags: Flags for the point. The EDDF_SELECT bit is set if the selection state of the point matches the EltOpSelect passed to the MeshEditBegin function. The EDDF_DELETE bit is set if the point has been deleted during this mesh edit.
position: The point's position.
vmapVec: The vmap values associated with the point.

   typedef struct st_EDPolygonInfo {
      LWPolID        pol;
      void          *userData;
      int            layer;
      int            flags;
      int            numPnts;
      const LWPntID *points;
      const char    *surface;
      unsigned long  type;
   } EDPolygonInfo;

pol: The polygon ID.
userData: Your per-polygon data buffer, allocated by the MeshEditBegin call.
layer: The layer in which the polygon resides.
flags: Flags for the polygon. These include the EDPF_CCSTART and EDDF_CCEND bits for curves.
numPnts: The number of vertices in the polygon.
points: An array of point IDs for the vertices of the polygon.
surface: The polygon's surface.
type: The polygon type, which will usually be one of the following.
LWPOLTYPE_FACE - face
LWPOLTYPE_CURV - higher order curve
LWPOLTYPE_PTCH - subdivision control cage polygon
LWPOLTYPE_MBAL - metaball
LWPOLTYPE_BONE - bone

Example

The zfacing sample demonstrates OPSEL_MODIFY edits. This method of altering the selection is especially useful in CommandSequence plug-ins, so zfacing.c contains both edit and command versions of the activation function. The vidscape sample uses mesh editing to enumerate the geometry of an object before exporting it to a VideoScape format file. Many former mesh edit sample plug-ins, notably superq and spikey, have been converted to interactive mesh edit tools.