pfMatrix4d(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
NAME
pfMakeIdentMat4d, pfMakeTransMat4d, pfMakeScaleMat4d, pfMakeRotMat4d,
pfMakeQuatMat4d, pfMakeEulerMat4d, pfMakeVecRotVecMat4d,
pfMakeCoordMat4d, pfGetMat4dType, pfGetOrthoMat4dQuat,
pfGetOrthoMat4dCoordd, pfSetMat4d, pfSetMat4dRowVec3, pfGetMat4dRowVec3,
pfSetMat4dColVec3, pfGetMat4dColVec3, pfSetMat4dRow, pfGetMat4dRow,
pfSetMat4dCol, pfGetMat4dCol, pfCopyMat4d, pfAddMat4d, pfSubMat4d,
pfScaleMat4d, pfTransposeMat4d, pfMultMat4d, pfPreMultMat4d,
pfPostMultMat4d, pfPreTransMat4d, pfPostTransMat4d, pfPreRotMat4d,
pfPostRotMat4d, pfPreScaleMat4d, pfPostScaleMat4d, pfInvertFullMat4d,
pfInvertAffMat4d, pfInvertOrthoMat4d, pfInvertOrthoNMat4d,
pfInvertIdentMat4d, pfEqualMat4d, pfAlmostEqualMat4d - Set and operate on
4x4 double-precision matrices.
FUNCTION SPECIFICATION
#include <Performer/pr.h>
void pfMakeIdentMat4d(pfMatrix4d dst);
void pfMakeTransMat4d(pfMatrix4d dst, double x, double y, double z);
void pfMakeScaleMat4d(pfMatrix4d dst, double x, double y, double z);
void pfMakeRotMat4d(pfMatrix4d dst, double degrees, double x, double y,
double z);
void pfMakeQuatMat4d(pfMatrix4d m, const pfQuatd q);
void pfMakeEulerMat4d(pfMatrix4d dst, double h, double p, double r);
void pfMakeVecRotVecMat4d(pfMatrix4d dst, const pfVec3d v1,
const pfVec3d v2);
void pfMakeCoordMat4d(pfMatrix4d dst, const pfCoordd *c);
int pfGetMat4dType(const pfMatrix4d mat);
void pfGetOrthoMat4dQuat(const pfMatrix4d m, pfQuatd dst);
void pfGetOrthoMat4dCoordd(pfMatrix4d m, pfCoordd* dst);
void pfSetMat4d(const double *m);
void pfSetMat4dRowVec3(pfMatrix4d dst, int row, const pfVec3d v);
void pfGetMat4dRowVec3(const pfMatrix4d m, int row, pfVec3d dst);
void pfSetMat4dColVec3(pfMatrix4d dst, int col, const pfVec3d v);
void pfGetMat4dColVec3(const pfMatrix4d m, int col, pfVec3d dst);
Page 1
pfMatrix4d(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
void pfSetMat4dRow(pfMatrix4d dst, int row, double x, double y,
double z, double w);
void pfGetMat4dRow(const pfMatrix4d m, int row, double *x, double *y,
double *z, double *w);
void pfSetMat4dCol(pfMatrix4d dst, int col, double x, double y,
double z, double w);
void pfGetMat4dCol(const pfMatrix4d m, int col, double *x, double *y,
double *z, double *w);
void pfCopyMat4d(pfMatrix4d dst, const pfMatrix4d m);
void pfAddMat4d(pfMatrix4d dst, const pfMatrix4d m1,
const pfMatrix4d m2);
void pfSubMat4d(pfMatrix4d dst, const pfMatrix4d m1,
const pfMatrix4d m2);
void pfScaleMat4d(pfMatrix4d dst, double s, pfMatrix4d m);
void pfTransposeMat4d(pfMatrix4d dst, pfMatrix4d m);
void pfMultMat4d(pfMatrix4d dst, const pfMatrix4d m1,
const pfMatrix4d m2);
void pfPreMultMat4d(pfMatrix4d dst, const pfMatrix4d m);
void pfPostMultMat4d(pfMatrix4d dst, const pfMatrix4d m);
void pfPreTransMat4d(pfMatrix4d dst, double x, double y, double z,
pfMatrix4d m);
void pfPostTransMat4d(pfMatrix4d dst, const pfMatrix4d m, double x,
double y, double z);
void pfPreRotMat4d(pfMatrix4d dst, double degrees, double x, double y,
double z, pfMatrix4d m);
void pfPostRotMat4d(pfMatrix4d dst, const pfMatrix4d mat,
double degrees, double x, double y, double z, );
void pfPreScaleMat4d(pfMatrix4d dst, double x, double y, double z,
pfMatrix4d m);
void pfPostScaleMat4d(pfMatrix4d dst, const pfMatrix4d m, double x,
double y, double z);
int pfInvertFullMat4d(pfMatrix4d dst, const pfMatrix4d m);
Page 2
pfMatrix4d(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
void pfInvertAffMat4d(pfMatrix4d dst, const pfMatrix4d m);
void pfInvertOrthoMat4d(pfMatrix4d dst, const pfMatrix4d m);
void pfInvertOrthoNMat4d(pfMatrix4d dst, const pfMatrix4d m);
int pfInvertIdentMat4d(pfMatrix4d dst, const pfMatrix4d m);
void pfEqualMat4d(const pfMatrix4d m1, const pfMatrix4d m2);
void pfAlmostEqualMat4d(const pfMatrix4d m1, const pfMatrix4d m2,
double tol);
typedef struct
{
pfVec3 xyz;
pfVec3 hpr;
} pfCoord;
typedef double pfMatrix4d[4][4];
DESCRIPTION
Routines for pfMatrix4d, a 4X4 double-precision matrix.
pfMakeIdentMat4d 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).
pfMakeTransMat4d sets dst to the matrix which translates by (x, y, z).
Equivalent macro: PFMAKE_TRANS_MAT.
pfMakeScaleMat4d 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
pfMakeRotMat4d 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.
pfMakeQuatMat4d builds a rotation matrix m that expresses the rotation
defined by the quaternion q.
pfMakeEulerMat4d sets dst to a rotation matrix composed of the Euler
angles h, p, r: h specifies heading, the rotation about the Z axis; p
Page 3
pfMatrix4d(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
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).
pfMakeVecRotVecMat4d 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.
pfMakeCoordMat4d 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.
pfGetOrthoMat4dQuatd constructs a quaternion dst equivalent to the
rotation expressed by the orthonormal matrix m.
pfGetOrthoMat4dCoordd 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.
pfDoubleDCSMatType 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 4
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.
pfGetMat4dType 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.
pfSetMat4dRow. 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.
pfGetMat4dRow. *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.
pfSetMat4dCol. 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.
pfGetMat4dCol. *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.
pfSetMat4dRowVec3. 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.
pfGetMat4dRowVec3. 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.
pfSetMat4dColVec3. 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.
pfGetMat4dColVec3. 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.
pfSetMat4d. dst[i][j] = m[i*4+j], 0 <= i,j <= 3.
pfCopyMat4d: dst = m. Copies m into dst. Equivalent macro: PFCOPY_MAT
pfPreTransMat4d: dst = T(x,y,z) * m, where T(x,y,z) is the matrix which
translates by (x,y,z).
pfPostTransMat4d: dst = m * T(x,y,z), where T(x,y,z) is the matrix which
translates by (x,y,z).
Page 5
pfMatrix4d(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
pfPreRotMat4d: 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).
pfPostRotMat4d: 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).
pfPreScaleMat4d: dst = S(x,y,z) * m, where S(x,y,z) is the matrix which
scales by (x,y,z).
pfPostScaleMat4d: dst = m * S(x,y,z), where S(x,y,z) is the matrix which
scales by (x,y,z).
pfAddMat4d: dst = m1 + m2. Sets dst to the sum of m1 and m2.
pfSubMat4d: dst = m1 - m2. Sets dst to the difference of m1 and m2.
pfScaleMat4d: 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.
pfTransposeMat4d: dst = Transpose(m). Sets dst to the transpose of m.
pfMultMat4d: dst = m1 * m2. Sets dst to the product of m1 and m2.
pfPostMultMat4d: dst = dst *m. Postmultiplies dst by m.
pfPreMultMat4d: dst = m * dst. Premultiplies dst by m.
pfInvertFullMat4d, pfInvertAffMat4d, pfInvertOrthoMat4d,
pfInvertOrthoNMat4d, and pfInvertIdentMat4d, 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. pfInvertFullMat4d returns FALSE
if the matrix is singular and TRUE otherwise.
pfEqualMat4d(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.
pfAlmostEqualMat4d(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.
Page 6
pfMatrix4d(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
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, pfVec3d, pfVec4
Page 7
