NAME

vzShapeSet - A set of volumetric shapes.

INHERITS FROM

vzObject

HEADER FILE

#include <Volumizer2/ShapeSet.h>

PUBLIC METHOD SUMMARY

   Creation/Modification

vzShapeSet (

);

static vzShapeSet* load (

const char* filename);

static vzShapeSet* create (

const char* str);

void add (

vzShape* shape);

void remove (

vzShape* shape);

void setGraphicsState (

vzGraphicsState* state);

   Get methods

int getNumShapes (

) const;

vzShape* get (

int i) const;

void getBoundingBox (

float bbox[6]) const;

vzGraphicsState* getGraphicsState (

) const;

   Utility methods

void sort (

int* indices) const;

void setShapeGridDimensions (

const int dimensions[3]);

void getShapeGridDimensions (

int dimensions[3]) const;

static void setLoaderCB (

vzShapeSetLoaderCB loaderPtr);

PROTECTED METHOD SUMMARY

~vzShapeSet (

);

CLASS DESCRIPTION

vzShapeSet provides a simple abstraction for a collection of volumetric shapes (vzShape). Individual shapes can be added to and removed from the set. The class provides utility routines for computing the bounding box and visibility sorting of the set, among others. The ShapeSet provides a static load() method which uses the libvzxml loader library (based on Apache's Xerces library) to load and create a shape set.

METHOD DESCRIPTIONS

   vzShapeSet()

vzShapeSet (

);

Constructor for the shape set.

   ~vzShapeSet()

~vzShapeSet (

);

Destructor for the shape set.

   add()

void add (

vzShape* shape);

Add the shape to the shape set. The shape is added to the end of the set.

   create()

static vzShapeSet* create (

const char* str);

Create a str. This factory is similar to load(), except that the vzShapeSet description is specified as a character string instead of a text file.

   get()

vzShape* get (

int i) const;

Get the i 'th shape from the set.

   getBoundingBox()

void getBoundingBox (

float bbox[6]) const;

Return the bounding box of the set of shapes.

   getGraphicsState()

vzGraphicsState* getGraphicsState (

) const;

Get the graphics state for the shape set.

   getNumShapes()

int getNumShapes (

) const;

Returns the number of shapes in the set

   getShapeGridDimensions()

void getShapeGridDimensions (

int dimensions[3]) const;

Get the number of shapes along X, Y and Z axes in the shape set.

   load()

static vzShapeSet* load (

const char* filename);

Load a filename. For any plug-in modules, the plug-in DSO has to define the callback functions with the name createObjectClassName, where the ObjectClassName is the name of the class without the vz prefix.

// Type definition for the object loader callback
typedef vzObject * (*vzObjectLoaderCB)(const char *filename, 
                                       const char *userString);

// Example for loading class vzPolyGeometry
extern "C" vzObject *createPolyGeometry(const char *filename,
                                        const char *userString)
{
    vzPolyGeometry *geom = MyPolyLoader::load(filename);
    if(!geom) {
        fprintf(stderr,"Cannot load file %s using MyPolyLoader\n", filename);
        return NULL;
    }

return (vzObject *)geom;
}

   remove()

void remove (

vzShape* shape);

Remove the shape from the shape set.

   setGraphicsState()

void setGraphicsState (

vzGraphicsState* state);

Set the current graphics state to be used for controlling LOD parameters for this shape set. The graphics state would be used to update the center-of-interest of any clip-textures in the shape set. The application needs to update the graphics state depending on user interaction, etc. If the application does not use the above method to set a graphics state, the class would create a default one internally.

   setLoaderCB()

static void setLoaderCB (

vzShapeSetLoaderCB loaderPtr);

Set the loader method for this shape set. The loader method is defined as

typedef vzShapeSet * (*vzShapeSetLoaderCB)(const char *filename);

This callback is set by the libvzxml library automatically if the application links against the library or dlopen's the library. In this case, the shape set will be loaded using the XML based Volumizer loader. Applications can implement their own loaders for loading a vzShapeSet by setting the appropriate loader callback.

   setShapeGridDimensions()

void setShapeGridDimensions (

const int dimensions[3]);

Set the number of shapes along X, Y and Z axes in the shape set. This is useful if the shape set is used to represent a regular grid of shapes (typically used for bricking of 3D textures) which are adjacent to each other. The same algorithm would work if the shapes are scattered in 3D space and the adjacent shapes do not overlap.

   sort()

void sort (

int* indices) const;

Sort the set of shapes in a back-to-front visibility sorted order. The sorted order is returned as the indices of the shapes in indices in a back-to-front sorted order. Note: The method does not allocate any memory for indices so the length of the array should atleast be equal to the value returned by getNumShapes(). The sort method uses the vzGraphicsState to get the transformation matrices used for sorting. This case requires the graphics state to be updated for every change to the viewing matrices. If the graphics state has not been set however, the class assumes a valid OpenGL context and queries the OpenGL transformation matrices using the glGetDoublev calls.

Note on Sorting:The ShapeSet currently implements two sorting algorithms. The default sorting algorithm uses an approximate sorting algorithm which sorts the shapes by distance from the view point. This algorithm might not give accurate results if the shapes are of different sizes and/or if they are intersecting.

If the shapes in the shape set consists of a regular grid of shapes which are axis aligned, the class will use a more accurate binary-space partition type algorithm to sort the shapes. The application can provide this information to the shape set using the setShapeGridDimensions() method. The shapes are assumed to be organized in a row-major order such that shape (i, j, k) is at position i + X * (j + Z * k) in the shape set.

If accurate sorting is critical, and the second sorting algorithm cannot be used, the application should implement its own sorting algorithm.

SEE ALSO

vzGraphicsState, vzObject, vzShape, vzShapeSet

Back to Index