pfMatrix4d(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
NAMEpfMatrix4d - Set and operate on 4x4 double-precision matrices.
FUNCTION SPECIFICATION
#include <Performer/pr/pfLinMath.h>
void* pfMatrix4d::operator new(size_t);
void* pfMatrix4d::operator new(size_t, void *arena);
pfMatrix4d::pfMatrix4d();
pfMatrix4d::pfMatrix4d(double a00, double a01,
double a02, double a03, double a10, double a11,
double a12, double a13, double a20, double a21,
double a22, double a23, double a30, double a31,
double a32, double a33);
void pfMatrix4d::makeIdent(void);
void pfMatrix4d::makeTrans(double x, double y, double z);
void pfMatrix4d::makeScale(double x, double y, double z);
void pfMatrix4d::makeRot(double degrees, double x, double y,
double z);
void pfMatrix4d::makeQuat(const pfQuatd& q);
void pfMatrix4d::makeEuler(double h, double p, double r);
void pfMatrix4d::makeVecRotVec(const pfVec3d& v1,
const pfVec3d& v2);
void pfMatrix4d::makeCoordd(const pfCoordd *c);
void pfMatrix4d::getOrthoQuatd(pfQuatd& dst);
void pfMatrix4d::getOrthoCoordd(pfCoordd* dst);
int pfMatrix4d::getMatType(void);
void pfMatrix4d::setRow(int row, double x, double y, double z,
double w);
void pfMatrix4d::getRow(int row, double *x, double *y,
double *z, double *w);
void pfMatrix4d::setCol(int col, double x, double y, double z,
double w);
Page 1
pfMatrix4d(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
void pfMatrix4d::getCol(int col, double *x, double *y,
double *z, double *w);
void pfMatrix4d::setRow(int row, const pfVec3d& v);
void pfMatrix4d::getRow(int row, pfVec3d& dst);
void pfMatrix4d::setCol(int col, const pfVec3d& v);
void pfMatrix4d::getCol(int col, pfVec3d& dst);
void pfMatrix4d::set(const double *m);
void pfMatrix4d::copy(const pfMatrix4d& m);
void pfMatrix4d::add(const pfMatrix4d& m1,
const pfMatrix4d& m2);
void pfMatrix4d::sub(const pfMatrix4d& m1,
const pfMatrix4d& m2);
void pfMatrix4d::scale(double s, pfMatrix4d& m);
void pfMatrix4d::transpose(pfMatrix4d& m);
void pfMatrix4d::mult(const pfMatrix4d& m1,
const pfMatrix4d& m2);
void pfMatrix4d::preMult(const pfMatrix4d& m);
void pfMatrix4d::postMult(const pfMatrix4d& m);
void pfMatrix4d::preTrans(double x, double y, double z,
pfMatrix4d& m);
void pfMatrix4d::postTrans(const pfMatrix4d& m, double x,
double y, double z);
void pfMatrix4d::preRot(double degrees, double x, double y,
double z, pfMatrix4d& m);
void pfMatrix4d::postRot(const pfMatrix4d& mat,
double degrees, double x, double y, double z, );
void pfMatrix4d::preScale(double x, double y, double z,
pfMatrix4d& m);
void pfMatrix4d::postScale(const pfMatrix4d& m, double x,
double y, double z);
Page 2
pfMatrix4d(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
int pfMatrix4d::invertFull(const pfMatrix4d& m);
void pfMatrix4d::invertAff(const pfMatrix4d& m);
void pfMatrix4d::invertOrtho(const pfMatrix4d& m);
void pfMatrix4d::invertOrthoN(const pfMatrix4d& m);
int pfMatrix4d::invertIdent(const pfMatrix4d& m);
void pfMatrix4d::equal(const pfMatrix4d& m2);
void pfMatrix4d::almostEqual(const pfMatrix4d& m2,
double tol);
double& pfMatrix4d::operator [](int i);
const double& pfMatrix4d::operator [](int i);
int pfMatrix4d::operator ==(const pfMatrix4d& v);
pfMatrix4d pfMatrix4d::operator +(const pfMatrix4d& v);
pfMatrix4d pfMatrix4d::operator -(const pfMatrix4d& v);
pfMatrix4d& pfMatrix4d::operator +=(const pfMatrix4d& m);
pfMatrix4d& pfMatrix4d::operator -=(const pfMatrix4d& m);
pfMatrix4d& pfMatrix4d::operator =(const pfMatrix4d& v);
pfMatrix4d& pfMatrix4d::operator *=(const pfMatrix4d& m);
pfMatrix4d pfMatrix4d::operator *=(const pfMatrix4d& m);
pfMatrix4d pfMatrix4d::operator *(const pfMatrix4d& v, double d);
pfMatrix4d pfMatrix4d::operator *(double d, const pfMatrix4d& v);
pfMatrix4d pfMatrix4d::operator /(const pfMatrix4d& v, double d);
struct pfCoord
{
pfVec3 xyz;
pfVec3 hpr;
};
struct pfCoordd
{
pfVec3d xyz;
pfVec3d hpr;
Page 3
pfMatrix4d(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
};
struct pfMatrix4d
{
double mat[4][4];
};
DESCRIPTION
Routines for pfMatrix4d, a 4X4 double-precision matrix.
Most accesses to pfMatrix4d go through pfMatrix4d::operator[], but
pfMatrix4d is a public struct whose data member mat is directly
accessible, e.g. for passing to a routine expecting a double* such as
glLoadMatrixf. The default constructor pfMatrix4d() is empty and does
not initialize the values in the matrix. An initializing constructor
pfMatrix4d(double, ... double) 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 pfMatrix4d from the specified memory arena, or
from the heap if arena is NULL. new allocates a pfMatrix4d 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.
pfMatrix4d::makeIdent sets the pfMatrix4d 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).
pfMatrix4d::makeTrans sets the pfMatrix4d to the matrix which translates
by (x, y, z). Equivalent macro: PFMAKE_TRANS_MAT.
pfMatrix4d::makeScale sets the pfMatrix4d 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
pfMatrix4d::makeRot sets the pfMatrix4d 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.
pfMatrix4d::makeQuat builds a rotation matrix that expresses the rotation
defined by the quaternion q.
pfMatrix4d::makeEuler sets the pfMatrix4d 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
Page 4
pfMatrix4d(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
pfMatrix4d = 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).
pfMatrix4d::makeVecRotVec sets the pfMatrix4d 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
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.
pfMatrix4d::makeCoordd sets the pfMatrix4d 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.
pfMatrix4d::getOrthoQuat constructs a quaternion pfMatrix4d equivalent to
the rotation expressed by the orthonormal matrix m.
pfMatrix4d::getOrthoCoordd returns in the pfMatrix4d 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.
pfDoubleDCS::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 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.
Page 5
pfMatrix4d(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
PFMAT_HOM_SCALE:
mat[4][4] != 1.
PFMAT_MIRROR:
matrix includes mirroring transformation that switches between
right handed and left handed coordinate systems.
pfMatrix4d::getMatType computes the type of matrix. This information can
be useful if a matrix is to be used repeatedly, e.g. to transform many
objects, but is somewhat time consuming to compute.
pfMatrix4d::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 pfMatrix4d.
row must be 0, 1, 2, or 3. Equivalent macro: PFSET_MAT_ROW.
pfMatrix4d::getRow. *x = mat[row][0], *y = mat[row][1], *z =
mat[row][2], *w = mat[row][3]. Get the arguments to row row of the
pfMatrix4d. row must be 0, 1, 2, or 3. Equivalent macro: PFGET_MAT_ROW.
pfMatrix4d::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 pfMatrix4d.
col must be 0, 1, 2, or 3. Equivalent macro: PFSET_MAT_COL.
pfMatrix4d::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
pfMatrix4d. col must be 0, 1, 2, or 3. Equivalent macro: PFGET_MAT_COL.
pfMatrix4d::setRow. mat[row][i] = v[i], i = 0, 1, 2. Set row row of the
pfMatrix4d to the vector v. row must be 0, 1, 2, or 3. Equivalent
macro: PFSET_MAT_ROWVEC3.
pfMatrix4d::getRow. mat[i] = m[row][i], i = 0, 1, 2. Return row row of
m and in the pfMatrix4d. row must be 0, 1, 2, or 3. Equivalent macro:
PFGET_MAT_ROWVEC3.
pfMatrix4d::setCol. mat[i][col] = v[i], i = 0, 1, 2. Set column col of
the pfMatrix4d to the vector v. col must be 0, 1, 2, or 3. Equivalent
macro: PFSET_MAT_COLVEC3.
pfMatrix4d::getCol. mat[i] = m[i][col], i = 0, 1, 2. Return column col
of m in the pfMatrix4d. col must be 0, 1, 2, or 3. Equivalent macro:
PFGET_MAT_COLVEC3.
pfMatrix4d::set. mat[i][j] = m[i*4+j], 0 <= i,j <= 3.
pfMatrix4d::copy: mat = m. Copies m into the pfMatrix4d. Equivalent
macro: PFCOPY_MAT
pfMatrix4d::preTrans: mat = T(x,y,z) * m, where T(x,y,z) is the matrix
which translates by (x,y,z).
pfMatrix4d::postTrans: mat = m * T(x,y,z), where T(x,y,z) is the matrix
Page 6
pfMatrix4d(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
which translates by (x,y,z).
pfMatrix4d::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).
pfMatrix4d::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).
pfMatrix4d::preScale: mat = S(x,y,z) * m, where S(x,y,z) is the matrix
which scales by (x,y,z).
pfMatrix4d::postScale: mat = m * S(x,y,z), where S(x,y,z) is the matrix
which scales by (x,y,z).
pfMatrix4d::add: mat = m1 + m2. Sets the pfMatrix4d to the sum of m1 and
m2.
pfMatrix4d::sub: mat = m1 - m2. Sets the pfMatrix4d to the difference of
m1 and m2.
pfMatrix4d::scale: mat = s * m. Sets the pfMatrix4d to the product of
the scalar s and the matrix m. This multiplies the full 4X4 matrix and
is not a 3D geometric scale.
pfMatrix4d::transpose: mat = Transpose(m). Sets the pfMatrix4d to the
transpose of m.
pfMatrix4d::mult: mat = m1 * m2. Sets the pfMatrix4d to the product of
m1 and m2.
pfMatrix4d::postMult: mat = mat *m. Postmultiplies the pfMatrix4d by m.
pfMatrix4d::preMult: mat = m * mat. Premultiplies the pfMatrix4d by m.
pfMatrix4d::invertFull, pfMatrix4d::invertAff, pfMatrix4d::invertOrtho,
pfMatrix4d::invertOrthoN, and pfMatrix4d::invertIdent, set the pfMatrix4d
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.
pfMatrix4d::invertFull returns FALSE if the matrix is singular and TRUE
otherwise.
pfMatrix4d::equal(m2) = (pfMatrix4d.mat == m2). Tests for strict
component-by-element equality of the pfMatrix4d and m2 and returns FALSE
or TRUE. Macro equivalent: PFEQUAL_MAT.
pfMatrix4d::almostEqual(m2, tol). Tests for approximate element-by-
element equality of the pfMatrix4d 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.
Page 7
pfMatrix4d(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
double& operator [](int) const double& operator [](int) Bracket operators
to allow indexing into the 2D array, e.g. m[3][2].
int operator ==(const pfMatrix4d&) Equality comparison operator.
pfMatrix4d operator +(const pfMatrix4d&) pfMatrix4d operator -(const
pfMatrix4d&) Component-wise binary matrix addition and subtraction
operators.
pfMatrix4d& operator +=(const pfMatrix4d&); pfMatrix4d& operator -=(const
pfMatrix4d&); Component-wise matrix addition and subtraction operators.
pfMatrix4d& operator =(const pfMatrix4d&) Set the matrix from another
matrix.
pfMatrix4d& operator *=(const pfMatrix4d&) pfMatrix4d operator *=(const
pfMatrix4d&) Performs right multiplication with anther matrix.
pfMatrix4d operator *(const pfMatrix4d&, double) pfMatrix4d operator
*(double, const pfMatrix4d&) pfMatrix4d operator /(const pfMatrix4d&,
double) 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) pfMatrix4d[n].
SEE ALSO
pfSinCos, pfSqrt, pfVec3, pfVec3d, pfVec4
Page 8
