matrix3.h File Reference
 
 
 
matrix3.h File Reference

This reference page is linked to from the following overview topics: Rotation, 3DXI Initialization.


#include "GeomExport.h"
#include "maxheap.h"
#include "ioapi.h"
#include "point3.h"
#include "point4.h"

Classes

class   Matrix3

Defines

#define  POS_IDENT   1
#define  ROT_IDENT   2
#define  SCL_IDENT   4
#define  MAT_IDENT   (POS_IDENT|ROT_IDENT|SCL_IDENT)

Typedefs

typedef float  MRow [3]

Enumerations

enum   Axis { kXAxis, kYAxis, kZAxis }
  This enum can be used to specify axis under a variety of scenarios. More...
enum   TransComponent { kTrans = kZAxis + 1 }
  The TransComponent enum simply specifies the translation row index of a Matrix3. More...

Functions

Matrix3  RotateXMatrix (float angle)
Matrix3  RotateYMatrix (float angle)
Matrix3  RotateZMatrix (float angle)
Matrix3  TransMatrix (const Point3 &p)
Matrix3  ScaleMatrix (const Point3 &s)
Matrix3  RotateYPRMatrix (float Yaw, float Pitch, float Roll)
Matrix3  RotAngleAxisMatrix (Point3 &axis, float angle)
Matrix3  Inverse (const Matrix3 &M)
Matrix3  InverseHighPrecision (const Matrix3 &M)
Point3  operator* (const Matrix3 &A, const Point3 &V)
Point3  operator* (const Point3 &V, const Matrix3 &A)
Point3  VectorTransform (const Matrix3 &M, const Point3 &V)
Point3  VectorTransform (const Point3 &V, const Matrix3 &M)
Point4  TransformPlane (const Matrix3 &M, const Point4 &plane)
  transform a plane.
Matrix3  XFormMat (const Matrix3 &xm, const Matrix3 &m)
void  MirrorMatrix (Matrix3 &tm, Axis axis, bool scaleMatrix=false)
void  MatrixMultiply (Matrix3 &outMatrix, const Matrix3 &matrixA, const Matrix3 &matrixB)
void  Inverse (Matrix3 &outMatrix, const Matrix3 &M)

Define Documentation

#define POS_IDENT   1
#define ROT_IDENT   2
#define SCL_IDENT   4
#define MAT_IDENT   (POS_IDENT|ROT_IDENT|SCL_IDENT)

Typedef Documentation

typedef float MRow[3]

Enumeration Type Documentation

enum Axis

This enum can be used to specify axis under a variety of scenarios.

For example, passing kXAxis to GetRow returns the vector that represents the X axis of the transform, and accessing a point3 the enum returns the X, Y, or Z component of the translation.

Enumerator:
kXAxis 
kYAxis 

Specifies the X Axis.

kZAxis 

Specifies the Y Axis.

          {
        kXAxis, 
        kYAxis, 
        kZAxis, 
};

The TransComponent enum simply specifies the translation row index of a Matrix3.

The enum is used (along with Axis enum) to construct the MatrixComponent pseudo-enum via InheritEnum. This pseudo-enum can be used in places where programmers need to access the components of the matrix directly (for example, in the functions GetRow or directly in the Matrix3 internals via GetAddr).

Enumerator:
kTrans 
                    {
        kTrans = kZAxis + 1     
};

Function Documentation

Matrix3 RotateXMatrix ( float  angle )
Remarks:
Builds a new matrix for use as a X rotation transformation.
Parameters:
angle Specifies the angle of rotation in radians.
Returns:
A new X rotation Matrix3.
Matrix3 RotateYMatrix ( float  angle )
Remarks:
Builds a new matrix for use as a Y rotation transformation.
Parameters:
angle Specifies the angle of rotation in radians.
Returns:
A new Y rotation Matrix3.
Matrix3 RotateZMatrix ( float  angle )
Remarks:
Builds a new matrix for use as a Z rotation transformation.
Parameters:
angle Specifies the angle of rotation in radians.
Returns:
A new Z rotation Matrix3.
Matrix3 TransMatrix ( const Point3 p )
Remarks:
Builds a new matrix for use as a translation transformation.
Parameters:
p Specifies the translation values.
Returns:
A new translation Matrix3.
Matrix3 ScaleMatrix ( const Point3 s )
Remarks:
Builds a new matrix for use as a scale transformation.
Parameters:
s Specifies the scale values.
Returns:
A new scale Matrix3.
Matrix3 RotateYPRMatrix ( float  Yaw,
float  Pitch,
float  Roll 
)
Remarks:
Builds a new matrix for use as a rotation transformation by specifying yaw, pitch and roll angles.

This definition will depend on what our coordinate system is. This one is equivalent to:

M.IdentityMatrix();

M.RotateZ(roll);

M.RotateX(pitch);

M.RotateY(yaw);

Which presupposes Y is vertical, X is sideways, Z is forward
Parameters:
Yaw Specifies the yaw angle in radians.
Pitch Specifies the pitch angle in radians.
Roll Specifies the roll angle in radians.
Returns:
A new rotation Matrix3.
Matrix3 RotAngleAxisMatrix ( Point3 axis,
float  angle 
)
Remarks:
Builds a new matrix for use as a rotation transformation by specifying an angle and axis.
Parameters:
axis Specifies the axis of rotation. Note that this angle is expected to be normalized.
angle Specifies the angle of rotation. Note: The direction of the angle in this method is opposite of that in AngAxisFromQ().
Returns:
A new rotation Matrix3.
Matrix3 Inverse ( const Matrix3 M )
Remarks:
Return the inverse of the matrix
Parameters:
M The matrix to compute the inverse of.
Matrix3 InverseHighPrecision ( const Matrix3 M )
Remarks:
Return the inverse of the matrix using doubles for the intermediary results
Parameters:
M The matrix to compute the inverse of.
Point3 operator* ( const Matrix3 A,
const Point3 V 
)
Remarks:
These transform a Point3 with a Matrix3. These two versions of transforming a point with a matrix do the same thing, regardless of the order of operands (linear algebra rules notwithstanding).
Parameters:
A The matrix to transform the point with.
V The point to transform.
Returns:
The transformed Point3.
Point3 operator* ( const Point3 V,
const Matrix3 A 
)
Remarks:
These transform a Point3 with a Matrix3. These two versions of transforming a point with a matrix do the same thing, regardless of the order of operands (linear algebra rules notwithstanding).
Parameters:
V The point to transform.
A The matrix to transform the point with.
Returns:
The transformed Point3.
Point3 VectorTransform ( const Matrix3 M,
const Point3 V 
)
Remarks:
Transform the vector (Point3) with the specified matrix.
Parameters:
M The matrix to transform the vector with.
V The vector to transform.
Returns:
The transformed vector (as a Point3).
Point3 VectorTransform ( const Point3 V,
const Matrix3 M 
)
Point4 TransformPlane ( const Matrix3 M,
const Point4 plane 
)

transform a plane.

Note:
this only works if M is orthogonal
Parameters:
M The transformation to apply to the plain
plane the plane to be transformed
Matrix3 XFormMat ( const Matrix3 xm,
const Matrix3 m 
)
Remarks:
This method is used to build a matrix that constructs a transformation in a particular space. For example, say you have a rotation you want to apply, but you want to perform the rotation in another coordinate system. To do this, you typically transform into the space of the coordinate system, then apply the transformation, and then transform out of that coordinate system. This method constructs a matrix that does just this. It transforms matrix m so it is applied in the space of matrix xm. It returns a Matrix3 that is xm*m*Inverse(xm).
Parameters:
xm Specifies the coordinate system you want to work in.
m Specifies the transformation matrix.
Returns:
Returns a Matrix3 that is xm*m*Inverse(xm).
void MirrorMatrix ( Matrix3 tm,
Axis  axis,
bool  scaleMatrix = false 
)
Remarks:
Mirrors the input matrix against the X, Y, or Z axis. This function mirrors the input matrix such that if it transformed a Point3 p, the transform applied by the mirrored transform would place p in an equivalent position relative but with one of it's elements negated.
        Point3 p = ...; // Some arbitrary point;
        Matrix3 tm = ...; // Some matrix
        Matrix3 tmMirror = tm;
        MirrorMatrix(tm, kXAxis); // Mirror this matrix around the X Axis;
        Point3 p3Result = tm.PointTransform(p);                 // Apply the original transformation
        Point3 p3Mirrored = tmMirror.PointTransform(p); // Apply the mirrored transformation
        p3Result[kXAxis] == -p3Mirrored[kXAxis];                // The point is mirrored around X
        p3Result[kYAxis] == p3Mirrored[kYAxis];                 // The point is unchanged around Y
        p3Result[kZAxis] == p3Mirrored[kZAxis];                 // The point is unchanged around Z
Parameters:
[in,out] tm The Matrix to mirror
axis The world plane to mirror around. The axis will be reflected against the plane formed by the point (0, 0, 0) and the normal where normal[axis] = 1;
scaleMatrix The matrix can be mirrored either by pure rotation, or by pure scaling. If true, the matrix is mirrored by flipping one of its axis, changing the handedness of the matrix. This had the advantage that the mirroring will be passed onto all it's children. This is preferential when the system can handle it, but can cause issues in systems that do not compensate for scale, eg game pipelines and skinning. if false, the mirroring will be achieved using rotation only and will not affect child local positions. It is better to use non-scaling mirroring when dealing with tools or processes that do not well support scale, or when the matrix will be blended with non-scaled matrices. (eg, Point/Quat based pipelines and skinning)
void MatrixMultiply ( Matrix3 outMatrix,
const Matrix3 matrixA,
const Matrix3 matrixB 
)
Remarks:
Same as Maxtrix3::operator[]. Perform matrix multiplication without additional matrix copy
Parameters:
outMatrix The result of matrixA * matrixB
matrixA First matrix to multiply
matrixB Second matrix to multiply
void Inverse ( Matrix3 outMatrix,
const Matrix3 M 
)
Remarks:
Same as Maxtrix3::Inverse. Compute the inverse of the matrix without additional matrix copy
Parameters:
outMatrix The inversed matrix.
M The matrix to compute the inverse of.