matrix3.h File Reference

#include "GeomExport.h"
#include "point3.h"
#include "point4.h"
#include <cstdint>

Classes
class	Matrix3

Macros
#define	MAX_DEPRECATE_MATRIX_BOOL_CTOR(str)   [[deprecated(str)]]
	MAX_SILENCE_DEPRECATED_MATRIX_BOOL_CTOR Silences warning when using the Matrix(bool) constructor. More...
#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 (const Point3 &axis, float angle)
Matrix3	Inverse (const Matrix3 &M)
Matrix3	InverseHighPrecision (const Matrix3 &M)
Matrix3	PseudoInverse (const Matrix3 &m)
Matrix3	AffineTranspose (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. More...
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)
void	AffineTranspose (Matrix3 &outMatrix, const Matrix3 &M)
void	SetMatrixFromNormal (const Point3 &normal, Matrix3 &mat)

Macro Definition Documentation

MAX_DEPRECATE_MATRIX_BOOL_CTOR

#define MAX_DEPRECATE_MATRIX_BOOL_CTOR

(

str

)

[[deprecated(str)]]

MAX_SILENCE_DEPRECATED_MATRIX_BOOL_CTOR Silences warning when using the Matrix(bool) constructor.

Matrix3 and DMatrix3 are now created as identity by default!

POS_IDENT

#define POS_IDENT   1

ROT_IDENT

#define ROT_IDENT   2

SCL_IDENT

#define SCL_IDENT   4

MAT_IDENT

#define MAT_IDENT   (POS_IDENT | ROT_IDENT | SCL_IDENT)

Typedef Documentation

MRow

typedef float MRow[3]

Enumeration Type Documentation

Axis

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, 
};

TransComponent

enum TransComponent

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

RotateXMatrix()

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.

RotateYMatrix()

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.

RotateZMatrix()

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.

TransMatrix()

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.

ScaleMatrix()

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.

RotateYPRMatrix()

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.

RotAngleAxisMatrix()

Matrix3 RotAngleAxisMatrix	(	const 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.

Inverse() [1/2]

Matrix3 Inverse

(

const Matrix3 &

M

)

Remarks

Return the inverse of the matrix

Parameters

M	The matrix to compute the inverse of.

InverseHighPrecision()

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.

PseudoInverse()

Matrix3 PseudoInverse

(

const Matrix3 &

m

)

Remarks

Return the pseudoinverse of an affine symmetric matrix, meaning that if the matrix is degenerate (projects into a plane, line or point; eg. has both row 1 and column 1 zero) this will still produce a matrix that inverts the nonzero parts of the transform.

Parameters

m	The matrix to compute the pseudoinverse of.

AffineTranspose() [1/2]

Matrix3 AffineTranspose

(

const Matrix3 &

M

)

Remarks

Transposes the affine portion of the matrix. Since Matrix3 does not have a 4th column you cannot transpose the entire 4x4 matrix, so this method only transposes the 3x3 matrix representing rotations, scale and skew.

Parameters

M	The matrix to compute the affine transpose of.

operator*() [1/2]

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.

operator*() [2/2]

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.

VectorTransform() [1/2]

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).

VectorTransform() [2/2]

Point3 VectorTransform	(	const Point3 &	V,
		const Matrix3 &	M
	)

TransformPlane()

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

XFormMat()

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).

MirrorMatrix()

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)

MatrixMultiply()

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

Inverse() [2/2]

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.

AffineTranspose() [2/2]

void AffineTranspose	(	Matrix3 &	outMatrix,
		const Matrix3 &	M
	)

Remarks

Same as Matrix3::AffineTranspose. Computes the affine transpose without additional matrix copy

Parameters

outMatrix	The inversed matrix.
M	The matrix to compute the affine transpose of.

SetMatrixFromNormal()

void SetMatrixFromNormal	(	const Point3 &	normal,
		Matrix3 &	mat
	)

Remarks

Create a rotational matrix oriented to the provided normal.

Parameters

normal	The normal vector, must be normalized.
mat	The output orientation matrix.