OGRE-Next  2.3
Object-Oriented Graphics Rendering Engine
Ogre::Matrix4 Class Reference

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

#include <OgreMatrix4.h>

Public Member Functions

 Matrix4 ()
 Default constructor. More...
 
 Matrix4 (const Matrix3 &m3x3)
 Creates a standard 4x4 transformation matrix with a zero translation part from a rotation/scaling 3x3 matrix. More...
 
 Matrix4 (const Quaternion &rot)
 Creates a standard 4x4 transformation matrix with a zero translation part from a rotation/scaling Quaternion. More...
 
 Matrix4 (const Real *arr)
 
 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 adjoint () const
 
Matrix4 concatenate (const Matrix4 &m2) const
 
Matrix4 concatenateAffine (const Matrix4 &m2) const
 Concatenate two affine matrices. More...
 
void decomposition (Vector3 &position, Vector3 &scale, Quaternion &orientation) const
 Decompose a Matrix4 to orientation / scale / position. More...
 
Real determinant () const
 
void extract3x3Matrix (Matrix3 &m3x3) const
 Extracts the rotation / scaling part of the Matrix as a 3x3 matrix. More...
 
Quaternion extractQuaternion () const
 Extracts the rotation / scaling part as a quaternion from the Matrix. More...
 
Vector3 getTrans () const
 Extracts the translation transformation part of the matrix. More...
 
bool hasNegativeScale () const
 Determines if this matrix involves a negative scaling. More...
 
bool hasScale () const
 Determines if this matrix involves a scaling. More...
 
Matrix4 inverse () const
 
Matrix4 inverseAffine () const
 Returns the inverse of the affine matrix. More...
 
bool isAffine () const
 Check whether or not the matrix is affine matrix. More...
 
void makeInverseTransform (const Vector3 &position, const Vector3 &scale, const Quaternion &orientation)
 Building an inverse Matrix4 from orientation / scale / position. More...
 
void makeTrans (const Vector3 &v)
 Builds a translation matrix. More...
 
void makeTrans (Real tx, Real ty, Real tz)
 
void makeTransform (const Vector3 &position, const Vector3 &scale, const Quaternion &orientation)
 Building a Matrix4 from orientation / scale / position. More...
 
bool operator!= (const Matrix4 &m2) const
 Tests 2 matrices for inequality. More...
 
Matrix4 operator* (const Matrix4 &m2) const
 Matrix concatenation using '*'. More...
 
Plane operator* (const Plane &p) const
 
Vector3 operator* (const Vector3 &v) const
 Vector transformation using '*'. More...
 
Vector4 operator* (const Vector4 &v) const
 
Matrix4 operator* (Real scalar) const
 
Matrix4 operator+ (const Matrix4 &m2) const
 Matrix addition. More...
 
Matrix4 operator- (const Matrix4 &m2) const
 Matrix subtraction. More...
 
void operator= (const Matrix3 &mat3)
 Assignment from 3x3 matrix. More...
 
bool operator== (const Matrix4 &m2) const
 Tests 2 matrices for equality. More...
 
Realoperator[] (size_t iRow)
 
const Realoperator[] (size_t iRow) const
 
void setScale (const Vector3 &v)
 Sets the scale part of the matrix. More...
 
void setTrans (const Vector3 &v)
 Sets the translation transformation part of the matrix. More...
 
void swap (Matrix4 &other)
 Exchange the contents of this matrix with another. More...
 
Vector3 transformAffine (const Vector3 &v) const
 3-D Vector transformation specially for an affine matrix. More...
 
Vector4 transformAffine (const Vector4 &v) const
 4-D Vector transformation specially for an affine matrix. More...
 
Vector3 transformDirectionAffine (const Vector3 &v) const
 3-D Vector transformation specially for an affine matrix. More...
 
Matrix4 transpose () const
 

Static Public Member Functions

static Matrix4 getScale (const Vector3 &v)
 Gets a scale matrix. More...
 
static Matrix4 getScale (Real s_x, Real s_y, Real s_z)
 Gets a scale matrix - variation for not using a vector. More...
 
static Matrix4 getTrans (const Vector3 &v)
 Gets a translation matrix. More...
 
static Matrix4 getTrans (Real t_x, Real t_y, Real t_z)
 Gets a translation matrix - variation for not using a vector. More...
 

Static Public Attributes

static const Matrix4 CLIPSPACE2DTOIMAGESPACE
 Useful little matrix which takes 2D clipspace {-1, 1} to {0,1} and inverts the Y. More...
 
static const Matrix4 IDENTITY
 
static const Matrix4 ZERO
 
static const Matrix4 ZEROAFFINE
 

Friends

class ArrayMatrix4
 
class ArrayMatrixAf4x3
 
_OgreExport friend std::ostream & operator<< (std::ostream &o, const Matrix4 &mat)
 Function for writing to a stream. More...
 
class SimpleMatrix4
 
class SimpleMatrixAf4x3
 

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}
    

Constructor & Destructor Documentation

◆ Matrix4() [1/5]

Ogre::Matrix4::Matrix4 ( )
inline

Default constructor.

Note
It does NOT initialize the matrix for efficiency.

◆ Matrix4() [2/5]

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

◆ Matrix4() [3/5]

Ogre::Matrix4::Matrix4 ( const Real arr)
inline

◆ Matrix4() [4/5]

Ogre::Matrix4::Matrix4 ( const Matrix3 m3x3)
inline

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

◆ Matrix4() [5/5]

Ogre::Matrix4::Matrix4 ( const Quaternion rot)
inline

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

References Ogre::Quaternion::ToRotationMatrix().

Member Function Documentation

◆ adjoint()

Matrix4 Ogre::Matrix4::adjoint ( ) const

◆ concatenate()

Matrix4 Ogre::Matrix4::concatenate ( const Matrix4 m2) const
inline

References m.

◆ concatenateAffine()

Matrix4 Ogre::Matrix4::concatenateAffine ( const Matrix4 m2) const
inline

Concatenate two affine matrices.

Note
The matrices must be affine matrix.
See also
Matrix4::isAffine.

References isAffine(), and m.

◆ decomposition()

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

Decompose a Matrix4 to orientation / scale / position.

◆ determinant()

Real Ogre::Matrix4::determinant ( ) const

◆ extract3x3Matrix()

void Ogre::Matrix4::extract3x3Matrix ( Matrix3 m3x3) const
inline

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

Parameters
m3x3Destination Matrix3

◆ extractQuaternion()

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

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

◆ getScale() [1/2]

static Matrix4 Ogre::Matrix4::getScale ( const Vector3 v)
inlinestatic

Gets a scale matrix.

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

◆ getScale() [2/2]

static Matrix4 Ogre::Matrix4::getScale ( Real  s_x,
Real  s_y,
Real  s_z 
)
inlinestatic

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

References m.

◆ getTrans() [1/3]

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

Extracts the translation transformation part of the matrix.

◆ getTrans() [2/3]

static Matrix4 Ogre::Matrix4::getTrans ( const Vector3 v)
inlinestatic

Gets a translation matrix.

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

◆ getTrans() [3/3]

static Matrix4 Ogre::Matrix4::getTrans ( Real  t_x,
Real  t_y,
Real  t_z 
)
inlinestatic

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

References m.

◆ hasNegativeScale()

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

Determines if this matrix involves a negative scaling.

◆ hasScale()

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

Determines if this matrix involves a scaling.

References Ogre::Math::RealEqual().

◆ inverse()

Matrix4 Ogre::Matrix4::inverse ( ) const

◆ inverseAffine()

Matrix4 Ogre::Matrix4::inverseAffine ( ) const

Returns the inverse of the affine matrix.

Note
The matrix must be an affine matrix.
See also
Matrix4::isAffine.

Referenced by Ogre::VrData::set().

◆ isAffine()

bool Ogre::Matrix4::isAffine ( ) const
inline

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.

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

◆ makeInverseTransform()

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.

◆ makeTrans() [1/2]

void Ogre::Matrix4::makeTrans ( const Vector3 v)
inline

Builds a translation matrix.

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

◆ makeTrans() [2/2]

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

◆ makeTransform()

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.

◆ operator!=()

bool Ogre::Matrix4::operator!= ( const Matrix4 m2) const
inline

Tests 2 matrices for inequality.

References m.

◆ operator*() [1/5]

Matrix4 Ogre::Matrix4::operator* ( const Matrix4 m2) const
inline

Matrix concatenation using '*'.

◆ operator*() [2/5]

◆ operator*() [3/5]

Vector3 Ogre::Matrix4::operator* ( const Vector3 v) const
inline

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.

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

◆ operator*() [4/5]

Vector4 Ogre::Matrix4::operator* ( const Vector4 v) const
inline

◆ operator*() [5/5]

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

◆ operator+()

Matrix4 Ogre::Matrix4::operator+ ( const Matrix4 m2) const
inline

Matrix addition.

References m.

◆ operator-()

Matrix4 Ogre::Matrix4::operator- ( const Matrix4 m2) const
inline

Matrix subtraction.

References m.

◆ operator=()

void Ogre::Matrix4::operator= ( const Matrix3 mat3)
inline

Assignment from 3x3 matrix.

◆ operator==()

bool Ogre::Matrix4::operator== ( const Matrix4 m2) const
inline

Tests 2 matrices for equality.

References m.

◆ operator[]() [1/2]

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

◆ operator[]() [2/2]

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

◆ setScale()

void Ogre::Matrix4::setScale ( const Vector3 v)
inline

Sets the scale part of the matrix.

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

◆ setTrans()

void Ogre::Matrix4::setTrans ( const Vector3 v)
inline

Sets the translation transformation part of the matrix.

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

◆ swap()

void Ogre::Matrix4::swap ( Matrix4 other)
inline

Exchange the contents of this matrix with another.

References m, and std::swap().

◆ transformAffine() [1/2]

Vector3 Ogre::Matrix4::transformAffine ( const Vector3 v) const
inline

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.

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

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

◆ transformAffine() [2/2]

Vector4 Ogre::Matrix4::transformAffine ( const Vector4 v) const
inline

4-D Vector transformation specially for an affine matrix.

Note
The matrix must be an affine matrix.
See also
Matrix4::isAffine.

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

◆ transformDirectionAffine()

Vector3 Ogre::Matrix4::transformDirectionAffine ( const Vector3 v) const
inline

3-D Vector transformation specially for an affine matrix.

Remarks
Transforms the given 3-D vector by the 3x3 submatrix, without adding translation, as should be transformed directions and normals.
Note
The matrix must be an affine matrix.
See also
Matrix4::isAffine.

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

◆ transpose()

Matrix4 Ogre::Matrix4::transpose ( ) const
inline

Referenced by operator*().

Friends And Related Function Documentation

◆ ArrayMatrix4

friend class ArrayMatrix4
friend

◆ ArrayMatrixAf4x3

friend class ArrayMatrixAf4x3
friend

◆ operator<<

_OgreExport friend std::ostream& operator<< ( std::ostream &  o,
const Matrix4 mat 
)
friend

Function for writing to a stream.

◆ SimpleMatrix4

friend class SimpleMatrix4
friend

◆ SimpleMatrixAf4x3

friend class SimpleMatrixAf4x3
friend

Member Data Documentation

◆ _m

◆ CLIPSPACE2DTOIMAGESPACE

const Matrix4 Ogre::Matrix4::CLIPSPACE2DTOIMAGESPACE
static

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

◆ IDENTITY

const Matrix4 Ogre::Matrix4::IDENTITY
static

◆ m

◆ ZERO

const Matrix4 Ogre::Matrix4::ZERO
static

◆ ZEROAFFINE

const Matrix4 Ogre::Matrix4::ZEROAFFINE
static

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