OGRE: Ogre::Matrix4 Class Reference - OGRE Documentation

Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Attributes | Friends

# Ogre::Matrix4 Class Reference
[Math]

Class encapsulating a standard 4x4 homogeneous matrix. More...

`#include <OgreMatrix4.h>`

List of all members.

## Public Member Functions
| Matrix4 ()
| Default constructor.
| Matrix4 (Real m00, Real m01, Real m02, Real m03, Real m10, Real m11, Real m12, Real m13, Real m20, Real m21, Real m22, Real m23, Real m30, Real m31, Real m32, Real m33)
| Matrix4 (const Matrix3 &m3x3)
| Creates a standard 4x4 transformation matrix with a zero translation part from a rotation/scaling 3x3 matrix.
| Matrix4 (const Quaternion &rot)
| Creates a standard 4x4 transformation matrix with a zero translation part from a rotation/scaling Quaternion.
void | swap (Matrix4 &other)
| Exchange the contents of this matrix with another.
Real * | operator[] (size_t iRow)
const Real * | operator[] (size_t iRow) const
Matrix4 | concatenate (const Matrix4 &m2) const
Matrix4 | operator* (const Matrix4 &m2) const
| Matrix concatenation using '*'.
Vector3 | operator* (const Vector3 &v) const
| Vector transformation using '*'.
Vector4 | operator* (const Vector4 &v) const
Plane | operator* (const Plane &p) const
Matrix4 | operator+ (const Matrix4 &m2) const
| Matrix addition.
Matrix4 | operator- (const Matrix4 &m2) const
| Matrix subtraction.
bool | operator== (const Matrix4 &m2) const
| Tests 2 matrices for equality.
bool | operator!= (const Matrix4 &m2) const
| Tests 2 matrices for inequality.
void | operator= (const Matrix3 &mat3)
| Assignment from 3x3 matrix.
Matrix4 | transpose (void) const
void | setTrans (const Vector3 &v)
| Sets the translation transformation part of the matrix.
Vector3 | getTrans () const
| Extracts the translation transformation part of the matrix.
void | makeTrans (const Vector3 &v)
| Builds a translation matrix.
void | makeTrans (Real tx, Real ty, Real tz)
void | setScale (const Vector3 &v)
| Sets the scale part of the matrix.
void | extract3x3Matrix (Matrix3 &m3x3) const
| Extracts the rotation / scaling part of the Matrix as a 3x3 matrix.
bool | hasScale () const
| Determines if this matrix involves a scaling.
bool | hasNegativeScale () const
| Determines if this matrix involves a negative scaling.
Quaternion | extractQuaternion () const
| Extracts the rotation / scaling part as a quaternion from the Matrix.
Matrix4 | operator* (Real scalar) const
Matrix4 | adjoint () const
Real | determinant () const
Matrix4 | inverse () const
void | makeTransform (const Vector3 &position, const Vector3 &scale, const Quaternion &orientation)
| Building a Matrix4 from orientation / scale / position.
void | makeInverseTransform (const Vector3 &position, const Vector3 &scale, const Quaternion &orientation)
| Building an inverse Matrix4 from orientation / scale / position.
void | decomposition (Vector3 &position, Vector3 &scale, Quaternion &orientation) const
| Decompose a Matrix4 to orientation / scale / position.
bool | isAffine (void) const
| Check whether or not the matrix is affine matrix.
Matrix4 | inverseAffine (void) const
| Returns the inverse of the affine matrix.
Matrix4 | concatenateAffine (const Matrix4 &m2) const
| Concatenate two affine matrices.
Vector3 | transformAffine (const Vector3 &v) const
| 3-D Vector transformation specially for an affine matrix.
Vector4 | transformAffine (const Vector4 &v) const
| 4-D Vector transformation specially for an affine matrix.
## Static Public Member Functions
static Matrix4 | getTrans (const Vector3 &v)
| Gets a translation matrix.
static Matrix4 | getTrans (Real t_x, Real t_y, Real t_z)
| Gets a translation matrix - variation for not using a vector.
static Matrix4 | getScale (const Vector3 &v)
| Gets a scale matrix.
static Matrix4 | getScale (Real s_x, Real s_y, Real s_z)
| Gets a scale matrix - variation for not using a vector.
## Static Public Attributes
static const Matrix4 | ZERO
static const Matrix4 | IDENTITY
static const Matrix4 | CLIPSPACE2DTOIMAGESPACE
| Useful little matrix which takes 2D clipspace {-1, 1} to {0,1} and inverts the Y.
## Protected Attributes
union {
Real m [4][4]
Real _m [16]
}; |
| The matrix entries, indexed by [row][col].
## Friends
_OgreExport friend std::ostream & | operator<< (std::ostream &o, const Matrix4 &mat)
| Function for writing to a stream.

## Detailed Description

Class encapsulating a standard 4x4 homogeneous matrix.

Remarks:
  OGRE uses column vectors when applying matrix multiplications, This means a vector is represented as a single column, 4-row matrix. This has the effect that the transformations implemented by the matrices happens right-to-left e.g. if vector V is to be transformed by M1 then M2 then M3, the calculation would be M3 * M2 * M1 * V. The order that matrices are concatenated is vital since matrix multiplication is not commutative, i.e. you can get a different result if you concatenate in the wrong order.

  The use of column vectors and right-to-left ordering is the standard in most mathematical texts, and is the same as used in OpenGL. It is, however, the opposite of Direct3D, which has inexplicably chosen to differ from the accepted standard and uses row vectors and left-to-right matrix multiplication.

  OGRE deals with the differences between D3D and OpenGL etc. internally when operating through different render systems. OGRE users only need to conform to standard maths conventions, i.e. right-to-left matrix multiplication, (OGRE transposes matrices it passes to D3D to compensate).

  The generic form M * V which shows the layout of the matrix entries is shown below:

                      [ m[0][0]  m[0][1]  m[0][2]  m[0][3] ]   {x}
                      | m[1][0]  m[1][1]  m[1][2]  m[1][3] | * {y}
                      | m[2][0]  m[2][1]  m[2][2]  m[2][3] |   {z}
                      [ m[3][0]  m[3][1]  m[3][2]  m[3][3] ]   {1}

Definition at line 78 of file OgreMatrix4.h.

## Constructor & Destructor Documentation

Ogre::Matrix4::Matrix4 | ( |  | ) |

Default constructor.

Note:
  It does NOT initialize the matrix for efficiency.

Definition at line 91 of file OgreMatrix4.h.

Ogre::Matrix4::Matrix4 | ( | Real | m00,
|  | Real | m01,
|  | Real | m02,
|  | Real | m03,
|  | Real | m10,
|  | Real | m11,
|  | Real | m12,
|  | Real | m13,
|  | Real | m20,
|  | Real | m21,
|  | Real | m22,
|  | Real | m23,
|  | Real | m30,
|  | Real | m31,
|  | Real | m32,
|  | Real | m33 |
| ) |  |  |

Definition at line 95 of file OgreMatrix4.h.

Ogre::Matrix4::Matrix4 | ( | const Matrix3 & | m3x3 | ) |

Creates a standard 4x4 transformation matrix with a zero translation part from a rotation/scaling 3x3 matrix.

Definition at line 122 of file OgreMatrix4.h.

Ogre::Matrix4::Matrix4 | ( | const Quaternion & | rot | ) |

Creates a standard 4x4 transformation matrix with a zero translation part from a rotation/scaling Quaternion.

Definition at line 131 of file OgreMatrix4.h.

References Ogre::Quaternion::ToRotationMatrix().

## Member Function Documentation

Matrix4 Ogre::Matrix4::adjoint | ( |  | ) | const

Matrix4 Ogre::Matrix4::concatenate | ( | const Matrix4 & | m2 | ) | const

Definition at line 174 of file OgreMatrix4.h.

References m.

Matrix4 Ogre::Matrix4::concatenateAffine | ( | const Matrix4 & | m2 | ) | const

Concatenate two affine matrices.

Note:
  The matrices must be affine matrix.

See also:
  Matrix4::isAffine.

Definition at line 586 of file OgreMatrix4.h.

References isAffine(), and m.

void Ogre::Matrix4::decomposition | ( | Vector3 & | position,
|  | Vector3 & | scale,
|  | Quaternion & | orientation |
| ) |  |  | const

Decompose a Matrix4 to orientation / scale / position.

Real Ogre::Matrix4::determinant | ( |  | ) | const

void Ogre::Matrix4::extract3x3Matrix | ( | Matrix3 & | m3x3 | ) | const

Extracts the rotation / scaling part of the Matrix as a 3x3 matrix.

Parameters:

  | m3x3 | Destination Matrix3

Definition at line 463 of file OgreMatrix4.h.

References Ogre::Matrix3::m.

Quaternion Ogre::Matrix4::extractQuaternion | ( |  | ) | const

Extracts the rotation / scaling part as a quaternion from the Matrix.

Definition at line 502 of file OgreMatrix4.h.

static Matrix4 Ogre::Matrix4::getScale | ( | const Vector3 & | v | ) | `[static]`

Gets a scale matrix.

Definition at line 436 of file OgreMatrix4.h.

References m, Ogre::Vector3::x, Ogre::Vector3::y, and Ogre::Vector3::z.

static Matrix4 Ogre::Matrix4::getScale | ( | Real | s_x,
|  | Real | s_y,
|  | Real | s_z |
| ) |  |  | `[static]`

Gets a scale matrix - variation for not using a vector.

Definition at line 449 of file OgreMatrix4.h.

References m.

static Matrix4 Ogre::Matrix4::getTrans | ( | const Vector3 & | v | ) | `[static]`

Gets a translation matrix.

Definition at line 394 of file OgreMatrix4.h.

References m, Ogre::Vector3::x, Ogre::Vector3::y, and Ogre::Vector3::z.

Vector3 Ogre::Matrix4::getTrans | ( |  | ) | const

Extracts the translation transformation part of the matrix.

Definition at line 368 of file OgreMatrix4.h.

static Matrix4 Ogre::Matrix4::getTrans | ( | Real | t_x,
|  | Real | t_y,
|  | Real | t_z |
| ) |  |  | `[static]`

Gets a translation matrix - variation for not using a vector.

Definition at line 408 of file OgreMatrix4.h.

References m.

bool Ogre::Matrix4::hasNegativeScale | ( |  | ) | const

Determines if this matrix involves a negative scaling.

Definition at line 495 of file OgreMatrix4.h.

bool Ogre::Matrix4::hasScale | ( |  | ) | const

Determines if this matrix involves a scaling.

Definition at line 478 of file OgreMatrix4.h.

References Ogre::Math::RealEqual().

Matrix4 Ogre::Matrix4::inverse | ( |  | ) | const

Matrix4 Ogre::Matrix4::inverseAffine | ( | void |  | ) | const

Returns the inverse of the affine matrix.

Note:
  The matrix must be an affine matrix.

See also:
  Matrix4::isAffine.

bool Ogre::Matrix4::isAffine | ( | void |  | ) | const

Check whether or not the matrix is affine matrix.

Remarks:
  An affine matrix is a 4x4 matrix with row 3 equal to (0, 0, 0, 1), e.g. no projective coefficients.

Definition at line 571 of file OgreMatrix4.h.

Referenced by concatenateAffine(), and Ogre::AxisAlignedBox::transformAffine().

void Ogre::Matrix4::makeInverseTransform | ( | const Vector3 & | position,
|  | const Vector3 & | scale,
|  | const Quaternion & | orientation |
| ) |  |  |

Building an inverse Matrix4 from orientation / scale / position.

Remarks:
  As makeTransform except it build the inverse given the same data as makeTransform, so performing -translation, -rotate, 1/scale in that order.

void Ogre::Matrix4::makeTrans | ( | const Vector3 & | v | ) |

Builds a translation matrix.

Definition at line 376 of file OgreMatrix4.h.

References Ogre::Vector3::x, Ogre::Vector3::y, and Ogre::Vector3::z.

void Ogre::Matrix4::makeTrans | ( | Real | tx,
|  | Real | ty,
|  | Real | tz |
| ) |  |  |

Definition at line 384 of file OgreMatrix4.h.

void Ogre::Matrix4::makeTransform | ( | const Vector3 & | position,
|  | const Vector3 & | scale,
|  | const Quaternion & | orientation |
| ) |  |  |

Building a Matrix4 from orientation / scale / position.

Remarks:
  Transform is performed in the order scale, rotate, translation, i.e. translation is independent of orientation axes, scale does not affect size of translation, rotation and scaling are always centered on the origin.

bool Ogre::Matrix4::operator!= | ( | const Matrix4 & | m2 | ) | const

Tests 2 matrices for inequality.

Definition at line 324 of file OgreMatrix4.h.

References m.

Matrix4 Ogre::Matrix4::operator* | ( | Real | scalar | ) | const

Definition at line 515 of file OgreMatrix4.h.

Matrix4 Ogre::Matrix4::operator* | ( | const Matrix4 & | m2 | ) | const

Matrix concatenation using '*'.

Definition at line 202 of file OgreMatrix4.h.

Vector3 Ogre::Matrix4::operator* | ( | const Vector3 & | v | ) | const

Vector transformation using '*'.

Remarks:
  Transforms the given 3-D vector by the matrix, projecting the result back into w = 1.

Note:
  This means that the initial w is considered to be 1.0, and then all the tree elements of the resulting 3-D vector are divided by the resulting w.

Definition at line 216 of file OgreMatrix4.h.

References Ogre::Vector3::x, Ogre::Vector3::y, and Ogre::Vector3::z.

Plane Ogre::Matrix4::operator* | ( | const Plane & | p | ) | const

Definition at line 237 of file OgreMatrix4.h.

References Ogre::Plane::d, Ogre::Plane::normal, Ogre::Vector3::normalise(), Ogre::Vector3::x, Ogre::Vector3::y, and Ogre::Vector3::z.

Vector4 Ogre::Matrix4::operator* | ( | const Vector4 & | v | ) | const

Definition at line 228 of file OgreMatrix4.h.

References Ogre::Vector4::w, Ogre::Vector4::x, Ogre::Vector4::y, and Ogre::Vector4::z.

Matrix4 Ogre::Matrix4::operator+ | ( | const Matrix4 & | m2 | ) | const

Matrix addition.

Definition at line 254 of file OgreMatrix4.h.

References m.

Matrix4 Ogre::Matrix4::operator- | ( | const Matrix4 & | m2 | ) | const

Matrix subtraction.

Definition at line 283 of file OgreMatrix4.h.

References m.

void Ogre::Matrix4::operator= | ( | const Matrix3 & | mat3 | ) |

Assignment from 3x3 matrix.

Definition at line 337 of file OgreMatrix4.h.

References Ogre::Matrix3::m.

bool Ogre::Matrix4::operator== | ( | const Matrix4 & | m2 | ) | const

Tests 2 matrices for equality.

Definition at line 311 of file OgreMatrix4.h.

References m.

Real* Ogre::Matrix4::operator[] | ( | size_t | iRow | ) |

Definition at line 162 of file OgreMatrix4.h.

const Real* Ogre::Matrix4::operator[] | ( | size_t | iRow | ) | const

Definition at line 168 of file OgreMatrix4.h.

void Ogre::Matrix4::setScale | ( | const Vector3 & | v | ) |

Sets the scale part of the matrix.

Definition at line 427 of file OgreMatrix4.h.

References Ogre::Vector3::x, Ogre::Vector3::y, and Ogre::Vector3::z.

void Ogre::Matrix4::setTrans | ( | const Vector3 & | v | ) |

Sets the translation transformation part of the matrix.

Definition at line 359 of file OgreMatrix4.h.

References Ogre::Vector3::x, Ogre::Vector3::y, and Ogre::Vector3::z.

void Ogre::Matrix4::swap | ( | Matrix4 & | other | ) |

Exchange the contents of this matrix with another.

Definition at line 142 of file OgreMatrix4.h.

References m.

Vector3 Ogre::Matrix4::transformAffine | ( | const Vector3 & | v | ) | const

3-D Vector transformation specially for an affine matrix.

Remarks:
  Transforms the given 3-D vector by the matrix, projecting the result back into w = 1.

Note:
  The matrix must be an affine matrix.

See also:
  Matrix4::isAffine.

Definition at line 616 of file OgreMatrix4.h.

References Ogre::Vector3::x, Ogre::Vector3::y, and Ogre::Vector3::z.

Referenced by Ogre::AxisAlignedBox::transformAffine().

Vector4 Ogre::Matrix4::transformAffine | ( | const Vector4 & | v | ) | const

4-D Vector transformation specially for an affine matrix.

Note:
  The matrix must be an affine matrix.

See also:
  Matrix4::isAffine.

Definition at line 630 of file OgreMatrix4.h.

References Ogre::Vector4::w, Ogre::Vector4::x, Ogre::Vector4::y, and Ogre::Vector4::z.

Matrix4 Ogre::Matrix4::transpose | ( | void |  | ) | const

Definition at line 344 of file OgreMatrix4.h.

## Friends And Related Function Documentation

_OgreExport friend std::ostream& operator<< | ( | std::ostream & | o,
|  | const Matrix4 & | mat |
| ) |  |  | `[friend]`

Function for writing to a stream.

Definition at line 527 of file OgreMatrix4.h.

## Member Data Documentation

union { ... } `[protected]`

The matrix entries, indexed by [row][col].

Real Ogre::Matrix4::_m[16]

Definition at line 84 of file OgreMatrix4.h.

const Matrix4 Ogre::Matrix4::CLIPSPACE2DTOIMAGESPACE`[static]`

Useful little matrix which takes 2D clipspace {-1, 1} to {0,1} and inverts the Y.

Definition at line 513 of file OgreMatrix4.h.

const Matrix4 Ogre::Matrix4::IDENTITY`[static]`

Definition at line 510 of file OgreMatrix4.h.

Real Ogre::Matrix4::m[4][4]

Definition at line 83 of file OgreMatrix4.h.

Referenced by concatenate(), concatenateAffine(), getScale(), getTrans(), operator!=(), operator+(), operator-(), operator==(), and swap().

const Matrix4 Ogre::Matrix4::ZERO`[static]`

Definition at line 509 of file OgreMatrix4.h.

The documentation for this class was generated from the following file:

- OgreMatrix4.h

Copyright © 2008 Torus Knot Software Ltd
This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.
Last modified Wed Nov 3 2010 19:24:56