pfSprite(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfSprite(3pf)NAME
pfSprite, pfGetCurSprite - Create and update sprite transformation
primitive.
FUNCTION SPECIFICATION
#include <Performer/pr/pfSprite.h>
pfSprite::pfSprite();
pfType * pfSprite::getClassType(void);
void pfSprite::setMode(int which, int val);
int pfSprite::getMode(int which);
void pfSprite::setAxis(float x, float y, float z);
void pfSprite::getAxis(float *x, float *y, float *z);
void pfSprite::begin(void);
void pfSprite::end(void);
void pfSprite::position(float x, float y, float z);
pfSprite * pfGetCurSprite(void);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfSprite is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfSprite. This is also true for
ancestor classes of class pfObject.
void* pfObject::operator new(size_t);
void* pfObject::operator new(size_t, void *arena);
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 pfSprite 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);
Page 1
pfSprite(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfSprite(3pf)
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();
DESCRIPTION
A "sprite" is a term borrowed from the video game industry and refers to
a movable graphical object that always appears orthogonal to the viewer.
In 2D, a sprite can be implemented by simply drawing an image that is
aligned with the screen, a technique called "bit-blitting". pfSprite
extends this support to 3D geometry by rotating the geometry
appropriately based on the viewer and object locations to achieve a
consistent screen alignment. In this respect, pfSprite is not really a
graphical object itself, rather it is an intelligent transformation and
is logically grouped with other libpr transformation primitives like
pfMultMatrix.
Sprite transformations (subsequently referred to as sprites) are useful
for complex objects that are roughly symmetrical about an axis or a
point. By rotating the model about the axis or point, the viewer only
sees the "front" of the model so complexity is saved in the model by
omitting the "back" geometry. A further performance enhancement is to
incorporate visual complexity in a texture map rather than in geometry.
Thus, on machines with fast texture mapping, sprites can present very
complex images with very little geometry. Classic examples of textured
sprites use a single quadrilateral that when rotated about a vertical
axis simulate trees and when rotated about a point simulate clouds or
puffs of smoke.
new(arena) allocates a pfSprite from the specified memory arena, or from
the heap if arena is NULL. new allocates a pfSprite from the default
memory arena (see pfGetSharedArena). Like other pfObjects, pfSprites
cannot be created statically, automatically on the stack or in arrays.
pfSprites should be deleted with pfDelete rather than the delete
operator.
pfSprite::getClassType returns the pfType* for the class pfSprite. The
pfType* returned by pfSprite::getClassType is the same as the pfType*
returned by invoking the virtual function getType on any instance of
Page 2
pfSprite(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfSprite(3pf)
class pfSprite. 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.
Sprite transformations are simply rotations which are based on:
1. The viewer location.
2. The sprite location.
3. The sprite mode/axis.
The viewer's coordinate system is specified with pfViewMat whose last row
is the viewer's location. The sprite location in object coordinates is
specified with pfSprite::position. This location is transformed by the
current modeling matrix (pfModelMat) into "world" coordinates before
computing the rotation based on the sprite mode.
pfSprite::setMode sets the which mode of the pfSprite to val. which
identifies a particular mode and is one of:
PFSPRITE_ROT val specifies the rotation constraints of the pfSprite
and is one of:
PFSPRITE_AXIAL_ROT
The +Z object coordinate axis of geometry is the axis of
rotation, i.e. the +Z object axis is rotated onto the sprite
axis defined by pfSprite::setAxis in eye space, then the
transformed -Y axis is rotated about the sprite axis to face
the viewer as nearly as possible.
PFSPRITE_POINT_ROT_EYE
The sprite rotation is constrained to rotate about the sprite
location specified by pfSprite::position. The object's -Y is
rotated to the eye's -Y (front vector), and then the objects's
Z axis is rotated about the front vector to point toward the
sprite axis (in eye coordinates) as nearly as possible. In
particular, if the sprite axis is +Z (the default), the object
+Z stays upright on the screen.
PFSPRITE_POINT_ROT_WORLD
This mode is identical to PFSPRITE_AXIAL_ROT except that the
sprite axis is interpreted as world coordinates rather than eye
coordinates.
The default PFSPRITE_ROT mode is PFSPRITE_AXIAL_ROT.
PFSPRITE_MATRIX_THRESHOLD
pfGeoSets which contain a number of vertices less than val will
be transformed on the CPU, rather than through the Graphics
Page 3
pfSprite(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfSprite(3pf)
Library transformation stack. If sprite is to affect non-
pfGeoSet geometry, then val should be <= 0 in which case the
Graphics Library transformation stack will always be used.
Specifically, pfSprite::begin will push the matrix stack,
pfSprite::position will modify the top of stack with the
current sprite rotation, and pfSprite::end will pop the matrix
stack. It is not necessary to push/pop the matrix stack within
pfSprite::begin/pfSprite::end. The default threshold value is
10.
pfSprite::getMode returns the value of the mode identified by which.
pfSprite::setAxis sets the pfSprite's axis to (x, y, z).
pfSprite::getAxis returns the axis of sprite in x, y, z.
pfSprite::begin makes the pfSprite the current pfSprite and applies its
effects to subsequently drawn pfGeoSets and non-pfGeoSet geometry if the
pfSprite's matrix threshold value is <= 0. pfSprite::position specifies
the sprite origin and pfSprite::end sets the current pfSprite to NULL and
exits "sprite mode". pfSprite::position may be called outside
pfSprite::begin/pfSprite::end and any number of times within
pfSprite::begin/pfSprite::end to render geometry with many different
origins but which share the characteristics of the pfSprite.
Example 1: Draw trees as axial sprites which rotate about +Z.
pfVec3 treeOrg[NUMTREES];
pfGeoSet *trees[NUMTREES];
sprite = new pfSprite;
sprite->begin();
for (i=0; i<NUMTREES; i++)
{
pfSprite::position(treeOrg[i][0], treeOrg[i][1], treeOrg[i][1]);
trees[i]->draw();
}
pfSprite::end();
pfSprite::begin, pfSprite::end, and pfSprite::position are all display-
listable commands. If a pfDispList has been opened by pfDispList::open,
these commands will not have immediate effect but will be captured by the
pfDispList and will only have effect when that pfDispList is later drawn
with pfDispList::draw.
Page 4
pfSprite(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfSprite(3pf)NOTES
Both PFSPRITE_AXIAL_ROT and PFSPRITE_POINT_ROT_WORLD sprites may "spin"
about the Y axis of the pfGeoSet when viewed along the rotation or
alignment axis.
SEE ALSO
pfDelete, pfDispList, pfGeoSet, pfModelMat, pfState, pfViewMat
Page 5
