pfPartition(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
NAME
pfNewPart, pfGetPartClassType, pfPartVal, pfGetPartVal, pfPartAttr,
pfGetPartAttr, pfBuildPart, pfUpdatePart - Create and update pfPartition
spatial partitioning node.
FUNCTION SPECIFICATION
#include <Performer/pf.h>
pfPartition * pfNewPart(void);
pfType * pfGetPartClassType(void);
void pfPartVal(pfPartition* part, int which, float val);
float pfGetPartVal(pfPartition *part, int which);
void pfPartAttr(pfPartition* part, int which, void *attr);
void * pfGetPartAttr(pfPartition *part, int which);
void pfBuildPart(pfPartition* cset);
void pfUpdatePart(pfPartition* cset);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfPartition is derived from the parent class
pfGroup, so each of these member functions of class pfGroup are also
directly usable with objects of class pfPartition. Casting an object of
class pfPartition to an object of class pfGroup is taken care of
automatically. This is also true for casts to objects of ancestor
classes of class pfGroup.
int pfAddChild(pfGroup *group, pfNode *child);
int pfInsertChild(pfGroup *group, int index, pfNode *child);
int pfReplaceChild(pfGroup *group, pfNode *old, pfNode *new);
int pfRemoveChild(pfGroup *group, pfNode* child);
int pfSearchChild(pfGroup *group, pfNode* child);
pfNode * pfGetChild(const pfGroup *group, int index);
int pfGetNumChildren(const pfGroup *group);
int pfBufferAddChild(pfGroup *group, pfNode *child);
int pfBufferRemoveChild(pfGroup *group, pfNode *child);
Since the class pfGroup is itself derived from the parent class pfNode,
objects of class pfPartition can also be used with these functions
designed for objects of class pfNode.
pfGroup * pfGetParent(const pfNode *node, int i);
int pfGetNumParents(const pfNode *node);
void pfNodeBSphere(pfNode *node, pfSphere *bsph, int mode);
Page 1
pfPartition(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
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);
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 pfPartition 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 pfPartition 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);
Page 2
pfPartition(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
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);
DESCRIPTION
A pfPartition is a type of pfGroup for organizing the subgraph of a scene
into a static data structure which is more efficient for intersection
testing with pfNodeIsectSegs for some databases. pfPartition does not
affect culling performance nor does it improve intersection performance
under transformation nodes, pfSwitch nodes, pfMorph nodes or pfSequence
nodes.
pfNewPart creates and returns a handle to a pfPartition. Like other
pfNodes, pfPartitions are always allocated from shared memory and can be
deleted using pfDelete.
pfGetPartClassType returns the pfType* for the class pfPartition. The
pfType* returned by pfGetPartClassType is the same as the pfType*
returned by invoking pfGetType on any instance of class pfPartition.
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.
pfBuildPart constructs a 2D spatial partitioning based on the type.
Within the confines of the parameters set by pfPartAttr, OpenGL Performer
attempts to construct an optimal partition based on the distribution of
vertices within the pfGeoSets in the subgraph of the scene rooted at the
partition. Information about the selected partitioning is displayed when
the pfNotifyLevel is debug or higher. Because the search for the optimal
partitioning is compute intensive, once the partitioning has been
determined for a particular database, the range of the search should be
restricted using pfPartAttr.
pfUpdatePart causes the scene graph under the partition to be traversed
and any changes incorporated into the spatial partitioning. The
partitioning itself does not change.
pfPartAttr sets the partition attribute attr to the attribute attr.
Partition attributes are:
Page 3
pfPartition(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
PFPART_MIN_SPACING
attr points to a pfVec3 specifying the minimum spacing between
partition dividers in each dimension. If not specified, the
default is 1/20th of the bounding box diagonal. When a
partition is built, a search is made between PFPART_MAX_SPACING
and PFPART_MIN_SPACING.
PFPART_MAX_SPACING
attr points to a pfVec3 specifying the maximum spacing between
partition dividers in each dimension. If not specified, the
default is 1/10th of the bounding box diagonal. When a
partition is built, a search is made between PFPART_MAX_SPACING
and PFPART_MIN_SPACING.
PFPART_ORIGIN
attr points to a pfVec3 specifying an origin for the partition.
If not specified, a search is done to find an optimal origin.
pfGetPartAttr returns the partition attribute attr.
pfPartVal sets the partition value val to the value val. Partition
values are:
PFPART_FINENESS
A value between 0.0 and 1.0 which indicates how fine of a
partitioning should be constructed. The subdivision is limited
by PFPART_MIN_SPACING and PFPART_MAX_SPACING. 1.0 causes
extremely fine subdivision. 0.0 causes no subdivision. 0.5 is
usually a good value and is the default.
pfGetPartVal returns the partition value val.
A pfPartition behaves like a pfGroup when the mode in the pfSegSet used
with pfNodeIsectSegs includes PFTRAV_IS_NO_PART.
NOTES
pfPartitions are primarily useful for databases containing many axis-
aligned objects for which bounding spheres are a poor fit and when only
one or two segments are made per call to pfNodeIsectSegs. For example,
terrain following on gridded terrain is likely to benefit. For databases
such as this which themselves have a regular grid, it is also important
for performance that the origin and spacing of the partition align
exactly the terrain grid. pfPartitions do not currently help with the
problem pfGeoSets containing too much geometry.
BUGS
The search for an optimal grid is very thorough so that it takes a very
long time if the search domain is large. Once a good partitioning for a
database is determined, the PFPART_MIN_SPACING, PFPART_MAX_SPACING and
PFPART_ORIGIN can be set equal for much faster building.
Page 4
pfPartition(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
Currently only partitionings in the XY plane are supported.
SEE ALSO
pfGroup, pfLookupNode, pfNode, pfNodeIsectSegs, pfNotifyLevel, pfScene
Page 5
