pfLOD(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfLOD(3pf)NAME
pfNewLOD, pfGetLODClassType, pfLODRange, pfGetLODRange,
pfGetLODNumRanges, pfLODTransition, pfGetLODTransition,
pfGetLODNumTransitions, pfLODRangeFlux, pfGetLODRangeFlux,
pfGetLODNumRangeFluxes, pfLODCenter, pfGetLODCenter, pfLODLODState,
pfGetLODLODState, pfLODLODStateIndex, pfGetLODLODStateIndex,
pfEvaluateLOD, pfLODUserEvalFunc, pfGetLODUserEvalFunc - Create, modify,
and query level of detail nodes.
FUNCTION SPECIFICATION
#include <Performer/pf.h>
pfLOD * pfNewLOD(void);
pfType * pfGetLODClassType(void);
void pfLODRange(pfLOD *lod, int index, float range);
float pfGetLODRange(const pfLOD *lod, int index);
int pfGetLODNumRanges(const pfLOD *lod);
void pfLODTransition(pfLOD *lod, int index,
float distance);
float pfGetLODTransition(const pfLOD *lod, int index);
int pfGetLODNumTransitions(const pfLOD *lod);
void pfLODRangeFlux(pfLOD *lod, int index, pfFlux *flux);
pfFlux* pfGetLODRangeFlux(const pfLOD *lod, int index);
int pfGetLODNumRangeFluxes(const pfLOD *lod);
void pfLODCenter(pfLOD *lod, pfVec3 center);
void pfGetLODCenter(const pfLOD *lod, pfVec3 center);
void pfLODLODState(pfLOD *lod, pfLODState *ls);
pfLODState* pfGetLODLODState(pfLOD *lod);
void pfLODLODStateIndex(pfLOD *lod, int index);
void pfGetLODLODStateIndex(pfLOD *lod);
float pfEvaluateLOD(pfLOD *lod, const pfChannel *chan,
const pfMatrix *offset);
Page 1
pfLOD(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfLOD(3pf)
void pfLODUserEvalFunc(pfLOD *lod,
pfLODEvalFuncType evalFunc);
pfLODEvalFuncType pfGetLODUserEvalFunc(pfLOD *lod);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfLOD is derived from the parent class
pfGroup, so each of these member functions of class pfGroup are also
directly usable with objects of class pfLOD. Casting an object of class
pfLOD 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 pfLOD 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);
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);
Page 2
pfLOD(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfLOD(3pf)
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 pfLOD 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 pfLOD 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
lod identifies a pfLOD.
typedef float (*pfLODEvalFuncType)
(pfLOD *lod, pfChannel *chan, pfMatrix *offset);
Page 3
pfLOD(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfLOD(3pf)DESCRIPTION
A pfLOD is a level-of-detail (LOD) node. Level-of-detail is a technique
for manipulating model complexity based on image quality and rendering
speed. Typically, a model is drawn in finer detail when close to the
viewer (occupies large screen area) than when it is far away (occupies
little screen area). In this way, costly detail is drawn only when
necessary.
Additionally, OpenGL Performer can adjust LODs based on rendering load.
If a scene is taking too long to draw, OpenGL Performer can globally
modify LODs so that they are drawn coarser and render time is reduced
(see pfChanStress).
OpenGL Performer uses range-based LOD and adjusts for field-of-view and
viewport pixel size. Range is computed as the distance from the
pfChannel eyepoint which is drawing the scene to a point designated as
the center of a pfLOD. This range is then potentially modified by
pfChannel attributes (see pfChanLODAttr, pfChanStress). This range
indexes the pfLOD range list to select a single child to draw.
pfLOD is derived from pfGroup so it can have children and use pfGroup API
to manipulate its child list. In addition to a list of children, a pfLOD
has a list of ranges which specify the transition points between levels-
of-detail. pfNewLOD creates and returns a handle to a pfLOD. Like other
pfNodes, pfLODs are always allocated from shared memory and can be
deleted using pfDelete.
pfGetLODClassType returns the pfType* for the class pfLOD. The pfType*
returned by pfGetLODClassType is the same as the pfType* returned by
invoking pfGetType on any instance of class pfLOD. 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.
pfLODCenter sets the object-space point which defines the center of lod.
center is affected by any transforms in the hierarchy above lod (see
pfSCS). pfGetLODCenter copies the LOD center point into center.
pfLODRange sets the value of range list element index to range which is a
floating point distance specified in world coordinates. A child is
selected based on the computed range (LODRange) from the eyepoint to the
pfLOD center and the range list (Ranges) according to the following
pseudocode decision test:
if (LODRange < Ranges[0])
draw nothing;
else
if (LODRange >= Ranges[i] && LODRange < Ranges[i+1])
draw Child[i];
else
if (LODRange >= Ranges[N-1] where N is length of Ranges)
Page 4
pfLOD(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfLOD(3pf)
draw nothing;
Ranges specified by pfLODRange must be positive and increasing with index
or results are undefined. pfGetLODRange returns the range with index
index and pfGetLODNumRanges returns the number of ranges currently set.
Normally, LOD transitions are abrupt switches that can cause distracting
visual artifacts. However, OpenGL Performer provides two ways to achieve
smooth LOD transitions. The first way is by having morphing LODs that
transition smoothly between the static LODs. The second way is to blend
between the LODs, by drawing both LODs during a transition range and
alpha blending between them. Morphing LODs tends to achieve better draw
performance because you are never drawing two LODs at once. But morphing
LODs do require special modeling and the morph engine will require some
amount of CPU time to calculate the morphed geometry. Blended LODs have
the advantage that no special modeling is required, and so it is easy to
enable blended LODs.
A morphing LOD is created by connecting a pfFlux to a pfLOD node using
pfLODRangeFlux. This pfFlux is then connected to the PFENG_MORPH_FRAME
source of one or more PFENG_MORPH pfEngines. When a LOD is selected,
which has a range flux attached, the range flux will be updated. The
value of the range flux will be between 0.0 and 1.0, depending on where
the computed range is within the range for the LOD. Morphing is
discussed in greater depth in the pfEngine man page.
Blended level-of-detail transitions are enabled by setting a non-zero
transition range with pfChanLODAttr. Blending is discussed in greater
depth in the pfChanLODAttr man page.
pfLODTransition sets the distance over which OpenGL Performer should
transition or "fade" between an lod's children. The number of
transitions is equal to the number of LOD children + 1. Thus
Transitions[0] specifies the distance over which LOD child 0 should fade
in. Transitions[1] specifies the distance over which OpenGL Performer
will fade between child 0 and child 1. Transitions[N] specifies the
distance over which the last lod child will fade out. Note that
performer will regulate the transition such that the fade will be
centered based on the ranges specified by pfLODRange. It is also
important to note the pfLODTransition distances should be specified such
that there is no overlap between transitions or reasonable, but
undefined, behavior will result. Thus, it is important to consider
pfLODRanges when specifying transition distances. pfGetLODTransition
returns the range with index index and pfGetLODNumRanges returns the
number of ranges currently set.
Note that in practice OpenGL Performer will multiply this transition
distance by a global transition scale (this scale is set by calls to
pfChanLODAttr with the PFLOD_FADE token).
Page 5
pfLOD(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfLOD(3pf)
The default behavior of pfLODTransition is that each transition is set to
a distance of 1.0 (except Transitions[0] which is set to 0.0 by default).
This makes it easy to specify a "global fade range" by controlling a
pfChanLODAttr attribute - PFLOD_FADE. By setting PFLOD_FADE to 10.0, all
transitions that have not be explicitly set will use 10.0 * 1.0 = 10.0 as
their fade distance (except Transitions[0] which will not fade at all).
Note that if one does not desire control over individual lod transitions,
it is not necessary to call pfLODTransition.
If a particular LOD is morphing you will probably want to set its
transitions to 0.0.
pfLODLODState associates the given pfLOD and pfLODState. This enables
the control of how a particular pfLOD responds to stress and range.
pfGetLODLODState returns the pfLODState associated with lod if there is
one or NULL if one does not exist.
pfLODLODStateIndex allows pfLODStates to be indexed on a per channel
basis. index is an index into an pfList of pfLODStates specified via
pfChanLODStateList. pfGetLODLODStateIndex returns the index currently
specified for lod or -1 if no index has been specified.
Note that if an out of range index is specified for a given pfLOD then
the pfLODState specified as the global pfLODState for that channel will
be used.
pfEvaluateLOD returns the index of the child that the Performer Cull
traversal would produce given a specific channel and matrix offset. The
integer portion of the return value represents the selected child, while
the floating point portion of the return is used to distinguish the fade
ratio between two visible lods if lod fading is turned on for the given
channel (see pfChanLODAttr). Thus an index of 1.0 would correspond to
Performer's decision to draw only child one. A value of 1.25 would mean
Performer would be 25% across the FADE transition between child one and
child two - meaning that child one would be 75% opaque while child two
would be 25% opaque. Similarly a value of 3.9 would represent child
three being 10% opaque (solid) while child four was 90% opaque. The
value -1.0 is returned when no children are visible. Note that negative
floating point values (like -.3) mean that Performer is currently fading
in child 0 and that it is 70% opaque. Thus return values will range from
-1.0 <= return value < N+1 where N is the number of children for the LOD.
(See pfChannel and pfLODState)
pfLODUserEvalFunc sets a user function for picking an LOD result. The
result of this user function is a floating point number similar to the
result of pfEvaluateLOD. pfGetLODUserEvalFunc returns the current user
evaluation function.
Page 6
pfLOD(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfLOD(3pf)NOTES
Intersection traversals currently always intersect with an LODRange of 0.
To intersect with other ranges, a pfSwitch with the same parent and
children as the pfLOD can be created with the pfLOD used for drawing and
the pfSwitch used for intersecting (see pfChanTravMask).
SEE ALSO
pfChanLODAttr, pfChanStress, pfChannel, pfGroup, pfLODState,
pfLookupNode, pfDelete
Page 7
