Classes: ObjectLoader

ObjectLoader

Availability  LightWave 6.0
Component  Layout, Modeler
Header  lwobjimp.h

Object loaders read object files that aren't in LightWave's native object file format.

When an object loader's activation function is called, it should open the object file and try to recognize its contents. LightWave calls all of the installed object loaders in sequence until one of them recognizes the file. Each object loader is therefore responsible for identifying the files it can load. If the file isn't one the loader understands, the loader sets the result field of the local structure to LWOBJIM_NOREC and returns AFUNC_OK.

If, on the other hand, the loader understands the object file, it reads the file and submits its contents to the host through the functions provided in the local structure.

Handler Activation Function

   XCALL_( int ) MyObjImport( long version, GlobalFunc *global,
      LWObjectImport *local, void *serverData );

The local argument to an object loader's activation function is an LWObjectImport.

   typedef struct st_LWObjectImport {
      int         result;
      const char *filename;
      LWMonitor  *monitor;
      char       *failedBuf;
      int         failedLen;
      void       *data;
      void       (*done)    (void *);
      void       (*layer)   (void *, short int lNum, const char *name);
      void       (*pivot)   (void *, const LWFVector pivot);
      void       (*parent)  (void *, int lNum);
      void       (*lFlags)  (void *, int flags);
      LWPntID    (*point)   (void *, const LWFVector xyz);
      void       (*vmap)    (void *, LWID type, int dim,
                               const char *name);
      void       (*vmapVal) (void *, LWPntID point, const float *val);
      LWPolID    (*polygon) (void *, LWID type, int flags, int numPts,
                               const LWPntID *);
      void       (*polTag)  (void *, LWPolID polygon, LWID type,
                               const char *tag);
      void       (*surface) (void *, const char *, const char *, int,
                               void *);
      void       (*vmapPDV) (void *, LWPntID point, LWPolID polygon,
                               const float *val);
   } LWObjectImport;

result

Set this to indicate whether the object was loaded successfully. The result codes are

LWOBJIM_OK

The object was loaded successfully.

LWOBJIM_NOREC

The loader didn't recognize the file format. This can happen frequently, since all loaders are called in sequence until one of them doesn't return this result.

LWOBJIM_BADFILE

The loader couldn't open the file. If the loader is able to open the file but believes it has found an error in the contents, it should return IPSTAT_NOREC.

LWOBJIM_ABORTED

Use this to indicate that the user cancelled the load operation. This can happen if you use the monitor to indicate the progress of a lengthy image loading operation..

LWOBJIM_FAILED

An error occurred during loading, for example a memory allocation failed.

filename

The name of the file to load.

monitor

A monitor for displaying the progress of the load to the user. You don't have to use this, but you're encouraged to if your object loading takes an unusual amount of time. This is the same structure as that returned by the monitor global's create function.

failedBuf
failedLen

These are used to display an error message to the user when object loading fails. Use strcpy or a similar function to copy a single-line error string into failedBuf. failedLen is the maximum size of this string, and it may be 0.

data

An opaque pointer to data used internally by LightWave during object loading. Pass this as the first argument to the loading functions.

done( data )

Call this when object loading is complete, after setting the result field.

layer( data, layernum, layername )

Create a new layer. All of the geometry you load will be put in this layer until you call layer again. Even if your object format doesn't support anything that could be interpreted as layers, this needs to be called at least once to initialize a layer that will receive your geometry. The layer name is optional and can be NULL. Layers are ordinarily created in increasing numerical order, starting at 1, but this isn't required.

pivot( data, pivpoint )

Set the pivot point for the current layer. The pivot point is the origin for rotations in the layer.

parent( data, layernum )

Set the parent layer for the current layer. Layer parenting is a mechanism for creating object hierarchies.

lFlags( data, layerflags )

Set flags for the current layer. The only flag currently defined is the low order bit, 1 << 0, which when set signifies that the layer is hidden.

pointID = point( data, pos )

Create a point in the current layer. Returns a point ID that can be used later to refer to the point in polygon vertex lists.

vmap( data, type, dim, name )

Create or select a vertex map. If the vmap doesn't exist, this function creates it. Otherwise it selects the vmap for subsequent calls to vmapVal. The lwmeshes.h header defines common vmap IDs, but you can create custom vmap types for special purposes.

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

The dimension of a vmap is just the number of values per point.

vmapVal( data, point, valarray )

Set the value of the current vmap for the point. The number of elements in the value array should be the same as the dimension of the vmap.

polID = polygon( data, type, flags, npoints, point_array )

Create a polygon in the current layer. The type will usually be one of the polygon types defined in lwmeshes.h.

LWPOLTYPE_FACE - face
LWPOLTYPE_CURV - higher order curve
LWPOLTYPE_PTCH - subdivision control cage polygon
LWPOLTYPE_MBAL - metaball
LWPOLTYPE_BONE - bone

The flags are specific to each type. The point array contains npoints point IDs returned by calls to the point function.

polTag( data, polygon, type, tag )

Associate a tag string with a polygon. A polygon's surface is set, for example, by passing LWPTAG_SURF as the type and the surface name as the tag. Note that you can do this without first having called surface.

surface( data, basename, refname, chunk_size, surf_chunk )

Set parameters for a surface. The base name is the name of the surface, while the reference name is the name of a "parent" surface (which can be NULL). Parameters not explicitly defined for the surface will be taken from its reference, or parent, surface. The surface data is passed as the memory image of a LightWave object file SURF chunk. See the object file format document for a detailed description of the contents of a SURF chunk.

Note that this method of specifying surface parameters doesn't allow you to associate envelopes or image textures with a surface. In the SURF chunk, envelopes and images are referenced by index into ENVL and CLIP chunks, respectively, and object loaders have no way to create these.

vmapPDV( data, point, polygon, valarray )

Like vmapVal, but sets the per-polygon, or discontinuous, vmap vector for a polygon vertex.

Example

The vidscape sample loads VideoScape ASCII object files. Several examples of this simple format (the files with .geo extensions) are included in the directory. The singular merit of the VideoScape format is that it's easy to write, even by hand, but in particular using languages like LScript, Perl and BASIC. The qbasic program that generated the ball.geo object is included. The vidscape sample also demonstrates the use of a MeshDataEdit plug-in to save objects in non-LightWave formats.