DMatrix3 Class Reference

#include <dmatrix3.h>

Class Description

Class DPoint3, Matrix Representations of 3D Transformations, Class Quat, Class AngAxis, Structure AffineParts, Class BigMatrix.

Description: This class implements a 4x3 3D transformation matrix object. Methods are provided to zero the matrix, set it to the identity, compute its inverse, apply incremental translation, rotation and scaling, and build new X, Y and Z rotation matrices. Operators are provided for matrix addition, subtraction, and multiplication. All methods are implemented by the system.

Note: In 3ds Max, all vectors are assumed to be row vectors. Under this assumption, multiplication of a vector with a matrix can be written either way (Matrix*Vector or Vector*Matrix), for ease of use, and the result is the same – the (row) vector transformed by the matrix. Data Members: private:

double m[4][3];

Matrix storage.

DWORD flags;

Matrix Identity Flags.

POS_IDENT

Indicates the translation row of the matrix is the identity.

ROT_IDENT

Indicates the rotation elements of the matrix are the identity.

SCL_IDENT

Indicates the scale elements of the matrix are the identity.

MAT_IDENT

Indicates the matrix is the identity matrix. This is equivalent to (POS_IDENT|ROT_IDENT|SCL_IDENT).

Inheritance diagram for DMatrix3:

Public Member Functions
const DPoint3 &	operator[] (int i) const
	Returns a reference to the 'i-th' DPoint3 of the matrix. More...
void	SetNotIdent ()
	This clears the MAT_IDENT flag to indicate the matrix is not the identity. More...
void	SetIdentFlags (DWORD f)
	This sets the specified identity flag(s). More...
DWORD	GetIdentFlags () const
	Returns the identity flags. More...
void	ClearIdentFlag (DWORD f)
	Clears the specified identity flag(s). More...
BOOL	IsIdentity () const
	Returns TRUE if the matrix is the identity matrix (based on the flags); otherwise FALSE. More...
void	ValidateFlags ()
	This method may be used to recompute the *_IDENT flags for this matrix. More...
MRow *	GetAddr ()
	Returns the address of this Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3. More...
const MRow *	GetAddr () const
	Returns the address of this Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3. More...
	DMatrix3 ()
	Constructor. More...
	DMatrix3 (BOOL init)
	Constructor. More...
	DMatrix3 (const DPoint3 &row0, const DPoint3 &row1, const DPoint3 &row2, const DPoint3 &row3)
	Constructor. More...
DMatrix3 &	Set (const DPoint3 &row0, const DPoint3 &row1, const DPoint3 &row2, const DPoint3 &row3)
	Initializes the matrix with the row data passed and validates the matrix flags. More...
int	operator== (const DMatrix3 &m) const
	Compares the elements of this matrix and the one specified element by element for exact equality. More...
bool	operator!= (const DMatrix3 &m) const
	Compares the elements of this matrix and the one specified element by element for inequality. More...
int	Equals (const DMatrix3 &m, double epsilon=1E-12) const
	Compares the elements of this matrix and the one specified element by element for equality within the specified tolerance epsilon. More...
DMatrix3 &	operator-= (const DMatrix3 &m)
	Subtracts a Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3 from this Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3. More...
DMatrix3 &	operator+= (const DMatrix3 &m)
	Adds a Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3 to this Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3. More...
DMatrix3 &	operator*= (const DMatrix3 &m)
	Multiplies this Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3 by the specified Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3 (*this = (*this)*M;). More...
DMatrix3 &	operator*= (double a)
	Multiplies each element of this Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3 by a double. More...
void	IdentityMatrix ()
	Set this matrix to the Identity Matrix. More...
void	Zero ()
	This method sets all elements of the matrix to 0.0f. More...
DPoint3	GetRow (int i) const
	Returns the specified row of this matrix. More...
void	SetRow (int i, DPoint3 p)
	Sets the specified row of this matrix to the specified values. More...
Point4	GetColumn (int i) const
	Returns the 'i-th' column of this matrix. More...
void	SetColumn (int i, Point4 col)
	Sets the 'i-th' column of this matrix to the specified values. More...
DPoint3	GetColumn3 (int i) const
	Returns the upper three entries in the specified column. More...
void	NoTrans ()
	This method zeros the translation portion of this matrix. More...
void	NoRot ()
	This method zeros the rotation and scale portion of this matrix. More...
void	NoScale ()
	This method zeros the scale portion of this matrix without orthogonalization. More...
void	Orthogonalize ()
	Ortho-normalize the matrix. More...
void	SetTrans (const DPoint3 &p)
	Sets the translation row of this matrix to the specified values. More...
void	SetTrans (int i, double v)
	Sets the specified component of the translation row of this matrix to the specified value. More...
const DPoint3 &	GetTrans () const
	Returns the translation row of this matrix. More...
void	Translate (const DPoint3 &p)
	Apply an incremental translation transformation to this matrix. More...
void	RotateX (double angle)
	Apply an incremental X rotation transformation to this matrix. More...
void	RotateY (double angle)
	Apply an incremental Y rotation transformation to this matrix. More...
void	RotateZ (double angle)
	Apply an incremental Z rotation transformation to this matrix. More...
void	Scale (const DPoint3 &s, BOOL trans=FALSE)
	Apply an incremental scaling transformation to this matrix. More...
void	PreTranslate (const DPoint3 &p)
	Apply an incremental translation transformation to this matrix. More...
void	PreRotateX (double angle)
	Apply an incremental X rotation transformation to this matrix. More...
void	PreRotateY (double angle)
	Apply an incremental Y rotation transformation to this matrix. More...
void	PreRotateZ (double angle)
	Apply an incremental Z rotation transformation to this matrix. More...
void	PreScale (const DPoint3 &s, BOOL trans=FALSE)
	Apply an incremental scaling transformation to this matrix. More...
void	SetTranslate (const DPoint3 &p)
	Sets this matrix to the identity and the translation components to the specified values. More...
void	SetRotateX (double angle)
	Sets this matrix to the identity and the rotation components to the specified X rotation. More...
void	SetRotateY (double angle)
	Sets this matrix to the identity and the rotation components to the specified Y rotation. More...
void	SetRotateZ (double angle)
	Sets this matrix to the identity and the rotation components to the specified Z rotation. More...
void	SetRotate (const Quat &q)
	Sets the rotation components of the matrix as specified by the quaternion. More...
void	SetRotate (const AngAxis &aa)
	Sets the rotation components of the matrix as specified by the AngAxis. More...
void	SetRotate (double yaw, double pitch, double roll)
	Sets the rotation components of this matrix using yaw, pitch and roll angles. More...
void	SetAngleAxis (const DPoint3 &axis, double angle)
	Sets the rotation portion of the matrix to the rotation specified by the angle and axis and sets the translation portion to zeros. More...
void	SetScale (const DPoint3 &s)
	Sets the scale components of this matrix to the specified values. More...
void	SetFromToUp (const DPoint3 &from, const DPoint3 &to, const DPoint3 &up)
	This creates a matrix describing a viewpoint which is at the 'from' location, looking toward the 'to' location; the viewpoint is tilted so that the 'up' vector points to the top of the view. More...
void	Invert ()
	This method performs an in-place inversion on this matrix. More...
DMatrix3	operator* (const DMatrix3 &) const
	Perform matrix multiplication. More...
DMatrix3	operator+ (const DMatrix3 &) const
	Perform matrix addition. More...
DMatrix3	operator- (const DMatrix3 &) const
	Perform matrix subtraction. More...
DPoint3	PointTransform (const DPoint3 &p) const
	Returns the specified point transformed by this matrix. More...
DPoint3	VectorTransform (const DPoint3 &p) const
	Returns the specified vector transformed by this matrix. More...
void	TransformPoints (DPoint3 *array, int n, int stride=sizeof(DPoint3))
	Transforms the specified list of points with this matrix. More...
void	TransformPoints (const DPoint3 *array, DPoint3 *to, int n, int stride=sizeof(DPoint3), int strideTo=sizeof(DPoint3))
	Transforms the specified list of points with this matrix and stores the resulting transformed points in the storage passed. More...
void	TransformVectors (DPoint3 *array, int n, int stride=sizeof(DPoint3))
	Transforms the specified list of vectors with this matrix. More...
void	TransformVectors (const DPoint3 *array, DPoint3 *to, int n, int stride=sizeof(DPoint3), int strideTo=sizeof(DPoint3))
	Transforms the specified list of vectors with this matrix and stores the resulting transformed vectors in the storage passed. More...
void	GetYawPitchRoll (double *yaw, double *pitch, double *roll)
	Retrieves the yaw, pitch and roll angles represented by the rotation in this matrix. More...
IOResult	Save (ISave *isave)
	Save this Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3 to disk. More...
IOResult	Load (ILoad *iload)
	Load the data for this Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3. More...
bool	Parity () const
	Returns the 'parity' of the matrix. More...
Matrix3	ToMatrix3 ()
	Converts to a Matrix3. More...
void	FromMatrix3 (const Matrix3 &tm)
	Copies a matrix3 into the Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3. More...

Static Public Attributes
static const DMatrix3	Identity
	An global instance of Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3 set to the identity. More...

Friends
class	Quat
DMatrix3	RotateXMatrix (double angle)
	Builds a new matrix for use as a X rotation transformation. More...
DMatrix3	RotateYMatrix (double angle)
	Builds a new matrix for use as a Y rotation transformation. More...
DMatrix3	RotateZMatrix (double angle)
	Builds a new matrix for use as a Z rotation transformation. More...
DMatrix3	TransMatrix (const DPoint3 &p)
	Builds a new matrix for use as a translation transformation. More...
DMatrix3	ScaleMatrix (const DPoint3 &s)
	Builds a new matrix for use as a scale transformation. More...
DMatrix3	RotateYPRMatrix (double yaw, double pitch, double roll)
	Builds a new matrix for use as a rotation transformation by specifying yaw, pitch and roll angles. More...
DMatrix3	RotAngleAxisMatrix (DPoint3 &axis, double angle)
	Builds a new matrix for use as a rotation transformation by specifying an angle and axis. More...
DMatrix3	Inverse (const DMatrix3 &m)
	Return the inverse of the matrix. More...
DMatrix3	InverseHighPrecision (const DMatrix3 &m)
	Return the inverse of the matrix using doubles for the intermediary results. More...
DPoint3	operator* (const DMatrix3 &a, const DPoint3 &v)
	These transform a DPoint3 with a Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3. More...
DPoint3	operator* (const DPoint3 &v, const DMatrix3 &a)
	These transform a DPoint3 with a Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3. More...
DPoint3	VectorTransform (const DMatrix3 &m, const DPoint3 &v)
	Transform the vector (DPoint3) with the specified matrix. More...
DMatrix3	XFormMat (const DMatrix3 &xm, const DMatrix3 &m)
	This method is used to build a matrix that constructs a transformation in a particular space. More...
DPoint3	VectorTransform (const DPoint3 &v, const DMatrix3 &m)
void	MatrixMultiply (DMatrix3 &outMatrix, const DMatrix3 &matrixA, const DMatrix3 &matrixB)
	Same as Maxtrix3::operator[]. More...
void	Inverse (DMatrix3 &outMatrix, const DMatrix3 &m)
	Same as Maxtrix3::Inverse. More...

Additional Inherited Members
Static Public Member Functions inherited from MaxHeapOperators
static UtilExport void *	operator new (size_t size)
	Standard new operator used to allocate objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e)
	Standard new operator used to allocate objects if there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new (size_t size, const char *filename, int line)
	New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate objects that takes the type of memory, filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e, const char *filename, int line)
	New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new (size_t size, unsigned long flags)
	New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e, unsigned long flags)
	New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size, const char *filename, int line)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate arrays of objects. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e, const char *filename, int line)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size, unsigned long flags)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e, unsigned long flags)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void	operator delete (void *ptr)
	Standard delete operator used to deallocate an object If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e)
	Standard delete operator used to deallocate an object If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete (void *ptr, const char *filename, int line)
	Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, int block_type, const char *filename, int line)
	Delete operator used to deallocate an object that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e, const char *filename, int line)
	Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete (void *ptr, unsigned long flags)
	Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e, unsigned long flags)
	Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr)
	Standard delete operator used to deallocate an array of objects If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e)
	Standard delete operator used to deallocate an array of objects If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, int block_type, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr, unsigned long flags)
	Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e, unsigned long flags)
	Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, void *placement_ptr)
	Placement new operator. More...
static UtilExport void	operator delete (void *ptr, void *placement_ptr)
	Placement delete operator. More...

Constructor & Destructor Documentation

DMatrix3 ( )

inline

Constructor.

Note that no initialization is done. Use Zero() or Identity(), or the constructors below.

{ flags = 0; }

DMatrix3 ( BOOL  init )

inline

Constructor.

The matrix is set to the identity.

Parameters

init

Unused.

{UNREFERENCED_PARAMETER(init); flags=0; IdentityMatrix();}

DMatrix3 ( const DPoint3 &  row0, const DPoint3 &  row1, const DPoint3 &  row2, const DPoint3 &  row3  )

inline

Constructor.

Initializes the matrix with the row data passed and validates the matrix flags.

Parameters

row0	The data for row 0.
row1	The data for row 1.
row2	The data for row 2.
row3	The data for row 3.

{ Set(row0, row1, row2, row3); }

Member Function Documentation

const DPoint3& operator[] ( int  i ) const

inline

Returns a reference to the 'i-th' DPoint3 of the matrix.

{ return((DPoint3&)(*m[i])); }

void SetNotIdent ( )

inline

This clears the MAT_IDENT flag to indicate the matrix is not the identity.

If any changes are made to components directly via GetAddr(), this method must be called.

{ flags &= ~MAT_IDENT; }

void SetIdentFlags ( DWORD  f )

inline

This sets the specified identity flag(s).

Parameters

f	Specifies the identity flag bit(s) to set. See Matrix Identity Flags above.

{ flags &= ~MAT_IDENT; flags |= f; }

DWORD GetIdentFlags ( ) const

inline

Returns the identity flags.

{ return flags; }

void ClearIdentFlag ( DWORD  f )

inline

Clears the specified identity flag(s).

See Matrix Identity Flags above.

Parameters

f	Specifies the identity flag bit(s) to clear.

{ flags &= ~f; }

BOOL IsIdentity ( ) const

inline

Returns TRUE if the matrix is the identity matrix (based on the flags); otherwise FALSE.

{ return ((flags&MAT_IDENT)==MAT_IDENT); }

void ValidateFlags

(

)

This method may be used to recompute the *_IDENT flags for this matrix.

For instance, if you call a method, such as INode::GetObjTMAfterWSM(), and it returns a matrix, you cannot use the IsIdentity() method to check if the matrix is indeed the identity. This is because the flags that method checks are not initialized by the INode method. What you can do however is call this method first. This will validate the flags in the matrix so they accuratly reflect the properties of the matrix. If after calling this method, and then calling IsIdentity(), the proper result would be returned.

MRow* GetAddr ( )

inline

Returns the address of this Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3.

The Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3 class keeps flags indicating identity for rotation, scale, position, and the matrix as a whole, and thus the direct access via the [] operator is restricted to prevent developers from modifying the matrix without updating the flags. This method, GetAddr(), still lets you get at the matrix itself and then you can use the [] operator on the result. Note: If you change the matrix via this pointer, you MUST clear the proper IDENT flags!

Also Note: typedef double MRow[3];

Returns

The address of the Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3.

{ return (MRow *)(m); }   

const MRow* GetAddr ( ) const

inline

Returns the address of this Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3.

The Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3 class keeps flags indicating identity for rotation, scale, position, and the matrix as a whole, and thus the direct access via the [] operator is restricted to prevent developers from modifying the matrix without updating the flags. This method, GetAddr(), still lets you get at the matrix itself and then you can use the [] operator on the result. Note: If you change the matrix via this pointer, you MUST clear the proper IDENT flags!

Also Note: typedef double MRow[3];

{ return (MRow *)(m); }

DMatrix3& Set ( const DPoint3 &  row0, const DPoint3 &  row1, const DPoint3 &  row2, const DPoint3 &  row3  )

inline

Initializes the matrix with the row data passed and validates the matrix flags.

Parameters

row0	The data for row 0.
row1	The data for row 1.
row2	The data for row 2.
row3	The data for row 3.

Returns

A reference to this matrix.

                                                                                                      {
        flags = 0; SetRow(kXAxis, row0); SetRow(kYAxis, row1); SetRow(kZAxis, row2); SetRow(kTrans, row3); 
        ValidateFlags(); return *this; }

int operator==

(

const DMatrix3 &

m

)

const

Compares the elements of this matrix and the one specified element by element for exact equality.

Returns nonzero if they are equal; otherwise zero.

Parameters

m	The matrix to compare against.

bool operator!= ( const DMatrix3 &  m ) const

inline

Compares the elements of this matrix and the one specified element by element for inequality.

Returns false iff they are unequal.

Parameters

m	The matrix to compare against.

{ return (operator==(m) == 0); }

int Equals	(	const DMatrix3 &	m,
		double	epsilon = 1E-12
	)		const

Compares the elements of this matrix and the one specified element by element for equality within the specified tolerance epsilon.

Returns nonzero if they are 'equal'; otherwise zero.

Parameters

m	The matrix to compare against.
epsilon	The tolerance for comparison. If the values in the matrix are within this value (+ epsilon or - epsilon) they are considered equal.

DMatrix3& operator-=

(

const DMatrix3 &

m

)

Subtracts a Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3 from this Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3.

DMatrix3& operator+=

(

const DMatrix3 &

m

)

Adds a Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3 to this Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3.

DMatrix3& operator*=

(

const DMatrix3 &

m

)

Multiplies this Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3 by the specified Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3 (*this = (*this)*M;).

Multiply this matrix on the right by Matrix m.

DMatrix3 tm1, tm2;
DMatrix3 tm3 = tm1 * tm2;   // Is equivalent to the below
tm1 *= tm2;                 // tm1 now equals tm3

Parameters

m	The matrix multiplied to the right of this matrix

Returns

A reference to this matrix

DMatrix3& operator*=

(

double

a

)

Multiplies each element of this Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3 by a double.

DMatrix3 tm1(1), tm2(2);
tm1 *= 0.7f;    // This multiplies all elements by 0.7f
tm2.Scale(DPoint3(0.7f, 0.7f, 0.7f), TRUE); // This multiplies all elements by 0.7f
tm1 == tm2; // is true

Parameters

a	The scale to apply to each element of this matrix

Returns

a reference to this matrix

void IdentityMatrix

(

)

Set this matrix to the Identity Matrix.

void Zero

(

)

This method sets all elements of the matrix to 0.0f.

DPoint3 GetRow ( int  i ) const

inline

Returns the specified row of this matrix.

Parameters

i	Specifies the row to retrieve.

{ return (*this)[i]; }

void SetRow	(	int	i,
		DPoint3	p
	)

Sets the specified row of this matrix to the specified values.

Parameters

i	Specifies the row to set.
p	The values to set.

Point4 GetColumn

(

int

i

)

const

Returns the 'i-th' column of this matrix.

Parameters

i	Specifies the column to get (0-2).

void SetColumn	(	int	i,
		Point4	col
	)

Sets the 'i-th' column of this matrix to the specified values.

Parameters

i	Specifies the column to set (0-2).
col	The values to set.

DPoint3 GetColumn3

(

int

i

)

const

Returns the upper three entries in the specified column.

Parameters

i	Specifies the partial column to get (0-2).

void NoTrans

(

)

This method zeros the translation portion of this matrix.

void NoRot

(

)

This method zeros the rotation and scale portion of this matrix.

void NoScale

(

)

This method zeros the scale portion of this matrix without orthogonalization.

If the matrix was sheared (skewed) then this method is not able to remove the scale component completely. In that case, use the Orthogonalize() method instead to remove the scale component entirely. Read the SCL_IDENT flag to check whether the NoScale() method was enough to make the matrix to be orthogonal (with perpendicular axes of unit length).

void Orthogonalize

(

)

Ortho-normalize the matrix.

This ensures that each axis of the basis is of length 1 and at right angles to the other. This is an "unbiased" orthogonalization, which means that no single axis is used as the basis for the other axis, and all axis will be modified equally.

Note

This is an iterative process, and should not be used in high-performance situations. It seems to take a maximum of 4 iterations to converge.

void SetTrans ( const DPoint3 &  p )

inline

Sets the translation row of this matrix to the specified values.

The POS_IDENT flag is cleared.

Parameters

p	Specifies the values for the translation row.

{ (*this)[kTrans] = p;  flags &= ~POS_IDENT; }

void SetTrans ( int  i, double  v  )

inline

Sets the specified component of the translation row of this matrix to the specified value.

The POS_IDENT flag is cleared.

Parameters

i	Specifies the component of the translation row of this matrix to set.
v	The value to set.

{ (*this)[kTrans][i] = v; flags &= ~POS_IDENT; }

const DPoint3& GetTrans ( ) const

inline

Returns the translation row of this matrix.

Returns

The translation row of this matrix.

{ return (*this)[kTrans]; }

void Translate

(

const DPoint3 &

p

)

Apply an incremental translation transformation to this matrix.

This is equivalent to multiplying on the RIGHT by the transform.

Parameters

p	Specifies the translation.

void RotateX

(

double

angle

)

Apply an incremental X rotation transformation to this matrix.

This is equivalent to multiplying on the RIGHT by the transform.

Parameters

angle

Specifies the X rotation in radians.

void RotateY

(

double

angle

)

Apply an incremental Y rotation transformation to this matrix.

This is equivalent to multiplying on the RIGHT by the transform.

Parameters

angle

Specifies the Y rotation in radians.

void RotateZ

(

double

angle

)

Apply an incremental Z rotation transformation to this matrix.

This is equivalent to multiplying on the RIGHT by the transform.

Parameters

angle

Specifies the Z rotation in radians.

void Scale	(	const DPoint3 &	s,
		BOOL	trans = FALSE
	)

Apply an incremental scaling transformation to this matrix.

This is equivalent to multiplying on the RIGHT by the transform.

Parameters

s

The scale values.

trans

If set to TRUE, the translation component is scaled. If trans = FALSE the translation component is unaffected. When 3ds Max was originally written there was a bug in the code for this method where the translation portion of the matrix was not being scaled. This meant that when a matrix was scaled the bottom row was not scaled. Thus it would always scale about the local origin of the object, but it would scale the world axes. When this bug was discovered, dependencies existed in the code upon this bug. Thus it could not simply be fixed because it would break the existing code that depended upon it working the incorrect way. To correct this the trans parameter was added. If this is set to TRUE, the translation component will be scaled correctly. The existing plug-ins don't use this parameter, it defaults to FALSE, and the code behaves the old way.

void PreTranslate

(

const DPoint3 &

p

)

Apply an incremental translation transformation to this matrix.

This is equivalent to multiplying on the LEFT by the transform. param p Specifies the translation distance.

void PreRotateX

(

double

angle

)

Apply an incremental X rotation transformation to this matrix.

This is equivalent to multiplying on the LEFT by the transform.

Parameters

angle

Specifies the X rotation in radians.

void PreRotateY

(

double

angle

)

Apply an incremental Y rotation transformation to this matrix.

This is equivalent to multiplying on the LEFT by the transform.

Parameters

angle

Specifies the Y rotation in radians.

void PreRotateZ

(

double

angle

)

Apply an incremental Z rotation transformation to this matrix.

This is equivalent to multiplying on the LEFT by the transform.

Parameters

angle

Specifies the Z rotation in radians.

void PreScale	(	const DPoint3 &	s,
		BOOL	trans = FALSE
	)

Apply an incremental scaling transformation to this matrix.

This is equivalent to multiplying on the LEFT by the transform.

Parameters

s	The scale values.
trans	= FALSE If trans = FALSE the translation component is unaffected.

void SetTranslate

(

const DPoint3 &

p

)

Sets this matrix to the identity and the translation components to the specified values.

Parameters

p	The translation values to store.

void SetRotateX

(

double

angle

)

Sets this matrix to the identity and the rotation components to the specified X rotation.

Parameters

angle

The angle for X rotation (in radians).

void SetRotateY

(

double

angle

)

Sets this matrix to the identity and the rotation components to the specified Y rotation.

Parameters

angle

The angle for Y rotation (in radians).

void SetRotateZ

(

double

angle

)

Sets this matrix to the identity and the rotation components to the specified Z rotation.

Parameters

angle

The angle for Z rotation (in radians).

void SetRotate

(

const Quat &

q

)

Sets the rotation components of the matrix as specified by the quaternion.

The translation and scale components will match the identity matrix.

Parameters

q	Specifies the rotation to use for the matrix.

void SetRotate

(

const AngAxis &

aa

)

Sets the rotation components of the matrix as specified by the AngAxis.

The translation and scale components will match the identity matrix.

Parameters

aa	Specifies the rotation to use for the matrix.

void SetRotate	(	double	yaw,
		double	pitch,
		double	roll
	)

Sets the rotation components of this matrix using yaw, pitch and roll angles.

There are many different conventions for specifying a rotation by means of three Euler angles. This function uses the convention of rotating around the world Z axis, then the X axis, then the Y axis; the three arguments are given in the order Y, X, Z.

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	The yaw angle in radians.
pitch	The pitch angle in radians.
roll	The roll angle in radians.

void SetAngleAxis	(	const DPoint3 &	axis,
		double	angle
	)

Sets the rotation portion of the matrix to the rotation specified by the angle and axis and sets the translation portion to zeros.

Parameters

axis	The axis of rotation.
angle	The angle of rotation about the axis in radians.

void SetScale

(

const DPoint3 &

s

)

Sets the scale components of this matrix to the specified values.

The other components to this matrix will match the identity.

Parameters

s	The scale factors for the matrix.

void SetFromToUp	(	const DPoint3 &	from,
		const DPoint3 &	to,
		const DPoint3 &	up
	)

This creates a matrix describing a viewpoint which is at the 'from' location, looking toward the 'to' location; the viewpoint is tilted so that the 'up' vector points to the top of the view.

Parameters

from	This specifies the viewpoint source location.
to	This vector specifies the direction of view.
up	This vector points to the top of the view.

void Invert

(

)

This method performs an in-place inversion on this matrix.

An inverted matrix, when multiplied by the original, yields the identity.

DMatrix3 operator*

(

const DMatrix3 &

)

const

Perform matrix multiplication.

DMatrix3 operator+

(

const DMatrix3 &

)

const

Perform matrix addition.

DMatrix3 operator-

(

const DMatrix3 &

)

const

Perform matrix subtraction.

DPoint3 PointTransform

(

const DPoint3 &

p

)

const

Returns the specified point transformed by this matrix.

Parameters

p	The point to transform by this matrix.

DPoint3 VectorTransform

(

const DPoint3 &

p

)

const

Returns the specified vector transformed by this matrix.

Parameters

p	The vector to transform by this matrix.

void TransformPoints	(	DPoint3 *	array,
		int	n,
		int	stride = sizeof(DPoint3)
	)

Transforms the specified list of points with this matrix.

Parameters

array	The array of points to transform with this matrix.
n	The number of points in the array.
stride	The size of the increment used when moving to the next point. If you wish to transform an array of data objects which contain x, y, and z coordinates in order (such as a Point4, or a structure containing a DPoint3 as a member) you can specify a 'stride' value (for instance sizeof(data_object)).

void TransformPoints	(	const DPoint3 *	array,
		DPoint3 *	to,
		int	n,
		int	stride = sizeof(DPoint3),
		int	strideTo = sizeof(DPoint3)
	)

Transforms the specified list of points with this matrix and stores the resulting transformed points in the storage passed.

Parameters

array	The array of points to transform (the source).
to	The array to store the transformed points (the destination).
n	The number of points in the source array.
stride	The size increment used when moving to the next source location.
strideTo	The size increment used when moving to the next storage location.

void TransformVectors	(	DPoint3 *	array,
		int	n,
		int	stride = sizeof(DPoint3)
	)

Transforms the specified list of vectors with this matrix.

Parameters

array	The array of vectors to transform with this matrix.
n	The number of vectors in the array.
stride	The size of the increment used when moving to the next vector. If you wish to transform an array of data objects which contain x, y, and z coordinates in order (such as a Point4, or a structure containing a DPoint3 as a member) you can specify a 'stride' value (for instance sizeof(data_object)).

void TransformVectors	(	const DPoint3 *	array,
		DPoint3 *	to,
		int	n,
		int	stride = sizeof(DPoint3),
		int	strideTo = sizeof(DPoint3)
	)

Transforms the specified list of vectors with this matrix and stores the resulting transformed vectors in the storage passed.

Parameters

*array	The array of vectors to transform (the source).
to	The array to store the transformed vectors (the destination).
n	The number of vectors in the source array.
stride	The size increment used when moving to the next source location.
strideTo	The size increment used when moving to the next storage location.

void GetYawPitchRoll	(	double *	yaw,
		double *	pitch,
		double *	roll
	)

Retrieves the yaw, pitch and roll angles represented by the rotation in this matrix.

Parameters

yaw	The yaw rotation angle is stored here (in radians).
pitch	The pitch rotation angle is stored here (in radians).
roll	The roll rotation angle is stored here (in radians).

IOResult Save

(

ISave *

isave

)

Save this Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3 to disk.

Parameters

isave

The interface responsible for actually saving the data

Returns

IO_OK on success, or a failure code

IOResult Load

(

ILoad *

iload

)

Load the data for this Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3.

Parameters

iload

The interface responsible for actually loading the data

Returns

IO_OK on success, or a failure code

bool Parity

(

)

const

Returns the 'parity' of the matrix.

Scaling one axis of the matrix negatively switches the 'parity'. However if you scale two axis the parity will flip back. Scaling three axis switches the parity again.

When rendering a mesh, if you scale something along one axis, it turns 'inside out'. That is the direction when the normals are reversed. This method may be used to detect that case and then reverse the normals. The 3ds Max renderer does this – if this method returns TRUE it flips all the normals so it won't turn inside out.

Matrix3 ToMatrix3

(

)

Converts to a Matrix3.

Returns

the concersion to Matrix3

void FromMatrix3

(

const Matrix3 &

tm

)

Copies a matrix3 into the Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3.

Friends And Related Function Documentation

friend class Quat

friend

DMatrix3 RotateXMatrix ( double  angle )

friend

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 Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3.

DMatrix3 RotateYMatrix ( double  angle )

friend

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 Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3.

DMatrix3 RotateZMatrix ( double  angle )

friend

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 Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3.

DMatrix3 TransMatrix ( const DPoint3 &  p )

friend

Builds a new matrix for use as a translation transformation.

Parameters

p	Specifies the translation values.

Returns

A new translation Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3.

DMatrix3 ScaleMatrix ( const DPoint3 &  s )

friend

Builds a new matrix for use as a scale transformation.

Parameters

s	Specifies the scale values.

Returns

A new scale Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3.

DMatrix3 RotateYPRMatrix ( double  yaw, double  pitch, double  roll  )

friend

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 Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3.

DMatrix3 RotAngleAxisMatrix ( DPoint3 &  axis, double  angle  )

friend

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 Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3.

DMatrix3 Inverse ( const DMatrix3 &  m )

friend

Return the inverse of the matrix.

Parameters

m	The matrix to compute the inverse of.

DMatrix3 InverseHighPrecision ( const DMatrix3 &  m )

friend

Return the inverse of the matrix using doubles for the intermediary results.

Parameters

m	The matrix to compute the inverse of.

DPoint3 operator* ( const DMatrix3 &  a, const DPoint3 &  v  )

friend

These transform a DPoint3 with a Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3.

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

DPoint3 operator* ( const DPoint3 &  v, const DMatrix3 &  a  )

friend

These transform a DPoint3 with a Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3.

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

DPoint3 VectorTransform ( const DMatrix3 &  m, const DPoint3 &  v  )

friend

Transform the vector (DPoint3) with the specified matrix.

Parameters

m	The matrix to transform the vector with.
v	The vector to transform.

Returns

The transformed vector (as a DPoint3).

DMatrix3 XFormMat ( const DMatrix3 &  xm, const DMatrix3 &  m  )

friend

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 Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3 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 Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3 that is xm*m*Inverse(xm).

DPoint3 VectorTransform ( const DPoint3 &  v, const DMatrix3 &  m  )

friend

void MatrixMultiply ( DMatrix3 &  outMatrix, const DMatrix3 &  matrixA, const DMatrix3 &  matrixB  )

friend

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 ( DMatrix3 &  outMatrix, const DMatrix3 &  m  )

friend

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.

Member Data Documentation

const DMatrix3 Identity

static

An global instance of Matrix Representations of 3D Transformations, Class Quat, Class AngAxis...">DMatrix3 set to the identity.

An identity matrix has no rotation, scale or translation on it. In other words, it is a matrix that has no effect when multiplied with another matrix.
the structure of the Matrix is as follows:

[1, 0, 0]
[0, 1, 0]
[0, 0, 1]
[0, 0, 0]