pfDCS(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages pfDCS(3pf)NAMEpfDCS - Create, modify and get the matrix of a dynamic coordinate system.
FUNCTION SPECIFICATION
#include <Performer/pf/pfDCS.h>
pfDCS::pfDCS();
static pfType * pfDCS::getClassType(void);
void pfDCS::setTrans(float x, float y, float z);
void pfDCS::setRot(float h, float p, float r);
void pfDCS::setCoord(pfCoord *coord);
void pfDCS::setScale(float s);
void pfDCS::setScale(float x, float y, float z);
void pfDCS::setMat(pfMatrix &m);
void pfDCS::getMat(pfMatrix &m);
const pfMatrix* pfDCS::getMatPtr(void);
void pfDCS::setMatType(uint val);
uint pfDCS::getMatType();
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. This is also true for ancestor classes of
class pfSCS.
void pfSCS::getMat(pfMatrix &mat);
const pfMatrix* pfSCS::getMatPtr(void);
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 pfGroup::addChild(pfNode *child);
int pfGroup::insertChild(int index, pfNode *child);
int pfGroup::replaceChild(pfNode *old, pfNode *new);
int pfGroup::removeChild(pfNode* child);
int pfGroup::searchChild(pfNode* child);
pfNode * pfGroup::getChild(int index);
Page 1
pfDCS(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages pfDCS(3pf)
int pfGroup::getNumChildren(void);
int pfGroup::bufferAddChild(pfNode *child);
int pfGroup::bufferRemoveChild(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 * pfNode::getParent(int i);
int pfNode::getNumParents(void);
void pfNode::setBound(pfSphere *bsph, int mode);
int pfNode::getBound(pfSphere *bsph);
pfNode* pfNode::clone(int mode);
pfNode* pfNode::bufferClone(int mode, pfBuffer *buf);
int pfNode::flatten(int mode);
int pfNode::setName(const char *name);
const char * pfNode::getName(void);
pfNode* pfNode::find(const char *pathName, pfType *type);
pfNode* pfNode::lookup(const char *name, pfType* type);
int pfNode::isect(pfSegSet *segSet, pfHit **hits[]);
void pfNode::setTravMask(int which, uint mask, int setMode,
int bitOp);
uint pfNode::getTravMask(int which);
void pfNode::setTravFuncs(int which, pfNodeTravFuncType pre,
pfNodeTravFuncType post);
void pfNode::getTravFuncs(int which, pfNodeTravFuncType *pre,
pfNodeTravFuncType *post);
void pfNode::setTravData(int which, void *data);
void * pfNode::getTravData(int which);
void pfNode::setTravMode(int which, int mode, int val);
int pfNode::getTravMode(int which, int mode) const;
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* pfObject::operator new(size_t);
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 pfDCS can also be used with these functions
designed for objects of class pfMemory.
Page 2
pfDCS(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages pfDCS(3pf)
void* pfMemory::getData(const void *ptr);
pfType * pfMemory::getType();
int pfMemory::isOfType(pfType *type);
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 pfDCS (Dynamic Coordinate System) is a pfSCS whose matrix can be
modified.
new pfDCS creates and returns a handle to a pfDCS. Like other pfNodes,
pfDCSes are always allocated from shared memory and cannot be created
statically, on the stack or in arrays. pfDCSes should be deleted using
pfDelete rather than the delete operator.
pfDCS::getClassType returns the pfType* for the class pfDCS. The pfType*
returned by pfDCS::getClassType is the same as the pfType* returned by
invoking the virtual function getType 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 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.
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
followed by rotation followed by translation.
pfDCS operations are absolute rather than cumulative. For example:
dcs->setTrans(2.0f, 0.0f, 0.0f);
dcs->setTrans(1.0f, 0.0f, 0.0f);
Page 3
pfDCS(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages pfDCS(3pf)
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 pfNode::setBound. 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.
pfDCS::setTrans sets the translation part of the pfDCS to (x, y, z). The
rotational portion of the matrix is unchanged.
pfDCS::setScale 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. pfDCS::setScale specifies a non-
uniform scale of x, y, z.
pfDCS::setRot 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.
pfDCS::setCoord sets the rotation and translation portion of the pfDCS
according to coord. This is equivalent to:
dcs->setRot(coord->hpr[0], coord->hpr[1], coord->hpr[2]);
dcs->setTrans(coord->xyz[0], coord->xyz[1], coord->xyz[2]);
pfDCS::setMat sets the transformation matrix for the pfDCS to m.
Normally pfDCS::setMat 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.
Page 4
pfDCS(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages pfDCS(3pf)
pfDCS::setMatType 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.
pfDCS::getMatType returns the matrix type as
set by pfDCS::setMatType. 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.
pfNode::flatten cannot flatten pfDCSes since they may change at
run-time. In this case pfNode::flatten 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 pfNode::flatten for more
details.
The presence of transformations in the scene graph impacts the
performance of intersection, culling and drawing. pfGeoSet culling
(see PFCULL_GSET in pfChannel::setTravMode) is disabled in portions
of the scene graph below pfDCSes.
Page 5
pfDCS(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages pfDCS(3pf)
Both pre and post CULL and DRAW callbacks attached to a pfDCS (-
pfNode::setTravFuncs) 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.
pfDCS::getMat copies the transformation matrix value from the pfDCS
into the matrix m. For faster matrix access, pfDCS::getMatPtr can
be used to get a const pointer to the pfDCS's matrix.
SEE ALSO
pfCoord, pfGroup, pfChannel, pfLookupNode, pfFlatten, pfMatrix, pfNode,
pfSCS, pfScene, pfTraverser, pfDelete
Page 6
