pfMatrix(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfMatrix(3pf)NAMEpfMatrix - Set and operate on 4x4 matrices.
FUNCTION SPECIFICATION
#include <Performer/pr/pfLinMath.h>
void* pfMatrix::operator new(size_t);
void* pfMatrix::operator new(size_t, void *arena);
pfMatrix::pfMatrix();
pfMatrix::pfMatrix(float a00, float a01, float a02,
float a03, float a10, float a11, float a12, float a13,
float a20, float a21, float a22, float a23, float a30,
float a31, float a32, float a33);
void pfMatrix::makeIdent(void);
void pfMatrix::makeTrans(float x, float y, float z);
void pfMatrix::makeScale(float x, float y, float z);
void pfMatrix::makeRot(float degrees, float x, float y,
float z);
void pfMatrix::makeQuat(const pfQuat& q);
void pfMatrix::makeEuler(float h, float p, float r);
void pfMatrix::makeVecRotVec(const pfVec3& v1,
const pfVec3& v2);
void pfMatrix::makeCoord(const pfCoord *c);
void pfMatrix::getOrthoQuat(pfQuat& dst);
void pfMatrix::getOrthoCoord(pfCoord* dst);
int pfMatrix::getMatType(void);
void pfMatrix::setRow(int row, float x, float y, float z,
float w);
void pfMatrix::getRow(int row, float *x, float *y, float *z,
float *w);
void pfMatrix::setCol(int col, float x, float y, float z,
float w);
Page 1
pfMatrix(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfMatrix(3pf)
void pfMatrix::getCol(int col, float *x, float *y, float *z,
float *w);
void pfMatrix::setRow(int row, const pfVec3& v);
void pfMatrix::getRow(int row, pfVec3& dst);
void pfMatrix::setCol(int col, const pfVec3& v);
void pfMatrix::getCol(int col, pfVec3& dst);
void pfMatrix::set(const float *m);
void pfMatrix::copy(const pfMatrix& m);
void pfMatrix::add(const pfMatrix& m1, const pfMatrix& m2);
void pfMatrix::sub(const pfMatrix& m1, const pfMatrix& m2);
void pfMatrix::scale(float s, pfMatrix& m);
void pfMatrix::transpose(pfMatrix& m);
void pfMatrix::mult(const pfMatrix& m1, const pfMatrix& m2);
void pfMatrix::preMult(const pfMatrix& m);
void pfMatrix::postMult(const pfMatrix& m);
void pfMatrix::preTrans(float x, float y, float z,
pfMatrix& m);
void pfMatrix::postTrans(const pfMatrix& m, float x, float y,
float z);
void pfMatrix::preRot(float degrees, float x, float y, float z,
pfMatrix& m);
void pfMatrix::postRot(const pfMatrix& mat, float degrees,
float x, float y, float z, );
void pfMatrix::preScale(float x, float y, float z,
pfMatrix& m);
void pfMatrix::postScale(const pfMatrix& m, float x, float y,
float z);
int pfMatrix::invertFull(const pfMatrix& m);
void pfMatrix::invertAff(const pfMatrix& m);
Page 2
pfMatrix(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfMatrix(3pf)
void pfMatrix::invertOrtho(const pfMatrix& m);
void pfMatrix::invertOrthoN(const pfMatrix& m);
int pfMatrix::invertIdent(const pfMatrix& m);
void pfMatrix::equal(const pfMatrix& m2);
void pfMatrix::almostEqual(const pfMatrix& m2, float tol);
float& pfMatrix::operator [](int i);
const float& pfMatrix::operator [](int i);
int pfMatrix::operator ==(const pfMatrix& v);
pfMatrix pfMatrix::operator +(const pfMatrix& v);
pfMatrix pfMatrix::operator -(const pfMatrix& v);
pfMatrix& pfMatrix::operator +=(const pfMatrix& m);
pfMatrix& pfMatrix::operator -=(const pfMatrix& m);
pfMatrix& pfMatrix::operator =(const pfMatrix& v);
pfMatrix& pfMatrix::operator *=(const pfMatrix& m);
pfMatrix pfMatrix::operator *=(const pfMatrix& m);
pfMatrix pfMatrix::operator *(const pfMatrix& v, float d);
pfMatrix pfMatrix::operator *(float d, const pfMatrix& v);
pfMatrix pfMatrix::operator /(const pfMatrix& v, float d);
struct pfCoord
{
pfVec3 xyz;
pfVec3 hpr;
};
struct pfMatrix
{
float mat[4][4];
};
Page 3
pfMatrix(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfMatrix(3pf)DESCRIPTION
Routines for pfMatrix, a 4X4 matrix.
Most accesses to pfMatrix go through pfMatrix::operator[], but pfMatrix
is a public struct whose data member mat is directly accessible, e.g.
for passing to a routine expecting a float* such as glLoadMatrixf. The
default constructor pfMatrix() is empty and does not initialize the
values in the matrix. An initializing constructor pfMatrix(float, ...
float) accepts the initial values in row major order, i.e. mat[0][0],
mat[0][1], mat[0][2], mat[0][3],
new(arena) allocates a pfMatrix from the specified memory arena, or from
the heap if arena is NULL. new allocates a pfMatrix from the default
memory arena (pfGetSharedArena). pfMatrices can also be created
automatically on the stack or statically. pfMatrices allocated with new
can be deleted with delete or pfDelete.
pfMatrix::makeIdent sets the pfMatrix to the identity matrix.
PFMAKE_IDENT_MAT is an equivalent macro.
The following routines create transformation matrices based on
multiplying a row vector by a matrix on the right, i.e. the vector v
transformed by m is v * m. Many actions will go considerably faster if
the last column is (0,0,0,1).
pfMatrix::makeTrans sets the pfMatrix to the matrix which translates by
(x, y, z). Equivalent macro: PFMAKE_TRANS_MAT.
pfMatrix::makeScale sets the pfMatrix to the matrix which scales by x in
the X direction, by y in the Y direction and by z in the Z direction.
Equivalent macro: PFMAKE_SCALE_MAT
pfMatrix::makeRot sets the pfMatrix to the matrix which rotates by
degrees about the axis denoted by the unit vector (x, y, z). If (x, y,
z) is not normalized, results are undefined.
pfMatrix::makeQuat builds a rotation matrix that expresses the rotation
defined by the quaternion q.
pfMatrix::makeEuler sets the pfMatrix to a rotation matrix composed of
the Euler angles h, p, r: h specifies heading, the rotation about the Z
axis; p specifies pitch, the rotation about the X axis; and, r specifies
roll, rotation about the Y axis. The matrix created is the pfMatrix =
R*P*H, where R is the roll transform, P is the pitch transform and H is
the heading transform. All rotations follow the right hand rule. The
convention is natural for a model in which +Y is "forward," +Z is "up"
and +X is "right". This routine uses pfSinCos which is faster than the
libm counterpart, but has less resolution (see pfSinCos).
pfMatrix::makeVecRotVec sets the pfMatrix to the rotation matrix which
rotates the vector v1 onto v2, i.e. v2 = v1 * dst. v2 must be
normalized. The rotation axis is always chosen to be perpendicular to
Page 4
pfMatrix(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfMatrix(3pf)
both v0 and v1 so that the rotation angle is as small as possible. Note
that the result is ambiguous only when v0 == -v1; in this case the
rotation axis is chosen to be an arbitrary vector perpendicular to v0 and
v1.
pfMatrix::makeCoord sets the pfMatrix to the matrix which rotates by the
Euler transform specified by c->hpr and translates by c->xyz, i.e. dst =
R*P*H*T, where R is the roll transform, P is the pitch transform and H is
the heading transform, and T is the translation transform.
pfMatrix::getOrthoQuat constructs a quaternion pfMatrix equivalent to the
rotation expressed by the orthonormal matrix m.
pfMatrix::getOrthoCoord returns in the pfMatrix the translation and
rotation of the orthonormal matrix, m. The returned pitch ranges from
-90 to +90 degrees. Roll and heading range from -180 to +180.
pfMatrix::getMatType computes and returns the type of a matrix. This
information can be useful when using a matrix repeatedly, e.g. to
transform many objects, but is somewhat time consuming to compute. The
returned matrix type is a bitwise OR of any of the following constants:
PFMAT_TRANS:
matrix includes a translational component in the 4th row.
PFMAT_ROT:
matrix includes a rotational component in the left upper 3X3
submatrix.
PFMAT_SCALE:
matrix includes a uniform scale in the left upper 3X3
submatrix.
PFMAT_NONORTHO:
matrix includes a non-uniform scale in the left upper 3X3
submatrix.
PFMAT_PROJ:
matrix includes projections.
PFMAT_HOM_SCALE:
mat[4][4] != 1.
PFMAT_MIRROR:
matrix includes mirroring transformation that switches between
right handed and left handed coordinate systems.
pfMatrix::setRow. mat[row][0] = x, mat[row][1] = y, mat[row][2] = z,
mat[row][3] = w. Use the arguments to set row row of the pfMatrix. row
must be 0, 1, 2, or 3. Equivalent macro: PFSET_MAT_ROW.
pfMatrix::getRow. *x = mat[row][0], *y = mat[row][1], *z = mat[row][2],
Page 5
pfMatrix(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfMatrix(3pf)
*w = mat[row][3]. Get the arguments to row row of the pfMatrix. row
must be 0, 1, 2, or 3. Equivalent macro: PFGET_MAT_ROW.
pfMatrix::setCol. mat[0][col] = x, mat[1][col] = y, mat[2][col] = z,
mat[3][col] = w. Use the arguments to set col col of the pfMatrix. col
must be 0, 1, 2, or 3. Equivalent macro: PFSET_MAT_COL.
pfMatrix::getCol. *x = mat[0][col], *y = mat[1][col], *z = mat[2][col],
*w = mat[3][col]. Get the arguments to col col of the pfMatrix. col
must be 0, 1, 2, or 3. Equivalent macro: PFGET_MAT_COL.
pfMatrix::setRow. mat[row][i] = v[i], i = 0, 1, 2. Set row row of the
pfMatrix to the vector v. row must be 0, 1, 2, or 3. Equivalent macro:
PFSET_MAT_ROWVEC3.
pfMatrix::getRow. mat[i] = m[row][i], i = 0, 1, 2. Return row row of m
and in the pfMatrix. row must be 0, 1, 2, or 3. Equivalent macro:
PFGET_MAT_ROWVEC3.
pfMatrix::setCol. mat[i][col] = v[i], i = 0, 1, 2. Set column col of
the pfMatrix to the vector v. col must be 0, 1, 2, or 3. Equivalent
macro: PFSET_MAT_COLVEC3.
pfMatrix::getCol. mat[i] = m[i][col], i = 0, 1, 2. Return column col of
m in the pfMatrix. col must be 0, 1, 2, or 3. Equivalent macro:
PFGET_MAT_COLVEC3.
pfMatrix::set. mat[i][j] = m[i*4+j], 0 <= i,j <= 3.
pfMatrix::copy: mat = m. Copies m into the pfMatrix. Equivalent macro:
PFCOPY_MAT
pfMatrix::preTrans: mat = T(x,y,z) * m, where T(x,y,z) is the matrix
which translates by (x,y,z).
pfMatrix::postTrans: mat = m * T(x,y,z), where T(x,y,z) is the matrix
which translates by (x,y,z).
pfMatrix::preRot: mat = R(degrees, x,y,z) * m, where R(degrees,x,y,z) is
the matrix which rotates by degrees about the axis (x,y,z).
pfMatrix::postRot: mat = m * R(degrees, x,y,z), where R(degrees,x,y,z) is
the matrix which rotates by degrees about the axis (x,y,z).
pfMatrix::preScale: mat = S(x,y,z) * m, where S(x,y,z) is the matrix
which scales by (x,y,z).
pfMatrix::postScale: mat = m * S(x,y,z), where S(x,y,z) is the matrix
which scales by (x,y,z).
pfMatrix::add: mat = m1 + m2. Sets the pfMatrix to the sum of m1 and m2.
Page 6
pfMatrix(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfMatrix(3pf)
pfMatrix::sub: mat = m1 - m2. Sets the pfMatrix to the difference of m1
and m2.
pfMatrix::scale: mat = s * m. Sets the pfMatrix to the product of the
scalar s and the matrix m. This multiplies the full 4X4 matrix and is
not a 3D geometric scale.
pfMatrix::transpose: mat = Transpose(m). Sets the pfMatrix to the
transpose of m.
pfMatrix::mult: mat = m1 * m2. Sets the pfMatrix to the product of m1
and m2.
pfMatrix::postMult: mat = mat *m. Postmultiplies the pfMatrix by m.
pfMatrix::preMult: mat = m * mat. Premultiplies the pfMatrix by m.
pfMatrix::invertFull, pfMatrix::invertAff, pfMatrix::invertOrtho,
pfMatrix::invertOrthoN, and pfMatrix::invertIdent, set the pfMatrix to
the inverse of m for general, affine, orthogonal, orthonormal and
identity matrices respectively. They are listed here in order of
decreasing generality and increasing speed. If the matrix m is not of
the type specified in the routine name, the result is undefined.
pfMatrix::invertFull returns FALSE if the matrix is singular and TRUE
otherwise.
pfMatrix::equal(m2) = (pfMatrix.mat == m2). Tests for strict component-
by-element equality of the pfMatrix and m2 and returns FALSE or TRUE.
Macro equivalent: PFEQUAL_MAT.
pfMatrix::almostEqual(m2, tol). Tests for approximate element-by-element
equality of the pfMatrix and m2. It returns FALSE or TRUE depending on
whether the absolute value of the difference between each pair of
elements is less than the tolerance tol. Macro equivalent:
PFALMOST_EQUAL_MAT.
float& operator [](int) const float& operator [](int) Bracket operators
to allow indexing into the 2D array, e.g. m[3][2].
int operator ==(const pfMatrix&) Equality comparison operator.
pfMatrix operator +(const pfMatrix&) pfMatrix operator -(const pfMatrix&)
Component-wise binary matrix addition and subtraction operators.
pfMatrix& operator +=(const pfMatrix&); pfMatrix& operator -=(const
pfMatrix&); Component-wise matrix addition and subtraction operators.
pfMatrix& operator =(const pfMatrix&) Set the matrix from another matrix.
pfMatrix& operator *=(const pfMatrix&) pfMatrix operator *=(const
pfMatrix&) Performs right multiplication with anther matrix.
Page 7
pfMatrix(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfMatrix(3pf)pfMatrix operator *(const pfMatrix&, float) pfMatrix operator *(float,
const pfMatrix&) pfMatrix operator /(const pfMatrix&, float) Component-
wise binary scalar multiplication and division operators.
Routines can accept the same matrix as source, destination, or as a
repeated operand.
NOTES
Some of these routines use pfSinCos and pfSqrt, which are faster but have
less resolution than the libm counterparts. (See pfSinCos) When using
overloaded operators in C++, assignment operators, e.g. "+=", are
somewhat more efficient than the corresponding binary operators, e.g.
"+", because the latter construct a temporary intermediate object. Use
assignment operators or macros for binary operations where optimal speed
is important.
C++ does not support array deletion (i.e. delete[]) for arrays of objects
allocated new operators that take additional arguments. Hence, the array
deletion operator delete[] should not be used on arrays of objects
created with new(arena) pfMatrix[n].
SEE ALSO
pfSinCos, pfSqrt, pfVec3, pfVec4
Page 8
