pfMatStack(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
NAME
pfNewMStack, pfGetMStackClassType, pfResetMStack, pfPushMStack,
pfPopMStack, pfPreMultMStack, pfPostMultMStack, pfLoadMStack,
pfGetMStack, pfGetMStackTop, pfGetMStackDepth, pfPreTransMStack,
pfPostTransMStack, pfPreRotMStack, pfPostRotMStack, pfPreScaleMStack,
pfPostScaleMStack - Create and manipulate a matrix stack.
FUNCTION SPECIFICATION
#include <Performer/pr.h>
pfMatStack * pfNewMStack(int size, void *arena);
pfType * pfGetMStackClassType(void);
void pfResetMStack(pfMatStack *stack);
int pfPushMStack(pfMatStack *stack);
int pfPopMStack(pfMatStack *stack);
void pfPreMultMStack(pfMatStack *stack, const pfMatrix m);
void pfPostMultMStack(pfMatStack *stack, const pfMatrix m);
void pfLoadMStack(pfMatStack *stack, const pfMatrix m);
void pfGetMStack(const pfMatStack *stack, pfMatrix m);
pfMatrix * pfGetMStackTop(const pfMatStack *stack);
int pfGetMStackDepth(const pfMatStack *stack);
void pfPreTransMStack(pfMatStack *stack, float x, float y,
float z);
void pfPostTransMStack(pfMatStack *stack, float x, float y,
float z);
void pfPreRotMStack(pfMatStack *stack, float degrees, float x,
float y, float z);
void pfPostRotMStack(pfMatStack *stack, float degrees, float x,
float y, float z);
void pfPreScaleMStack(pfMatStack *stack, float xs, float ys,
float zs);
void pfPostScaleMStack(pfMatStack *stack, float xs, float ys,
float zs);
Page 1
pfMatStack(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfMatStack is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfMatStack. Casting an object of
class pfMatStack 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);
Since the class pfObject is itself derived from the parent class
pfMemory, objects of class pfMatStack 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);
DESCRIPTION
These routines allow the creation and manipulation of a stack of 4x4
matrices.
pfNewMStack creates and returns a handle to a pfMatStack. arena
specifies a malloc arena out of which the pfMatStack is allocated or NULL
for allocation off the process heap. pfMatStacks can be deleted with
pfDelete. size is the number of pfMatrix's in the matrix stack. The
initial depth is 1 and the top of stack is the identity matrix.
pfGetMStackClassType returns the pfType* for the class pfMatStack. The
Page 2
pfMatStack(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
pfType* returned by pfGetMStackClassType is the same as the pfType*
returned by invoking pfGetType on any instance of class pfMatStack.
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.
pfResetMStack sets the stack depth to 1 and sets the top of stack to the
identity matrix.
pfPushMStack pushes down the specified matrix stack duplicating the top.
pfPopMStack pops the matrix stack. Attempting to pop a matrix stack
containing only a single element or pushing past the maximum depth causes
a warning and leaves the stack unchanged.
pfPreMultMStack pre-multiplies the top of the stack by the matrix m and
replaces the top of the stack with the product. Thus if T is the top of
the stack, the operation replaces T with m*T. This order corresponds to
that used by OpenGL's glMultMatrix. pfPostMultMStack operates similarly
but using post-multiplication, calculating T*m instead.
pfLoadMStack replaces the top of the stack with the matrix m.
pfGetMStack copies the top of the matrix into the matrix m.
pfGetMStackTop returns a pointer to the top of the matrix stack.
pfGetMStackDepth returns the current depth of the stack. Initially the
depth is 1.
The following transformations pre- and post- multiply the top of the
matrix stack:
pfPreTransMStack and pfPostTransMStack respectively pre- and post-
multiply the top of the matrix stack by the translation matrix generated
by the coordinates x, y and z. (See pfMakeTransMat).
pfPreRotMStack and pfPostRotMStack respectively pre- and post- multiply
the top of the matrix stack by the rotation by degrees about the axis
defined by (x, y, z). (See pfMakeRotMat). The results are undefined if
the vector (x, y, z) is not normalized.
pfPreScaleMStack and pfPostScaleMStack respectively pre- and post-
multiply the top of the matrix stack by a scaling matrix. (See
pfMakeScaleMat). The matrix scales by x in the X direction, y and the Y
direction and z in the Z direction.
NOTES
pfPreRotMStack and pfPostRotMStack use pfSinCos which is faster than the
libm counterpart, but has less resolution.
pfMatStack is not related to the GL matrix stack.
Page 3
pfMatStack(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
IMPORTANT: The argument order of degrees and axis to the pfPreRotMStack
are not the same as to the corresponding routine pfRotMStack in the IRIS
Performer 1.0 and IRIS Performer 1.1 releases. This change was first
introduced in the IRIS Performer 1.2 release and is present in subsequent
releases of OpenGL Performer.
SEE ALSO
pfDelete, pfMakeRotMat, pfMakeScaleMat, pfMakeTransMat, pfMatrix,
pfSinCos, multmatrix
Page 4
