pfMatrix - Set and operate on 4x4 matrices.
void* pfMatrix::operator new(size_t);
void* pfMatrix::operator new(size_t, void *arena);
void pfMatrix::makeIdent(void);
void pfMatrix::makeTrans(float x, float y, float z);
void pfMatrix::makeScale(float x, float y, float z);
void pfMatrix::makeQuat(const pfQuat& q);
void pfMatrix::makeEuler(float h, float p, float r);
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, 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);
int pfMatrix::invertFull(const pfMatrix& m);
void pfMatrix::invertAff(const pfMatrix& m);
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];
};
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
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::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
pfMatrix::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.
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], *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::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::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::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].
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&) pfMatrix operator *=(const pfMatrix&) Performs right multiplication with anther matrix.
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.
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].
pfSinCos, pfSqrt, pfVec3, pfVec4
pfMakeIdentMat, pfMakeTransMat, pfMakeScaleMat, pfMakeRotMat, pfMakeQuatMat, pfMakeEulerMat, pfMakeVecRotVecMat, pfMakeCoordMat, pfGetMatType, pfGetOrthoMatQuat, pfGetOrthoMatCoord, pfSetMat, pfSetMatRowVec3, pfGetMatRowVec3, pfSetMatColVec3, pfGetMatColVec3, pfSetMatRow, pfGetMatRow, pfSetMatCol, pfGetMatCol, pfCopyMat, pfAddMat, pfSubMat, pfScaleMat, pfTransposeMat, pfMultMat, pfPreMultMat, pfPostMultMat, pfPreTransMat, pfPostTransMat, pfPreRotMat, pfPostRotMat, pfPreScaleMat, pfPostScaleMat, pfInvertFullMat, pfInvertAffMat, pfInvertOrthoMat, pfInvertOrthoNMat, pfInvertIdentMat, pfEqualMat, pfAlmostEqualMat - Set and operate on 4x4 matrices.
void pfMakeIdentMat(pfMatrix dst);
void pfMakeTransMat(pfMatrix dst, float x, float y, float z);
void pfMakeScaleMat(pfMatrix dst, float x, float y, float z);
void pfMakeQuatMat(pfMatrix m, const pfQuat q);
void pfMakeEulerMat(pfMatrix dst, float h, float p, float r);
void pfMakeCoordMat(pfMatrix dst, const pfCoord *c);
int pfGetMatType(const pfMatrix mat);
void pfGetOrthoMatQuat(const pfMatrix m, pfQuat dst);
void pfGetOrthoMatCoord(pfMatrix m, pfCoord* dst);
void pfSetMat(const float *m);
void pfSetMatRowVec3(pfMatrix dst, int row, const pfVec3 v);
void pfGetMatRowVec3(const pfMatrix m, int row, pfVec3 dst);
void pfSetMatColVec3(pfMatrix dst, int col, const pfVec3 v);
void pfGetMatColVec3(const pfMatrix m, int col, pfVec3 dst);
void pfCopyMat(pfMatrix dst, const pfMatrix m);
void pfAddMat(pfMatrix dst, const pfMatrix m1, const pfMatrix m2);
void pfSubMat(pfMatrix dst, const pfMatrix m1, const pfMatrix m2);
void pfScaleMat(pfMatrix dst, float s, pfMatrix m);
void pfTransposeMat(pfMatrix dst, pfMatrix m);
void pfMultMat(pfMatrix dst, const pfMatrix m1, const pfMatrix m2);
void pfPreMultMat(pfMatrix dst, const pfMatrix m);
void pfPostMultMat(pfMatrix dst, const pfMatrix m);
int pfInvertFullMat(pfMatrix dst, const pfMatrix m);
void pfInvertAffMat(pfMatrix dst, const pfMatrix m);
void pfInvertOrthoMat(pfMatrix dst, const pfMatrix m);
void pfInvertOrthoNMat(pfMatrix dst, const pfMatrix m);
int pfInvertIdentMat(pfMatrix dst, const pfMatrix m);
void pfEqualMat(const pfMatrix m1, const pfMatrix m2);
void pfAlmostEqualMat(const pfMatrix m1, const pfMatrix m2, float tol);
typedef struct
{
pfVec3 xyz;
pfVec3 hpr;
} pfCoord;
pfMakeIdentMat sets dst 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).
pfMakeTransMat sets dst to the matrix which translates by (x, y, z). Equivalent macro: PFMAKE_TRANS_MAT.
pfMakeScaleMat sets dst 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
pfMakeRotMat sets dst 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.
pfMakeQuatMat builds a rotation matrix m that expresses the rotation defined by the quaternion q.
pfMakeEulerMat sets dst 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 dst = 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).
pfMakeVecRotVecMat sets dst 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.
pfMakeCoordMat sets dst 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.
pfGetOrthoMatQuat constructs a quaternion dst equivalent to the rotation expressed by the orthonormal matrix m.
pfGetOrthoMatCoord returns in dst 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.
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
pfGetMatType 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.
pfSetMatRow. dst[row][0] = x, dst[row][1] = y, dst[row][2] = z, dst[row][3] = w. Use the arguments to set row row of dst. row must be 0, 1, 2, or 3. Equivalent macro: PFSET_MAT_ROW.
pfGetMatRow. *x = dst[row][0], *y = dst[row][1], *z = dst[row][2], *w = dst[row][3]. Get the arguments to row row of dst. row must be 0, 1, 2, or 3. Equivalent macro: PFGET_MAT_ROW.
pfSetMatCol. dst[0][col] = x, dst[1][col] = y, dst[2][col] = z, dst[3][col] = w. Use the arguments to set col col of dst. col must be 0, 1, 2, or 3. Equivalent macro: PFSET_MAT_COL.
pfGetMatCol. *x = dst[0][col], *y = dst[1][col], *z = dst[2][col], *w = dst[3][col]. Get the arguments to col col of dst. col must be 0, 1, 2, or 3. Equivalent macro: PFGET_MAT_COL.
pfSetMatRowVec3. dst[row][i] = v[i], i = 0, 1, 2. Set row row of dst to the vector v. row must be 0, 1, 2, or 3. Equivalent macro: PFSET_MAT_ROWVEC3.
pfGetMatRowVec3. dst[i] = m[row][i], i = 0, 1, 2. Return row row of m and in dst. row must be 0, 1, 2, or 3. Equivalent macro: PFGET_MAT_ROWVEC3.
pfSetMatColVec3. dst[i][col] = v[i], i = 0, 1, 2. Set column col of dst to the vector v. col must be 0, 1, 2, or 3. Equivalent macro: PFSET_MAT_COLVEC3.
pfGetMatColVec3. dst[i] = m[i][col], i = 0, 1, 2. Return column col of m in dst. col must be 0, 1, 2, or 3. Equivalent macro: PFGET_MAT_COLVEC3.
pfPreTransMat: dst = T(x,y,z) * m, where T(x,y,z) is the matrix which translates by (x,y,z).
pfPostTransMat: dst = m * T(x,y,z), where T(x,y,z) is the matrix which translates by (x,y,z).
pfPreRotMat: dst = 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).
pfPostRotMat: dst = 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).
pfPreScaleMat: dst = S(x,y,z) * m, where S(x,y,z) is the matrix which scales by (x,y,z).
pfScaleMat: dst = s * m. Sets dst to the product of the scalar s and the matrix m. This multiplies the full 4X4 matrix and is not a 3D geometric scale.
pfInvertFullMat, pfInvertAffMat, pfInvertOrthoMat, pfInvertOrthoNMat, and pfInvertIdentMat, set dst 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. pfInvertFullMat returns FALSE if the matrix is singular and TRUE otherwise.
pfEqualMat(m1, m2) = (m1 == m2). Tests for strict component-by-element equality of two matrices m1 and m2 and returns FALSE or TRUE. Macro equivalent: PFEQUAL_MAT.
pfAlmostEqualMat(m1, m2, tol). Tests for approximate element-by-element equality of two matrices m1 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.
Routines can accept the same matrix as source, destination, or as a repeated operand.
Some of these routines use pfSinCos and pfSqrt, which are faster but have less resolution than the libm counterparts. (See pfSinCos)
pfSinCos, pfSqrt, pfVec3, pfVec4