pfSprite(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfSprite(3pf)NAME
pfNewSprite, pfGetSpriteClassType, pfSpriteMode, pfGetSpriteMode,
pfSpriteAxis, pfGetSpriteAxis, pfBeginSprite, pfEndSprite,
pfPositionSprite, pfGetCurSprite - Create and update sprite
transformation primitive.
FUNCTION SPECIFICATION
#include <Performer/pr.h>
pfSprite * pfNewSprite(void *arena);
pfType * pfGetSpriteClassType(void);
void pfSpriteMode(pfSprite *sprite, int which, int val);
int pfGetSpriteMode(const pfSprite *sprite, int which);
void pfSpriteAxis(pfSprite *sprite, float x, float y, float z);
void pfGetSpriteAxis(pfSprite *sprite, float *x, float *y,
float *z);
void pfBeginSprite(pfSprite *sprite);
void pfEndSprite(void);
void pfPositionSprite(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. Casting an object of
class pfSprite to an object of class pfObject is taken care of
automatically. This is also true for casts to objects of ancestor
classes 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 pfGetGLHandle(pfObject *obj);
int pfDeleteGLHandle(pfObject *obj);
Page 1
pfSprite(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfSprite(3pf)
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.
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
sprite identifies a pfSprite.
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.
pfNewSprite creates and returns a handle to a pfSprite. arena specifies
a malloc arena out of which the pfSprite is allocated or NULL for
allocation off the process heap. pfSprites can be deleted with pfDelete.
Page 2
pfSprite(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfSprite(3pf)
pfGetSpriteClassType returns the pfType* for the class pfSprite. The
pfType* returned by pfGetSpriteClassType is the same as the pfType*
returned by invoking pfGetType on any instance of 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 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.
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 pfPositionSprite. This location is transformed by the
current modeling matrix (pfModelMat) into "world" coordinates before
computing the rotation based on the sprite mode.
pfSpriteMode sets the which mode of sprite to val. which identifies a
particular mode and is one of:
PFSPRITE_ROT val specifies the rotation constraints of sprite 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 pfSpriteAxis 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 pfPositionSprite. 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.
Page 3
pfSprite(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfSprite(3pf)
PFSPRITE_MATRIX_THRESHOLD
pfGeoSets which contain a number of vertices less than val will
be transformed on the CPU, rather than through the Graphics
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, pfBeginSprite will push the matrix stack,
pfPositionSprite will modify the top of stack with the current
sprite rotation, and pfEndSprite will pop the matrix stack. It
is not necessary to push/pop the matrix stack within
pfBeginSprite/pfEndSprite. The default threshold value is 10.
pfGetSpriteMode returns the value of the mode identified by which.
pfSpriteAxis sets sprite's axis to (x, y, z). pfGetSpriteAxis returns
the axis of sprite in x, y, z.
pfBeginSprite makes sprite the current pfSprite and applies its effects
to subsequently drawn pfGeoSets and non-pfGeoSet geometry if sprite's
matrix threshold value is <= 0. pfPositionSprite specifies the sprite
origin and pfEndSprite sets the current pfSprite to NULL and exits
"sprite mode". pfPositionSprite may be called outside
pfBeginSprite/pfEndSprite and any number of times within
pfBeginSprite/pfEndSprite to render geometry with many different origins
but which share the characteristics of sprite.
Example 1: Draw trees as axial sprites which rotate about +Z.
pfVec3 treeOrg[NUMTREES];
pfGeoSet *trees[NUMTREES];
sprite = pfNewSprite(arena);
pfBeginSprite(sprite);
for (i=0; i<NUMTREES; i++)
{
pfPositionSprite(treeOrg[i][0], treeOrg[i][1], treeOrg[i][1]);
pfDrawGSet(trees[i]);
}
pfEndSprite();
pfBeginSprite, pfEndSprite, and pfPositionSprite are all display-listable
commands. If a pfDispList has been opened by pfOpenDList, 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 pfDrawDList.
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
