pfGeode(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfGeode(3pf)NAME
pfNewGeode, pfGetGeodeClassType, pfAddGSet, pfRemoveGSet, pfInsertGSet,
pfReplaceGSet, pfGetGSet, pfGetNumGSets - Create, modify, and query a
geometry node.
FUNCTION SPECIFICATION
#include <Performer/pf.h>
pfGeode * pfNewGeode(void);
pfType * pfGetGeodeClassType(void);
int pfAddGSet(pfGeode* geode, pfGeoSet* gset);
int pfRemoveGSet(pfGeode* geode, pfGeoSet* gset);
int pfInsertGSet(pfGeode* geode, int index, pfGeoSet* gset);
int pfReplaceGSet(pfGeode* geode, pfGeoSet* old, pfGeoSet* new);
pfGeoSet * pfGetGSet(const pfGeode* geode, int index);
int pfGetNumGSets(const pfGeode* geode);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfGeode is derived from the parent class
pfNode, so each of these member functions of class pfNode are also
directly usable with objects of class pfGeode. Casting an object of
class pfGeode to an object of class pfNode is taken care of
automatically. This is also true for casts to objects of ancestor
classes of class pfNode.
pfGroup * pfGetParent(const pfNode *node, int i);
int pfGetNumParents(const pfNode *node);
void pfNodeBSphere(pfNode *node, pfSphere *bsph, int mode);
int pfGetNodeBSphere(pfNode *node, pfSphere *bsph);
pfNode* pfClone(pfNode *node, int mode);
pfNode* pfBufferClone(pfNode *node, int mode, pfBuffer *buf);
int pfFlatten(pfNode *node, int mode);
int pfNodeName(pfNode *node, const char *name);
const char * pfGetNodeName(const pfNode *node);
pfNode* pfFindNode(pfNode *node, const char *pathName,
pfType *type);
pfNode* pfLookupNode(const char *name, pfType* type);
int pfNodeIsectSegs(pfNode *node, pfSegSet *segSet,
pfHit **hits[]);
void pfNodeTravMask(pfNode *node, int which, uint mask,
int setMode, int bitOp);
uint pfGetNodeTravMask(const pfNode *node, int which);
void pfNodeTravFuncs(pfNode* node, int which,
pfNodeTravFuncType pre, pfNodeTravFuncType post);
Page 1
pfGeode(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfGeode(3pf)
void pfGetNodeTravFuncs(const pfNode* node, int which,
pfNodeTravFuncType *pre, pfNodeTravFuncType *post);
void pfNodeTravData(pfNode *node, int which, void *data);
void * pfGetNodeTravData(const pfNode *node, int which);
void pfNodeTravMode(pfNode* node, int which, int mode,
int val);
int pfGetNodeTravMode(const pfNode* node, int which,
int mode);
Since the class pfNode is itself derived from the parent class pfObject,
objects of class pfGeode can also be used with these functions designed
for objects of class pfObject.
void pfUserDataSlot(pfObject *obj, int slot, void *data);
void pfUserData(pfObject *obj, void *data);
void* pfGetUserDataSlot(pfObject *obj, int slot);
void* pfGetUserData(pfObject *obj);
int pfGetNumUserData(pfObject *obj);
int pfGetNamedUserDataSlot(const char *name);
const char* pfGetUserDataSlotName(int slot);
int pfGetNumNamedUserDataSlots(void);
int pfDeleteGLHandle(pfObject *obj);
Since the class pfObject is itself derived from the parent class
pfMemory, objects of class pfGeode can also be used with these functions
designed for objects of class pfMemory.
pfType * pfGetType(const void *ptr);
int pfIsOfType(const void *ptr, pfType *type);
int pfIsExactType(const void *ptr, pfType *type);
const char * pfGetTypeName(const void *ptr);
int pfRef(void *ptr);
int pfUnref(void *ptr);
int pfUnrefDelete(void *ptr);
int pfUnrefGetRef(void *ptr);
int pfGetRef(const void *ptr);
int pfCopy(void *dst, void *src);
int pfDelete(void *ptr);
int pfIsFluxed(void *ptr);
int pfCompare(const void *ptr1, const void *ptr2);
void pfPrint(const void *ptr, uint which, uint verbose,
FILE *file);
void * pfGetArena(void *ptr);
PARAMETERS
geode identifies a pfGeode.
Page 2
pfGeode(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfGeode(3pf)DESCRIPTION
The name "pfGeode" is short for Geometry Node. A pfGeode is a leaf node
in the OpenGL Performer scene graph hierarchy and is derived from pfNode
so it can use pfNode API. A pfGeode is simply a list of pfGeoSets which
it draws and intersects with. A pfGeode is the smallest cullable unit
unless PFCULL_GSET is set by pfChanTravMode in which case OpenGL
Performer will cull individual pfGeoSets within pfGeodes.
The bounding volume of a pfGeode is that which surrounds all its
pfGeoSets. Unless the bounding volume is considered static (see
pfNodeBSphere), OpenGL Performer will compute a new volume when the list
of pfGeoSets is modified by pfAddGSet, pfRemoveGSet, pfInsertGSet or
pfReplaceGSet. If the bounding box of a child pfGeoSet changes, call
pfNodeBSphere to tell OpenGL Performer to update the bounding volume of
the pfGeode.
pfNewGeode creates and returns a handle to a pfGeode. Like other
pfNodes, pfGeodes are always allocated from shared memory and can be
deleted using pfDelete.
pfGetGeodeClassType returns the pfType* for the class pfGeode. The
pfType* returned by pfGetGeodeClassType is the same as the pfType*
returned by invoking pfGetType on any instance of class pfGeode. Because
OpenGL Performer allows subclassing of built-in types, when decisions are
made based on the type of an object, it is usually better to use
pfIsOfType to test if an object is of a type derived from a Performer
type rather than to test for strict equality of the pfType*'s.
pfAddGSet appends gset to geode's pfGeoSet list. pfRemoveGSet removes
gset from the list and shifts the list down over the vacant spot. For
example, if gset had index 0, then index 1 becomes index 0, index 2
becomes index 1 and so on. pfRemoveGSet returns a 1 if gset was actually
removed and 0 if it was not found in the list. pfAddGSet and
pfRemoveGSet will cause OpenGL Performer to recompute new bounding
volumes for geode unless it is configured to use static bounding volumes.
pfInsertGSet will insert gset before the pfGeoSet with index index.
index must be within the range 0 to pfGetNumGSets(geode). pfReplaceGSet
replaces old with new and returns 1 if the operation was successful or 0
if old was not found in the list. pfInsertGSet and pfReplaceGSet will
cause OpenGL Performer to recompute new bounding volumes for geode unless
it is configured to use static bounding volumes.
pfGetNumGSets returns the number of pfGeoSets in geode. pfGetGSet
returns a handle to the pfGeoSet with index index or NULL if the index is
out of range.
If database sorting is disabled, that is if the PFCULL_SORT mode of
pfChanTravMode is not set, the pfGeoSets in a pfGeode will be drawn in
the order they appear on the list. If sorting is enabled, there is no
guarantee about the drawing order, since the reordering of GeoSets for
Page 3
pfGeode(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfGeode(3pf)
minimum state-changing overhead is one of the primary design motivations
of OpenGL Performer's libpf and libpr.
NOTES
pfGeode geometry is not multibuffered by OpenGL Performer when in
multiprocessing mode in order to save memory. Therefore there are some
restrictions on dynamic geometry. Modified vertex positions will be
culled properly only if a static bound is defined which surrounds all
possible excursions of the dynamic geometry. Since the draw process may
be drawing the geometry at the same time the application process is
modifying it, cracks may appear between polygons which share a dynamic
vertex. Creation and deletion of vertices are not currently supported by
OpenGL Performer. However, the application may handle its own
multibuffering of pfGeodes through mutual exclusion with locks or through
the use of parallel data structures and pfSwitch nodes to achieve any
kind of dynamic geometry.
The shifting behavior of pfRemoveGSet can cause some confusion. The
following sample code shows how to remove all pfGeoSets from geode:
int i;
int n = pfGetNumGSets(geode);
for (i = 0; i < n; i++)
pfRemoveGSet(geode, pfGetGSet(geode, 0)); /* 0, not i */
Alternately, you can traverse the list from back to front, in which case
the shift never hits the fan.
int i;
int n = pfGetNumGSets(geode);
for (i = n - 1; i >= 0; i--)
pfRemoveGSet(geode, pfGetGSet(geode, i)); /* i, not 0 */
When sorting is enabled (see pfChanTravMode and PFCULL_SORT), transparent
pfGeoSets are drawn last unless the pfGeode has a pre or post draw
callback (see pfNodeTravFuncs). Drawing transparent pfGeoSets after
opaque geometry reduces artifacts when blended transparency (see
pfTransparency) is used and can improve fill rate performance.
SEE ALSO
pfChanTravMode, pfGeoSet, pfNode, pfNodeTravFuncs, pfTransparency,
pfDelete
Page 4
