pfLOD(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages pfLOD(3pf)NAMEpfLOD - Create, modify, and query level of detail nodes.
FUNCTION SPECIFICATION
#include <Performer/pf/pfLOD.h>
pfLOD::pfLOD();
static pfType * pfLOD::getClassType(void);
void pfLOD::setRange(int index, float range);
float pfLOD::getRange(int index);
int pfLOD::getNumRanges(void);
void pfLOD::setTransition(int index, float distance);
float pfLOD::getTransition(int index);
int pfLOD::getNumTransitions(void);
void pfLOD::setRangeFlux(int index, pfFlux *flux);
pfFlux* pfLOD::getRangeFlux(int index);
int pfLOD::getNumRangeFluxes(void);
void pfLOD::setCenter(pfVec3 ¢er);
void pfLOD::getCenter(pfVec3 ¢er);
void pfLOD::setLODState(pfLODState *ls);
pfLODState* pfLOD::getLODState(void);
void pfLOD::setLODStateIndex(int index);
void pfLOD::getLODStateIndex(void);
float pfLOD::evaluate(const pfChannel *chan,
const pfMatrix *offset);
void pfLOD::setUserEvalFunc(pfLOD *lod,
pfLODEvalFuncType evalFunc);
pfLODEvalFuncType pfLOD::getUserEvalFunc(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. This is also true for
Page 1
pfLOD(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages pfLOD(3pf)
ancestor classes of class pfGroup.
int pfGroup::addChild(pfNode *child);
int pfGroup::insertChild(int index, pfNode *child);
int pfGroup::replaceChild(pfNode *old, pfNode *new);
int pfGroup::removeChild(pfNode* child);
int pfGroup::searchChild(pfNode* child);
pfNode * pfGroup::getChild(int index);
int pfGroup::getNumChildren(void);
int pfGroup::bufferAddChild(pfNode *child);
int pfGroup::bufferRemoveChild(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 * pfNode::getParent(int i);
int pfNode::getNumParents(void);
void pfNode::setBound(pfSphere *bsph, int mode);
int pfNode::getBound(pfSphere *bsph);
pfNode* pfNode::clone(int mode);
pfNode* pfNode::bufferClone(int mode, pfBuffer *buf);
int pfNode::flatten(int mode);
int pfNode::setName(const char *name);
const char * pfNode::getName(void);
pfNode* pfNode::find(const char *pathName, pfType *type);
pfNode* pfNode::lookup(const char *name, pfType* type);
int pfNode::isect(pfSegSet *segSet, pfHit **hits[]);
void pfNode::setTravMask(int which, uint mask, int setMode,
int bitOp);
uint pfNode::getTravMask(int which);
void pfNode::setTravFuncs(int which, pfNodeTravFuncType pre,
pfNodeTravFuncType post);
void pfNode::getTravFuncs(int which, pfNodeTravFuncType *pre,
pfNodeTravFuncType *post);
void pfNode::setTravData(int which, void *data);
void * pfNode::getTravData(int which);
void pfNode::setTravMode(int which, int mode, int val);
int pfNode::getTravMode(int which, int mode) const;
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* pfObject::operator new(size_t);
void* pfObject::operator new(size_t, pfFluxMemory *fmem);
void pfObject::setUserData(void *data);
void pfObject::setUserData(int slot, void *data);
Page 2
pfLOD(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages pfLOD(3pf)
void* pfObject::getUserData(pfObject *obj);
void* pfObject::getUserData(pfObject *obj, int slot);
int pfObject::getNumUserData();
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.
void* pfMemory::getData(const void *ptr);
pfType * pfMemory::getType();
int pfMemory::isOfType(pfType *type);
int pfMemory::isExactType(pfType *type);
const char * pfMemory::getTypeName();
int pfMemory::copy(pfMemory *src);
int pfMemory::compare(const pfMemory *mem);
void pfMemory::print(uint which, uint verbose, char *prefix,
FILE *file);
int pfMemory::getArena(void *ptr);
void* pfMemory::getArena();
int pfMemory::ref();
int pfMemory::unref();
int pfMemory::unrefDelete();
int pfMemory::unrefGetRef();
int pfMemory::getRef();
int pfMemory::checkDelete();
int pfMemory::isFluxed();
void * pfMemory::getArena();
int pfMemory::getSize();
PARAMETERS
lod identifies a pfLOD.
typedef float (*pfLODEvalFuncType)
(pfLOD *lod, pfChannel *chan, pfMatrix *offset);
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 pfChannel::setStress).
OpenGL Performer uses range-based LOD and adjusts for field-of-view and
Page 3
pfLOD(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages pfLOD(3pf)
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 pfChannel::setLODAttr, pfChannel::setStress).
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. new pfLOD creates and returns a handle to a pfLOD. Like
other pfNodes, pfLODs are always allocated from shared memory and cannot
be created statically, on the stack or in arrays. pfLODs should be
deleted using pfDelete rather than the delete operator.
pfLOD::getClassType returns the pfType* for the class pfLOD. The pfType*
returned by pfLOD::getClassType is the same as the pfType* returned by
invoking the virtual function getType 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 the member function isOfType 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.
pfLOD::setCenter sets the object-space point which defines the center of
the pfLOD. center is affected by any transforms in the hierarchy above
the pfLOD (see pfSCS). pfLOD::getCenter copies the LOD center point into
center.
pfLOD::setRange 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)
draw nothing;
Ranges specified by pfLOD::setRange must be positive and increasing with
index or results are undefined. pfLOD::getRange returns the range with
index index and pfLOD::getNumRanges 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
Page 4
pfLOD(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages pfLOD(3pf)
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
pfLOD::setRangeFlux. 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 pfChannel::setLODAttr. Blending is discussed in
greater depth in the pfChannel::setLODAttr man page.
pfLOD::setTransition 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. pfLOD::getTransition
returns the range with index index and pfLOD::getNumRanges 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
pfChannel::setLODAttr with the PFLOD_FADE token).
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
pfChannel::setLODAttr 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 pfLOD::setTransition.
Page 5
pfLOD(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages pfLOD(3pf)
If a particular LOD is morphing you will probably want to set its
transitions to 0.0.
pfLOD::setLODState associates the given pfLOD and pfLODState. This
enables the control of how a particular pfLOD responds to stress and
range. pfLOD::getLODState returns the pfLODState associated with lod if
there is one or NULL if one does not exist.
pfLOD::setLODStateIndex allows pfLODStates to be indexed on a per channel
basis. index is an index into an pfList of pfLODStates specified via
pfChannel::setLODStateList. pfLOD::getLODStateIndex returns the index
currently specified for the pfLOD 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.
pfLOD::evaluate 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 pfChannel::setLODAttr). 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)
pfLOD::setUserEvalFunc 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 pfLOD::evaluate. pfLOD::getUserEvalFunc returns the
current user evaluation function.
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 pfChannel::setTravMask).
SEE ALSO
pfChannel, pfGroup, pfLODState, pfNode, pfDelete
Page 6
