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 intofailedBuf
.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 colorThe 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
- boneThe flags are specific to each type. The point array contains
npoints
point IDs returned by calls to thepoint
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 calledsurface
. 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 aSURF
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 intoENVL
andCLIP
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.