LW Scene Info 2 System ID Globals Table of Contents

"Scene Objects"

Availability:  LightWave 6.0
Component:  Layout

The scene objects global gives plug-ins access to the internal representation of each object file loaded into the scene. Functions are provided for scanning the points, polygons and vertex maps of an object.

Global Call

   LWObjectFuncs *objfunc;
   objfunc = global( "Scene Objects", GFUSE_TRANSIENT );

The global function returns a pointer to an LWObjectFuncs.

   typedef struct st_LWObjectFuncs {
      int          (*numObjects)  (void);
      const char * (*filename)    (int obj);
      int          (*maxLayers)   (int obj);
      int          (*layerExists) (int obj, int lnum);
      void         (*pivotPoint)  (int obj, int lnum, LWFVector pos);
      LWMeshInfo * (*layerMesh)   (int obj, int lnum);
      int          (*numVMaps)    (LWID);
      const char * (*vmapName)    (LWID, int index);
      int          (*vmapDim)     (LWID, int index);
   } LWObjectFuncs;
count = numObjects()
Returns a count of the number of objects in the scene's object database. This is the number of unique object files that have been loaded, which in general will be different from the number of animateable object items (clones and null objects, for example, aren't counted).

name = filename( object_index )
Returns the filename for the object. Objects in the database are indexed by integers ranging from 0 to count - 1. Except during rendering, the index associated with a given object can change at any time as objects are added to or removed from the object database by the user.

maxlayer = maxLayers( object_index )
Returns a value one greater than the highest indexed, existing layer for the object. This is just the layer count if all layers with indexes between 0 and maxlayer - 1 exist.

exists = layerExists( object_index, layer_index )
True if the layer exists.

pivotPoint( object_index, layer_index, pos )
Gets the pivot point for the object layer.

mesh = layerMesh( object_index, layer_index )
Returns a mesh info structure for the object layer. These are described in detail below. Call the mesh info destroy function when you no longer need it. This frees resources allocated by layerMesh.

vmap_count = numVMaps( vmtype );
Returns a count of the number of vertex maps of a given type. Vmap type codes are an extensible set of four-character identifiers. The header file lwmeshes.h defines some of the common vmap IDs.

LWVMAP_PICK -
LWVMAP_WGHT - weight map
LWVMAP_MNVW -
LWVMAP_TXUV - texture UV coordinates
LWVMAP_MORF - vertex displacement
LWVMAP_SPOT -

vmap_name = vmapName( vmtype, vmindex );
Returns the name of a vmap.

dimensions = vmapDim( vmtype, vmindex );
Returns the number of dimensions, or values per vertex, of a vmap. Vmaps are typically 2D or 3D (two or three coordinate values per vertex), but they can have any number of dimensions.

Mesh Info

The layerMesh function returns a structure of type LWMeshInfo.

   typedef struct st_GCoreVertex *  LWPntID;
   typedef struct st_GCorePolygon * LWPolID;
   typedef struct st_LWMeshInfo *   LWMeshInfoID;

   typedef int LWPntScanFunc (void *, LWPntID);
   typedef int LWPolScanFunc (void *, LWPolID);

   typedef struct st_LWMeshInfo {
      void         *priv;
      void         (*destroy)     (LWMeshInfoID);
      int          (*numPoints)   (LWMeshInfoID);
      int          (*numPolygons) (LWMeshInfoID);
      int          (*scanPoints)  (LWMeshInfoID, LWPntScanFunc *, void *);
      int          (*scanPolys)   (LWMeshInfoID, LWPolScanFunc *, void *);
      void         (*pntBasePos)  (LWMeshInfoID, LWPntID, LWFVector pos);
      void         (*pntOtherPos) (LWMeshInfoID, LWPntID, LWFVector pos);
      int          (*pntVSelect)  (LWMeshInfoID, LWID, const char *);
      int          (*pntVGet)     (LWMeshInfoID, LWPntID, float *vector);
      LWID         (*polType)     (LWMeshInfoID, LWPolID);
      int          (*polSize)     (LWMeshInfoID, LWPolID);
      LWPntID      (*polVertex)   (LWMeshInfoID, LWPolID, int);
      const char * (*polTag)      (LWMeshInfoID, LWPolID, LWID);
   } LWMeshInfo;
priv
An opaque pointer to private data used internally by the mesh info functions.

destroy( meshinfo )
Frees resources allocated by the layerMesh call that created this LWMeshInfo. This should only be called by the client that created it.

npts = numPoints( meshinfo )
Returns the number of points in the object.

npols = numPolygons( meshinfo )
Returns the number of polygons in the object.

result = scanPoints( meshinfo, pointscan_func, mydata )
Enumerate the points in the object. The callback you supply is called for each point in the object. The mydata argument is passed to the callback and can be anything it might require. Enumeration stops if your callback returns a non-zero value, and this value is then returned by scanPoints. Otherwise it returns 0.

result = scanPolygons( meshinfo, polyscan_func, mydata )
Enumerate the polygons in the object.

pntBasePos( meshinfo, point, pos )
Gets the base position of a point. This is the position of the point at rest in the basic object coordinate system.

pntOtherPos( meshinfo, point, pos )
Gets an alternate position for the point. This many be the same as the base position or it may be the position of the point after some transformation. The nature of the alternate position depends on how the mesh info was created.

dim = pntVSelect( meshinfo, vmap_type, vmap_name )
Selects a vmap for reading vectors. The vmap is given by its four-character identifier and its name string. The function returns the dimension of the vmap, or -1 if no vmap was found with the given ID and name.

ismapped = pntVGet( meshinfo, point, val )
Reads the vmap vector for a point. The vector is read from the vmap selected by a previous call to pntVSelect. 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 pntVGet returns true. The val array must have at least as many elements as the number returned by pntVSelect.

type = polType( meshinfo, polygon )
Returns the type of a polygon. "Polygon" here refers to a number of different kinds of geometric atoms, including things like curves and bones. The polygon type codes are an extensible set of four-character identifiers. The header file lwmeshes.h defines the most common ones.

LWPOLTYPE_FACE - face
LWPOLTYPE_CURV - higher order curve
LWPOLTYPE_PTCH - higher order surface patch
LWPOLTYPE_MBAL - metaball
LWPOLTYPE_BONE - bone

nvert = polSize( meshinfo, polygon )
Returns the number of vertices that the polygon has.

point = polVertex( meshinfo, polygon, vert_index )
Returns the point ID for a vertex of the polygon. Vertex indexes range from 0 to nvert - 1.

tagname = polTag( meshinfo, polygon, tagID )
Returns the tag string of the given type associated with the polygon. A null string pointer means that the polygon does not have a tag of that type. lwmeshes.h defines the most common polygon tags.

LWPTAG_SURF
The name of the surface applied to the polygon.
LWPTAG_PART
The name of a polygon group the polygon belongs to.

Example

This code fragment doesn't do much of anything yet.

   #include <lwserver.h>
   #include <lwmeshes.h>

   LWObjectFuncs *objfunc;
   LWMeshInfo *meshinfo;
   int objindex, layindex;

   objfunc = global( "Scene Objects", GFUSE_TRANSIENT );

   if ( objfunc ) {
      ...
      meshinfo = layerMesh( objindex, layindex );
      if ( meshinfo ) {
         ...
         meshinfo->destroy( meshinfo );
      }
   }