pfDCS(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfDCS(3pf)NAME
pfNewDCS, pfGetDCSClassType, pfDCSTrans, pfDCSRot, pfDCSCoord,
pfDCSScale, pfDCSScaleXYZ, pfDCSMat, pfGetDCSMat, pfGetDCSMatPtr,
pfDCSMatType, pfGetDCSMatType - Create, modify and get the matrix of a
dynamic coordinate system.
FUNCTION SPECIFICATION
#include <Performer/pf.h>
pfDCS * pfNewDCS(void);
pfType * pfGetDCSClassType(void);
void pfDCSTrans(pfDCS *dcs, float x, float y, float z);
void pfDCSRot(pfDCS *dcs, float h, float p, float r);
void pfDCSCoord(pfDCS *dcs, pfCoord *coord);
void pfDCSScale(pfDCS *dcs, float s);
void pfDCSScaleXYZ(pfDCS *dcs, float x, float y, float z);
void pfDCSMat(pfDCS *dcs, pfMatrix m);
void pfGetDCSMat(pfDCS *dcs, pfMatrix m);
const pfMatrix* pfGetDCSMatPtr(pfDCS *dcs);
void pfDCSMatType(pfDCS *dcs, uint val);
uint pfGetDCSMatType(pfDCS *dcs);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfDCS is derived from the parent class pfSCS,
so each of these member functions of class pfSCS are also directly usable
with objects of class pfDCS. Casting an object of class pfDCS to an
object of class pfSCS is taken care of automatically. This is also true
for casts to objects of ancestor classes of class pfSCS.
void pfGetSCSMat(pfSCS *scs, pfMatrix mat);
const pfMatrix* pfGetSCSMatPtr(pfSCS *scs);
Since the class pfSCS is itself derived from the parent class pfGroup,
objects of class pfDCS can also be used with these functions designed for
objects of class pfGroup.
int pfAddChild(pfGroup *group, pfNode *child);
int pfInsertChild(pfGroup *group, int index, pfNode *child);
Page 1
pfDCS(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfDCS(3pf)
int pfReplaceChild(pfGroup *group, pfNode *old, pfNode *new);
int pfRemoveChild(pfGroup *group, pfNode* child);
int pfSearchChild(pfGroup *group, pfNode* child);
pfNode * pfGetChild(const pfGroup *group, int index);
int pfGetNumChildren(const pfGroup *group);
int pfBufferAddChild(pfGroup *group, pfNode *child);
int pfBufferRemoveChild(pfGroup *group, pfNode *child);
Since the class pfGroup is itself derived from the parent class pfNode,
objects of class pfDCS can also be used with these functions designed for
objects of class pfNode.
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 pfDCS 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);
Page 2
pfDCS(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfDCS(3pf)
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 pfDCS 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
dcs identifies a pfDCS
DESCRIPTION
A pfDCS (Dynamic Coordinate System) is a pfSCS whose matrix can be
modified.
pfNewDCS creates and returns a handle to a pfDCS. Like other pfNodes,
pfDCSes are always allocated from shared memory and can be deleted using
pfDelete.
pfGetDCSClassType returns the pfType* for the class pfDCS. The pfType*
returned by pfGetDCSClassType is the same as the pfType* returned by
invoking pfGetType on any instance of class pfDCS. 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.
The initial transformation is the identity matrix. The transformation of
a pfDCS can be set by specifying a matrix or translation, scale and
rotation. When independently setting translation, rotation, and scale,
the pfDCS matrix is computed as S*R*T, where S is the scale, R is the
rotation, and T is the translation. The order of effect is then scale
Page 3
pfDCS(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfDCS(3pf)
followed by rotation followed by translation.
pfDCS operations are absolute rather than cumulative. For example:
pfDCSTrans(dcs, 2.0f, 0.0f, 0.0f);
pfDCSTrans(dcs, 1.0f, 0.0f, 0.0f);
specifies a translation by 1 unit along the X coordinate axis, not 3
units.
By default a pfDCS uses a bounding sphere which is dynamic, so it is
automatically updated when the pfDCS transformation is changed or when
children are added, deleted or changed. This behavior may be changed
using pfNodeBSphere. The bound for a pfDCS encompasses all B(i)*S*R*T,
where B(i) is the bound for the child 'i' and S*R*T represents the scale,
rotation, and translation transformation of the pfDCS.
pfDCSTrans sets the translation part of the pfDCS to (x, y, z). The
rotational portion of the matrix is unchanged.
pfDCSScale sets the scale portion of the pfDCS to scale uniformly by a
scale factor s. This supersedes the previous scale leaving the rotation
and translation unchanged. pfDCSScaleXYZ specifies a non-uniform scale of
x, y, z.
pfDCSRot sets the rotation portion of the matrix:
h Specifies heading, the rotation about the Z axis.
p Specifies pitch, the rotation about the X axis.
r Specifies roll, rotation about the Y axis.
The matrix created is R*P*H, where R is the roll transform, P is the
pitch transform and H is the heading transform. The new (h,p,r)
combination replaces the previous specification, leaving the scale and
translation unchanged. The convention is natural for a model in which +Y
is "forward," +Z is "up" and +X is "right". To maintain 1/1000 degree
resolution in the single precision arithmetic used internally for sine
and cosine calculations, the angles h, p, r should be in the range of
-7500 to +7500 degrees.
pfDCSCoord sets the rotation and translation portion of the pfDCS
according to coord. This is equivalent to:
pfDCSRot(dcs, coord->hpr[0], coord->hpr[1], coord->hpr[2]);
pfDCSTrans(dcs, coord->xyz[0], coord->xyz[1], coord->xyz[2]);
pfDCSMat sets the transformation matrix for dcs to m.
Page 4
pfDCS(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfDCS(3pf)
Normally pfDCSMat is used as a replacement for the above routines which
individually set the scale, rotation and translational components. The
mechanisms can be combined but only if the supplied matrix can be
represented as scale followed by a rotation followed by a translation
(e.g. a point pt is transformed by the matrix as: pt' = pt*S*R*T), which
implies that no shearing or non-uniform scaling is present.
pfDCSMatType allows the specification of information about the type of
transformation the matrix represents. This information allows Performer
to speed up some operations. The matrix type is specified as the OR of
PFMAT_TRANS:
matrix may include a translational component in the 4th row.
PFMAT_ROT
matrix may include a rotational component in the left upper 3X3
submatrix.
PFMAT_SCALE
matrix may include a uniform scale in the left upper 3X3
submatrix.
PFMAT_NONORTHO
matrix may include a non-uniform scale in the left upper 3X3
submatrix.
PFMAT_PROJ
matrix may include projections.
PFMAT_HOM_SCALE
matrix may have mat[4][4] != 1.
PFMAT_MIRROR
matrix may include mirroring transformation that switches
between right handed and left handed coordinate systems.
pfGetDCSMatType returns the matrix type as
set by pfDCSMatType. If no matrix type is set the default is ~0,
corresponding to a general matrix.
The transformation of a pfDCS affects all its children. As the
hierarchy is traversed from top to bottom, each new matrix is pre-
multiplied to create the new transformation. For example, if DCSb
is below DCSa in the scene graph, any geometry G below DCSa is
transformed as G*DCSb*DCSa.
pfFlatten cannot flatten pfDCSes since they may change at run-time.
In this case pfFlatten will compute a pfSCS representing the
accumulated static transformation that the pfDCS inherits and insert
it above the pfDCS. Static transformations below a pfDCS are
flattened as usual. See pfFlatten for more details.
Page 5
pfDCS(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfDCS(3pf)
The presence of transformations in the scene graph impacts the
performance of intersection, culling and drawing. pfGeoSet culling
(see PFCULL_GSET in pfChanTravMode) is disabled in portions of the
scene graph below pfDCSes.
Both pre and post CULL and DRAW callbacks attached to a pfDCS (-
pfNodeTravFuncs) will be affected by the transformation represented
by the pfDCS, i.e. - the pfDCS matrix will already have been applied
to the matrix stack before the pre callback is called and will be
popped only after the post callback is called.
pfGetDCSMat copies the transformation matrix value from dcs into the
matrix m. For faster matrix access, pfGetDCSMatPtr can be used to
get a const pointer to dcs's matrix.
SEE ALSO
pfCoord, pfGroup, pfChanTravMode, pfLookupNode, pfFlatten, pfMatrix,
pfNode, pfSCS, pfScene, pfTraverser, pfDelete
Page 6
