pfMatrix(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfMatrix(3pf)NAME
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.
FUNCTION SPECIFICATION
#include <Performer/pr.h>
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 pfMakeRotMat(pfMatrix dst, float degrees, float x, float y,
float z);
void pfMakeQuatMat(pfMatrix m, const pfQuat q);
void pfMakeEulerMat(pfMatrix dst, float h, float p, float r);
void pfMakeVecRotVecMat(pfMatrix dst, const pfVec3 v1,
const pfVec3 v2);
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 pfSetMatRow(pfMatrix dst, int row, float x, float y, float z,
float w);
Page 1
pfMatrix(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfMatrix(3pf)
void pfGetMatRow(const pfMatrix m, int row, float *x, float *y,
float *z, float *w);
void pfSetMatCol(pfMatrix dst, int col, float x, float y, float z,
float w);
void pfGetMatCol(const pfMatrix m, int col, float *x, float *y,
float *z, float *w);
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);
void pfPreTransMat(pfMatrix dst, float x, float y, float z,
pfMatrix m);
void pfPostTransMat(pfMatrix dst, const pfMatrix m, float x, float y,
float z);
void pfPreRotMat(pfMatrix dst, float degrees, float x, float y,
float z, pfMatrix m);
void pfPostRotMat(pfMatrix dst, const pfMatrix mat, float degrees,
float x, float y, float z, );
void pfPreScaleMat(pfMatrix dst, float x, float y, float z,
pfMatrix m);
void pfPostScaleMat(pfMatrix dst, const pfMatrix m, float x, float y,
float z);
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);
Page 2
pfMatrix(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfMatrix(3pf)
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;
typedef float pfMatrix[4][4];
DESCRIPTION
Routines for pfMatrix, a 4X4 matrix.
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).
Page 3
pfMatrix(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfMatrix(3pf)
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.
pfGetMatType 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.
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.
Page 4
pfMatrix(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfMatrix(3pf)
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.
pfSetMat. dst[i][j] = m[i*4+j], 0 <= i,j <= 3.
pfCopyMat: dst = m. Copies m into dst. Equivalent macro: PFCOPY_MAT
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).
pfPostScaleMat: dst = m * S(x,y,z), where S(x,y,z) is the matrix which
scales by (x,y,z).
pfAddMat: dst = m1 + m2. Sets dst to the sum of m1 and m2.
Page 5
pfMatrix(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfMatrix(3pf)
pfSubMat: dst = m1 - m2. Sets dst to the difference of m1 and m2.
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.
pfTransposeMat: dst = Transpose(m). Sets dst to the transpose of m.
pfMultMat: dst = m1 * m2. Sets dst to the product of m1 and m2.
pfPostMultMat: dst = dst *m. Postmultiplies dst by m.
pfPreMultMat: dst = m * dst. Premultiplies dst by m.
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.
NOTES
Some of these routines use pfSinCos and pfSqrt, which are faster but have
less resolution than the libm counterparts. (See pfSinCos)
SEE ALSO
pfSinCos, pfSqrt, pfVec3, pfVec4
Page 6
