PolygonHandler

Availability  LightWave® 8.0
Component  Layout/Modeler
Header  lwpolygon.h

Polygon Type handlers provide a way to extend the list of available polygon types in LightWave.

Handler Activation Function

   XCALL_( int ) MyPolygonHandler( int version, GlobalFunc *global,
      LWPolygonHandler *local, void *serverData );

The local argument to a motion handler's activation function is an LWPolygonHandler.

   typedef struct st_LWPolygonHandler {
      LWInstanceFuncs *inst;
      LWItemFuncs     *item;
   } LWPolygonHandler;

The first two members of this structure are standard handler functions.

PolyType

The handler instance create function has to create and return a LWPolyType structure.

   typedef struct st_LWPolyType {
      unsigned int type;
      int           flags;
      void	  (*display )( void *instance, 
                               LWPolID pol, 
                               const LWPtypeWireDrawAccess *access, 
                               LWPolygonTypeAccessID ptinfo );
      void	  (*genMesh )( void *instance, 
	                             LWPolID pol, 
                               LWPolyMeshInfoID mesh, 
                               LWPolygonTypeAccessID ptinfo );
      int	  (*tstMesh )( void *instance, 
                               LWPolID pol, 
                               LWPolygonTypeAccessID ptinfo );
      void        (*startup )( LWPolyTypeID );
      void        (*shutdown)( LWPolyTypeID polygon_type);
      void *      (*alloc   )( LWPolygonTypeAccessID ptinfo );
      void        (*free    )( void *data );
      int         (*update  )( void *, 
                               int lnum, 
                               int change, 
                               LWPolygonTypeAccessID ptinfo );
   } LWPolyType;

type

Four-character type code for the new polygon. Use LWID_() in lwtypes.h to create.  There are several 'built-in' types that can not be used for custom polygon types.

flags

This contains bits that determine the type of the new polygon.  If the LWGPTF_SURFACE bit is set, then the polygon will render as a surface and a mesh wil be generated.  If LWGPTF_FLAT is set, then the surface is intended to be flat.  If LWGPTF_LINEAR is set, then the polygon type is a linear curve, and the order of the points determines absolute direction rather than sidedness.  If LWGPTF_SUBD is set, the polytype creates a subdivision surface.

display( instance, polygon, wireaccess, ptinfo )

This is called when an instance of your custom polygon needs to be drawn in a view port
using basic drawing functions.  The specific polygon to be displayed and the means to obtain the vertexes are given along with the means to draw into the view port

genMesh( instance, polygon, polymeshinfo, ptinfo )

This is called when an instance of your custom polygon needs to generate a standard surface mesh, which can consist of vertices, triangles or quads, normal vectors, and texture weightings.  The polygon parameter specifies the custom polygon for which a mesh is needed.  The vertex instance allows access to the vertices for the existing custom polygon.  The mesh is a structure that you fill in. (see definition below)

 

tstMesh( instance, polygon, ptinfo )

This is called to test if the given custom polygon instance is to be used.
Return 0 if false, 1 if true.

 

startup( ptypeid )

The 'startup' and 'shutdown' functions are used by the host when adding and removing the custom polygon type. The private data should be managed by these functions.

 

shutdown( ptypeid )

Called once when plug-in unloaded.

 

alloc( ptinfo )

This is called when an instance of your custom polygon type is being created. Any necessary memory allocation and setup should be done here. The free() function is obviously called to destroy that data.

 

free( instance )

This is called when an instance of your custom polygon type is being destroyed. This is your chance for polygon instance-specific memory de-allocation.  instance is a pointer to the memory allocated via the alloc() callback.

 

update( instance, layernum, changeflags, ptinfo )

This is called when the data in a layer changes. Test if the changes are relevant for your instance, and perform necessary pre-processing.

PolygonType Access

The functions provided by this structure resemble the ones in LWMeshInfo.

LWGPolMeshInfo

    typedef struct st_GPolMeshInfo {
        int flag;
        int type;
        int nvrt;
        int npol;
        int ntex;
        const int *pols;
        const float *vrts;
        const float *norm;
        const int *itex;
        const float *wtex;
    } GPolMeshInfo;

flag

This flag will be set for you to indicate which additional mesh data is being requested.  When set to LWPMI_NORMALS, please compute and supply a norm array.  When set to LWPMI_TEXTURE, please compute and supply texture data via itex and wtex.  You should always specify the vrts and pols arrays.

type

The type is 3 or 4, where 3 indicates that this is a triangle mesh and 4 indicates that it is a quad mesh. A type of zero indicates no mesh.

nvrt

Number of vertices in the polygon's mesh

npol

Number of surface polygons this specific polygon instance has generated.

ntex

Texture information is organized into a set of tuples; one tuple associated with each vertex in the mesh of polygons. Each point in the mesh is associated with an n-tuple of polygon vertices and weights, with the tuple order specified by ntex.

pols

The polygons in the mesh are specified by indices into the vertex array vrts. There are npol polygons, and the indices are grouped into triples or quads based on the mesh type.

vrts

The vertices of the polygon mesh are given by an array of floats, organized into nvrt triples.

norm

The normals of the polygon mesh are given by an array of floats, organized into nvrt triples.  It is important to note that these triples should be normalized direction vectors (x,y,z).  This is only needed when flag is set the LWPMI_NORMALS.

itex

This array holds the indices of the polygon vertices used in a texture.

wtex

This array holds the weight of each texture-polygon vertex.

Example

The spikeyplus SDK sample project is a plug-in showing the interaction between a MeshEditTool, which creates the polygon of a new type, and the Polygon Type plug-in, which takes care of creating and displaying the generated geometry,