pfBillboard(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
NAMEpfBillboard - Create and update automatic rotation billboard nodes.
FUNCTION SPECIFICATION
#include <Performer/pf/pfBillboard.h>
pfBillboard::pfBillboard();
static pfType * pfBillboard::getClassType(void);
void pfBillboard::setPos(int i, const pfVec3 &xyzOrigin);
void pfBillboard::getPos(int i, pfVec3 &xyzOrigin);
void pfBillboard::setPosFlux(pfFlux *flux);
pfFlux * pfBillboard::getPosFlux(void);
void pfBillboard::setMode(int mode, int val);
int pfBillboard::getMode(int mode);
void pfBillboard::setAxis(const pfVec3 &axis);
void pfBillboard::getAxis(pfVec3 &axis);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfBillboard is derived from the parent class
pfGeode, so each of these member functions of class pfGeode are also
directly usable with objects of class pfBillboard. This is also true for
ancestor classes of class pfGeode.
int pfGeode::addGSet(pfGeoSet* gset);
int pfGeode::removeGSet(pfGeoSet* gset);
int pfGeode::insertGSet(int index, pfGeoSet* gset);
int pfGeode::replaceGSet(pfGeoSet* old, pfGeoSet* new);
pfGeoSet * pfGeode::getGSet(int index);
int pfGeode::getNumGSets(void);
Since the class pfGeode is itself derived from the parent class pfNode,
objects of class pfBillboard 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);
Page 1
pfBillboard(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
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 pfBillboard 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);
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 pfBillboard 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();
Page 2
pfBillboard(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
int pfMemory::unrefGetRef();
int pfMemory::getRef();
int pfMemory::checkDelete();
int pfMemory::isFluxed();
void * pfMemory::getArena();
int pfMemory::getSize();
DESCRIPTION
A pfBillboard is a pfGeode in which each pfGeoSet rotates to follow the
eyepoint. Billboards are useful for complex objects which are roughly
symmetrical about one or more axes. The billboard tracks the viewer by
rotating about an axis or a point to present the same image to the viewer
using far fewer polygons than a solid model. A classic example is a
textured billboard of a single quadrilateral representing a tree.
A pfBillboard can contain any number of pfGeoSets. pfGeoSets are added
to and removed from the pfBillboard using the pfGeode::addGSet and
pfGeode::removeGSet routines used with pfGeodes. Each pfGeoSet rotates
independently to follow the viewer. By convention, the pfGeoSet is
rotated about the +Z axis so that the +Y axis points towards the eye
point.
new pfBillboard creates and returns a handle to a pfBillboard. Like
other pfNodes, pfBillboards are always allocated from shared memory and
cannot be created statically, on the stack or in arrays. pfBillboards
should be deleted using pfDelete rather than the delete operator.
pfBillboard::getClassType returns the pfType* for the class pfBillboard.
The pfType* returned by pfBillboard::getClassType is the same as the
pfType* returned by invoking the virtual function getType on any instance
of class pfBillboard. 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.
pfBboardPos specifies the position xyzOrigin for the pfGeoSet with index
i. pfBillboard::getPos copies the position of the pfGeoSet with index i
into xyzOrigin.
Billboards can either rotate about an axis or a point.
Axial billboards rotate about the axis specified by pfBillboard::setAxis.
The rotation is about the origin (0,0,0) of the pfGeoSet. In all cases,
the geometry is modeled in the XZ plane, with +Y forward. When rendered,
the billboard is rotated so that the -Y axis points back to the eye
point. The +Z axis is the pfGeoSet's axis of rotation. An axial rotate
billboard is specified by setting the PFBB_ROT mode of the billboard to
the value PFBB_AXIAL_ROT using pfBillboard::setMode. The axis of
rotation (x, y, z) is specified using pfBillboard::setAxis.
pfBillboard::getAxis returns the axis of the pfBillboard.
Page 3
pfBillboard(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
Point rotate billboards are useful for spherical objects or special
effects such as smoke. They come in two varieties depending on how the
remaining rotational degree of freedom is determined (rotating the -Y
axis towards the eye, still leaves an arbitrary rotation about the
pfGeoSet's Y axis).
If the PFBB_ROT mode on the billboard is set to PFBB_POINT_ROT_EYE,
the billboard is rotated so that the +Z axis of the pfGeoSet aligns
as closely as possible with the axis specified with
pfBillboard::setAxis, in eye space. In particular, if the axis is
+Z (as it is by default), the +Z axis of the pfGeoSet stays upright
on the screen.
If the PFBB_ROT mode on the billboard is set to
PFBB_POINT_ROT_WORLD, the billboard is rotated so that the angle
between the +Z axis of the pfGeoSet and axis specified with
pfBillboard::setAxis (in world space) is minimized.
Both PFBB_AXIAL_ROT and PFBB_POINT_ROT_WORLD billboards may "spin" about
the Y axis of the pfGeoSet when viewed along the rotation or alignment
axis.
pfBillboard::setPosFlux will set a pfFlux to be used to contain the xyz
origins of all the pfGeoSets under a pfBillboard node. The data size of
position flux should be equal to the number of pfGeoSets under the
pfBillboard multiplied by the size of pfVec3. Having the origins in a
flux allows you to animate the origins to align them to a pfASD.
pfBillboard::getPosFlux returns the current position flux is there is
one.
After the first pfSync, the number of pfGeoSets, the number and length of
the primitives, and planarity of the vertices should not be changed.
Some database formats may place a transformation above each billboard for
positioning it. As with a pfGeode containing a small amount of geometry,
having many billboards with transformation matrices above them can be
expensive.
Since billboards always rotate towards the eyepoint, billboards in
adjacent channels with the same eyepoint have the same orientation.
Channels with different eyepoints will have different billboard
orientations.
NOTES
Prior to Performer 3.2, intersection traversals test only the
pfBillboard's bounding volume, not its individual pfGeoSets. As of
Performer 3.2 and beyond, intersection traversals also test the
pfBillboard's (transformed) pfGeoSets. To revert to the original
behavior, set PF_BILLBOARD_DISABLE_ISECT to 1.
Page 4
pfBillboard(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
BUGS
pfFlatten only transforms the position of a billboard, not the axis and
applies only a uniform scale to the billboard geometry.
SEE ALSO
pfChannel, pfGeode, pfNode, pfFlux, pfScene, pfTransparency, pfDelete
Page 5
