pfuTraverser(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages
NAME
pfuInitTraverser, pfuTraverse, pfuTravPrintNodes, pfuTravGLProf,
pfuTravCountDB, pfuTravNodeHlight, pfuTravNodeAttrBind, pfuTravCalcBBox,
pfuTravCountNumVerts, pfuTravSetDListMode, pfuTravCompileDLists,
pfuTravDrawDLists, pfuTravCreatePackedAttrs, pfuFillGSetPackedAttrs,
pfuDelGSetAttrs, pfuTravCachedCull, pfuCalcDepth,
pfuLowestCommonAncestor, pfuLowestCommonAncestorOfGeoSets,
pfuFindTexture, pfuFindClipTextures - Useful scene graph traversals.
FUNCTION SPECIFICATION
#include <Performer/pfutil.h>
void pfuInitTraverser(pfuTraverser* trav);
int pfuTraverse(pfNode* node, pfuTraverser* trav);
void pfuTravPrintNodes(pfNode *node, const char *fname);
void pfuTravGLProf(pfNode *node, int mode);
void pfuTravCountDB(pfNode *node, pfFrameStats *fstats);
void pfuTravNodeHlight(pfNode *node, pfHighlight *hl);
void pfuTravNodeAttrBind(pfNode *node, unsigned int attr,
unsigned int bind);
void pfuTravCalcBBox(pfNode *node, pfBox *box);
int pfuTravCountNumVerts(pfNode *node);
void pfuTravSetDListMode(pfNode *node, int enable);
void pfuTravCompileDLists(pfNode *node, int delMask);
void pfuTravDrawDLists(pfNode *node);
void pfuTravCreatePackedAttrs(pfNode *node, int format,
int delMask);
void pfuFillGSetPackedAttrs(pfGeoSet *gset, int mask);
void pfuDelGSetAttrs(pfGeoSet *gset, int delMask);
void pfuTravCachedCull(pfNode* node, int numChans);
int pfuCalcDepth(pfNode *node);
pfNode * pfuLowestCommonAncestor(pfNode *scene, int (*fun)(pfNode*,
void*), void *arg, int travmode);
Page 1
pfuTraverser(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages
pfNode * pfuLowestCommonAncestorOfGeoSets(pfNode *scene,
int (*fun)(pfGeoSet*, void*), void *arg, int travmode);
pfNode * pfuFindTexture(pfNode *scene, int n, (*fun)(pfGeoState*,
pfTexture*, void*), void *arg, int travmode);
void pfuFindClipTextures(pfList *list, pfNode *scene);
struct _pfuTraverser
{
pfuTravFuncType preFunc;
pfuTravFuncType postFunc;
int mode;
int depth
pfNode *node;
pfMatStack *mstack;
void *data;
};
typedef struct _pfuTraverser pfuTraverser;
typedef int (*pfuTravFuncType)(pfuTraverser *trav);
DESCRIPTION
pfuTraverser provides a customizable, recursive traversal of an OpenGL
Performer scene graph. Traversals are useful for many things including
database queries like "find and activate all the pfSequence nodes in this
scene graph".
The pfuTraverser facility is used by initializing a pfuTraverser
structure and invoking pfuTraverse with the pfuTraverser and a target
pfNode. Custom database processing is carried out in the pre- and post-
traversal callbacks that are provided by the user.
pfuInitTraverser initializes trav to the following:
preFunc = postFunc = NULL
mode = PFUTRAV_SW_ALL | PFUTRAV_LOD_ALL | PFUTRAV_SEQ_ALL
mstack = NULL
data = NULL
mode is a bitmask indicating how to traverse nodes which have an explicit
(pfSwitch) or implicit (pfLOD) switch. The ALL, NONE, and CUR forms of
the PFUTRAV tokens indicate that the traversal should traverse all, none,
or just the current child of the specified node type, e.g.
PFUTRAV_SEQ_CUR will traverse the currently selected child of all
pfSequence nodes.
Page 2
pfuTraverser(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages
preFunc and postFunc are callbacks which are invoked before and after
each node in the hierarchy is visited. Callbacks are passed a pointer to
the current pfuTraverser structure and may access elements of the
pfuTraverser.
The node member references the current node in the traversal. data is a
pointer to user-data and if non-NULL, mstack will contain the matrix
stack of the traversal, i.e. all pfSCS and pfDCS nodes will push,
multiply and pop the pfMatStack represented by mstack. Memory management
of the pfMatStack` is the responsibility of the application.
The following functions provide a few specific examples of the
pfuTraverser utility. The specific traversals implemented are:
pfuTravPrintNodes
Recursively prints all nodes below node into file fname.
pfuTravGLProf
Outputs GLprof output tags. If mode is true then it places
glprof tag callbacks.
pfuTravCountDB
Accumulates stats for scene graph node into stats structure
fstats by traversing node with stats open.
pfuTravNodeHlight
Highlights all nodes below node by recursive traversal and
calling a highlight routine on each.
pfuTravNodeAttrBind
Recursively traverses node setting attr of each node under node
to the value bind.
pfuTravCalcBBox
Computes the bounding box of node and returns it in the
parameter box. If the node parameter is NULL, the returned box
will be an empty box.
pfuTravCountNumVerts
Returns the number of vertices in the scene graph rooted by
node.
pfuTravCachedCull
Installs callback functions for each node which cache CULL
results between frame updates.
pfuCalcDepth
Returns the depth of the scene graph pointed to by node. A
single root node with no children is counted as having depth 1.
Page 3
pfuTraverser(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages
pfuLowestCommonAncestor
Return the lowest common ancestor node of all nodes in the
scene graph rooted by scene for which fun(node, arg) != 0,
using the traversal mode given by travmode.
pfuLowestCommonAncestorOfGeoSets
Return the lowest common ancestor node of all geosets in the
scene graph rooted by scene for which fun(geoset, arg) != 0,
using the traversal mode given by travmode.
pfuFindTexture
Return the n'th texture occuring in the traversal of the scene
graph rooted by scene for which fun(geostate, texture, arg) !=
0, using the traversal mode given by travmode. Note that
textures occuring multiple times will be counted multiple
times; this behavior is a bug and may change in future
versions.
pfuTravSetDListMode
Enables and disables the pfGeoSet display-list rendering mode
on all nodes beneath node. The value of enable guides the
processing: non-zero enable will force display list mode and a
zero value will prevent it. If display lists for pfGeoSets in
the subtree are dirty or non-existant, they will be recreated
as they are drawn. Note that pfGeoSets under pfLODs or
pfSwitch nodes may not be immediately drawn, as pfGeoSets not
in view. To make sure all pfGeoSets are compiled immediately,
the pfuTravCompleDLists traversal should be used.
pfuTravCompleDLists
Will immediately compile all pfGeoSets beneath node. The
delMask argument indicates which (if any) of the pfGeoSet
attributes (vertex position, color, normal, and texture
coordinate) are to be deleted once the display list is built to
minimize storage consumption. Once these attributes are
deleted, then returning to immediate-mode rendering via a
second call to pfuTravSetDListMode will result in empty
pfGeoSets and lost geometry. This traversal must be executed in
the DRAW process, or in a thread that is sproced or in the same
address as the DRAW as it requires an active GL contect to
create the GL display lists for the DRAW. This traversal will
reach all pfGeoSets immediately for compilation.
pfuTravSetDListMode can then be used to select the display list
rendering mode.
pfuTravDrawDLists
will draw all pfGeoSets under node that have a draw mode of
PFGS_DRAW_GLOBJ. On an InfiniteReality graphics platform, this
will cause the GL display lists to be downloaded into the
local display list memory in the graphics subsystem for future
fast rendering. Even on other graphics platforms, there is
other additional optimization that might be done on the first
Page 4
pfuTraverser(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages
rendering of a display list.
pfuTravCreatePackedAttrs
This traversal builds a special packed pfGeoSet attribute array
representation (based on the OpenGL VertexArray facility) that
can speed rendering in many cases by reducing host overhead in
data transmission to the pipeline. The format argument
indicates which style of packed attribute data should be used.
Refer to the header files for details of the supported formats,
such as PFGS_PA_C4UBN3ST2FV3F and PFGS_PA_C4UBN3ST2F).
pfuFillGSetPackedAttrs constructs the packed attribute array
representation of gset using mask to determine what to pack and how to
pack it.
pfuDelGSetAttrs deletes the packed attribute arrays of gset using delMask
as a guide for the deletion operation.
pfuFindClipTexture traverses the nodes in the scenegraph whose root node
is scene, finding all the cliptextures in the scene, and collecting
pointers to them in the pfList list.
NOTES
The libpfutil source code, object code and documentation are provided as
unsupported software. Routines are subject to change in future releases.
SEE ALSO
pfFrameStats, pfGeoSet, pfNode, pfTraverser
Page 5
