pfBillboard(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
NAME
pfNewBboard, pfGetBboardClassType, pfBboardPos, pfGetBboardPos,
pfBboardPosFlux, pfGetBboardPosFlux, pfBboardMode, pfGetBboardMode,
pfBboardAxis, pfGetBboardAxis - Create and update automatic rotation
billboard nodes.
FUNCTION SPECIFICATION
#include <Performer/pf.h>
pfBillboard * pfNewBboard(void);
pfType * pfGetBboardClassType(void);
void pfBboardPos(pfBillboard* bill, int i,
const pfVec3 xyzOrigin);
void pfGetBboardPos(pfBillboard* bill, int i,
pfVec3 xyzOrigin);
void pfBboardPosFlux(pfBillboard* bill, pfFlux *flux);
pfFlux * pfGetBboardPosFlux(pfBillboard* bill);
void pfBboardMode(pfBillboard* bill, int mode, int val);
int pfGetBboardMode(pfBillboard* bill, int mode);
void pfBboardAxis(pfBillboard* bill, const pfVec3 axis);
void pfGetBboardAxis(pfBillboard* bill, 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. Casting an object of
class pfBillboard to an object of class pfGeode is taken care of
automatically. This is also true for casts to objects of ancestor
classes of class pfGeode.
int pfAddGSet(pfGeode* geode, pfGeoSet* gset);
int pfRemoveGSet(pfGeode* geode, pfGeoSet* gset);
int pfInsertGSet(pfGeode* geode, int index, pfGeoSet* gset);
int pfReplaceGSet(pfGeode* geode, pfGeoSet* old, pfGeoSet* new);
pfGeoSet * pfGetGSet(const pfGeode* geode, int index);
int pfGetNumGSets(const pfGeode* geode);
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.
Page 1
pfBillboard(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
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);
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 pfBillboard 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 pfBillboard 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);
Page 2
pfBillboard(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
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);
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 pfAddGSet and pfRemoveGSet
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.
pfNewBboard creates and returns a handle to a pfBillboard. Like other
pfNodes, pfBillboards are always allocated from shared memory and can be
deleted using pfDelete.
pfGetBboardClassType returns the pfType* for the class pfBillboard. The
pfType* returned by pfGetBboardClassType is the same as the pfType*
returned by invoking pfGetType 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 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.
pfBboardPos specifies the position xyzOrigin for the pfGeoSet with index
i. pfGetBboardPos 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 pfBboardAxis. 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
Page 3
pfBillboard(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
billboard is specified by setting the PFBB_ROT mode of the billboard to
the value PFBB_AXIAL_ROT using pfBboardMode. The axis of rotation (x, y,
z) is specified using pfBboardAxis. pfGetBboardAxis returns the axis of
the pfBillboard.
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 pfBboardAxis, 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
pfBboardAxis (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.
pfBboardPosFlux 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. pfGetBboardPosFlux
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
pfAddGSet, pfRemoveGSet, pfChanTravMode, pfFlatten, pfLookupNode,
pfNodeTravFuncs, pfFlux, pfScene, pfTransparency, pfDelete
Page 5
