template<class T>
Magnum::Math::Matrix4 class

3D transformation matrix

Template parameters
T Underlying data type

Contents

See Operations with matrices and vectors and 2D and 3D transformations for brief introduction.

Base classes

template<std::size_t size, class T>
class Matrix
Square matrix.

Public static functions

static auto translation(const Vector3<T>& vector) -> Matrix4<T> constexpr
3D translation matrix
static auto scaling(const Vector3<T>& vector) -> Matrix4<T> constexpr
3D scaling matrix
static auto rotation(Rad<T> angle, const Vector3<T>& normalizedAxis) -> Matrix4<T>
3D rotation matrix around arbitrary axis
static auto rotationX(Rad<T> angle) -> Matrix4<T>
3D rotation matrix around X axis
static auto rotationY(Rad<T> angle) -> Matrix4<T>
3D rotation matrix around Y axis
static auto rotationZ(Rad<T> angle) -> Matrix4<T>
3D rotation matrix around Z axis
static auto reflection(const Vector3<T>& normal) -> Matrix4<T>
3D reflection matrix
static auto shearingXY(T amountX, T amountY) -> Matrix4<T> constexpr
3D shearing matrix along XY plane
static auto shearingXZ(T amountX, T amountZ) -> Matrix4<T> constexpr
3D shearing matrix along XZ plane
static auto shearingYZ(T amountY, T amountZ) -> Matrix4<T> constexpr
3D shearing matrix along YZ plane
static auto orthographicProjection(const Vector2<T>& size, T near, T far) -> Matrix4<T>
3D orthographic projection matrix
static auto perspectiveProjection(const Vector2<T>& size, T near, T far) -> Matrix4<T>
3D perspective projection matrix
static auto perspectiveProjection(Rad<T> fov, T aspectRatio, T near, T far) -> Matrix4<T>
3D perspective projection matrix
static auto lookAt(const Vector3<T>& eye, const Vector3<T>& target, const Vector3<T>& up) -> Matrix4<T>
Matrix oriented towards a specific point.
static auto from(const Matrix3x3<T>& rotationScaling, const Vector3<T>& translation) -> Matrix4<T> constexpr
Create matrix from rotation/scaling part and translation part.

Constructors, destructors, conversion operators

Matrix4(IdentityInitT = IdentityInit, T value = T{1}) constexpr noexcept
Default constructor.
Matrix4(ZeroInitT) explicit constexpr noexcept
Construct zero-filled matrix.



Matrix4(NoInitT) explicit constexpr noexcept
Construct matrix without initializing the contents.



Matrix4(const Vector4<T>& first, const Vector4<T>& second, const Vector4<T>& third, const Vector4<T>& fourth) constexpr noexcept
Construct matrix from column vectors.
Matrix4(T value) explicit constexpr noexcept
Construct matrix with one value for all elements.
template<class U>
Matrix4(const RectangularMatrix<4, 4, U>& other) explicit constexpr noexcept
Construct matrix from another of different type.
template<class U, class V = decltype(Implementation::RectangularMatrixConverter<4, 4, T, U>::from(std::declval<U>()))>
Matrix4(const U& other) explicit constexpr
Construct matrix from external representation.
Matrix4(const RectangularMatrix<4, 4, T>& other) constexpr noexcept
Copy constructor.

Public functions

auto isRigidTransformation() const -> bool
Check whether the matrix represents rigid transformation.
auto rotationScaling() const -> Matrix3x3<T> constexpr
3D rotation and scaling part of the matrix
auto rotationNormalized() const -> Matrix3x3<T>
3D rotation part of the matrix assuming there is no scaling
auto rotation() const -> Matrix3x3<T>
3D rotation part of the matrix
auto uniformScalingSquared() const -> T
Uniform scaling part of the matrix, squared.
auto uniformScaling() const -> T
Uniform scaling part of the matrix.
auto right() -> Vector3<T>&
Right-pointing 3D vector.
auto right() const -> Vector3<T> constexpr
auto up() -> Vector3<T>&
Up-pointing 3D vector.
auto up() const -> Vector3<T> constexpr
auto backward() -> Vector3<T>&
Backward-pointing 3D vector.
auto backward() const -> Vector3<T> constexpr
auto translation() -> Vector3<T>&
3D translation part of the matrix
auto translation() const -> Vector3<T> constexpr
auto invertedRigid() const -> Matrix4<T>
Inverted rigid transformation matrix.
auto transformVector(const Vector3<T>& vector) const -> Vector3<T>
Transform 3D vector with the matrix.
auto transformPoint(const Vector3<T>& vector) const -> Vector3<T>
Transform 3D point with the matrix.

Function documentation

template<class T>
static Matrix4<T> Magnum::Math::Matrix4<T>::translation(const Vector3<T>& vector) constexpr

3D translation matrix

Parameters
vector Translation vector
\[ \boldsymbol{A} = \begin{pmatrix} 1 & 0 & 0 & v_x \\ 0 & 1 & 0 & v_y \\ 0 & 0 & 1 & v_z \\ 0 & 0 & 0 & 1 \end{pmatrix} \]

template<class T>
static Matrix4<T> Magnum::Math::Matrix4<T>::scaling(const Vector3<T>& vector) constexpr

3D scaling matrix

Parameters
vector Scaling vector
\[ \boldsymbol{A} = \begin{pmatrix} v_x & 0 & 0 & 0 \\ 0 & v_y & 0 & 0 \\ 0 & 0 & v_z & 0 \\ 0 & 0 & 0 & 1 \end{pmatrix} \]

template<class T>
static Matrix4<T> Magnum::Math::Matrix4<T>::rotation(Rad<T> angle, const Vector3<T>& normalizedAxis)

3D rotation matrix around arbitrary axis

Parameters
angle Rotation angle (counterclockwise)
normalizedAxis Normalized rotation axis

Expects that the rotation axis is normalized. If possible, use faster alternatives like rotationX(), rotationY() and rotationZ().

\[ \boldsymbol{A} = \begin{pmatrix} v_{x}v_{x}(1 - \cos\theta) + \cos\theta & v_{y}v_{x}(1 - \cos\theta) - v_{z}\sin \theta & v_{z}v_{x}(1 - \cos\theta) + v_{y}\sin\theta & 0 \\ v_{x}v_{y}(1 - \cos\theta) + v_{z}\sin\theta & v_{y}v_{y}(1 - \cos\theta) + \cos\theta & v_{z}v_{y}(1 - \cos\theta) - v_{x}\sin\theta & 0 \\ v_{x}v_{z}(1 - \cos\theta) - v_{y}\sin\theta & v_{y}v_{z}(1 - \cos\theta)+v_{x}\sin\theta & v_{z}v_{z}(1 - \cos\theta) + \cos\theta & 0 \\ 0 & 0 & 0 & 1 \end{pmatrix} \]

template<class T>
static Matrix4<T> Magnum::Math::Matrix4<T>::rotationX(Rad<T> angle)

3D rotation matrix around X axis

Parameters
angle Rotation angle (counterclockwise)

Faster than calling Matrix4::rotation(angle, Vector3::xAxis()).

\[ \boldsymbol{A} = \begin{pmatrix} 1 & 0 & 0 & 0 \\ 0 & \cos\theta & -\sin\theta & 0 \\ 0 & \sin\theta & \cos\theta & 0 \\ 0 & 0 & 0 & 1 \end{pmatrix} \]

template<class T>
static Matrix4<T> Magnum::Math::Matrix4<T>::rotationY(Rad<T> angle)

3D rotation matrix around Y axis

Parameters
angle Rotation angle (counterclockwise)

Faster than calling Matrix4::rotation(angle, Vector3::yAxis()).

\[ \boldsymbol{A} = \begin{pmatrix} \cos\theta & 0 & \sin\theta & 0 \\ 0 & 1 & 0 & 0 \\ -\sin\theta & 0 & \cos\theta & 0 \\ 0 & 0 & 0 & 1 \end{pmatrix} \]

template<class T>
static Matrix4<T> Magnum::Math::Matrix4<T>::rotationZ(Rad<T> angle)

3D rotation matrix around Z axis

Parameters
angle Rotation angle (counterclockwise)

Faster than calling Matrix4::rotation(angle, Vector3::zAxis()).

\[ \boldsymbol{A} = \begin{pmatrix} \cos\theta & -\sin\theta & 0 & 0 \\ \sin\theta & \cos\theta & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 1 \end{pmatrix} \]

template<class T>
static Matrix4<T> Magnum::Math::Matrix4<T>::reflection(const Vector3<T>& normal)

3D reflection matrix

Parameters
normal Normal of the plane through which to reflect

Expects that the normal is normalized. Reflection along axes can be done in a slightly simpler way also using scaling(), e.g. Matrix4::reflection(Vector3::yAxis()) is equivalent to Matrix4::scaling(Vector3::yScale(-1.0f)).

\[ \boldsymbol{A} = \boldsymbol{I} - 2 \boldsymbol{NN}^T ~~~~~ \boldsymbol{N} = \begin{pmatrix} n_x \\ n_y \\ n_z \end{pmatrix} \]

template<class T>
static Matrix4<T> Magnum::Math::Matrix4<T>::shearingXY(T amountX, T amountY) constexpr

3D shearing matrix along XY plane

Parameters
amountX Amount of shearing along X axis
amountY Amount of shearing along Y axis

Z axis remains unchanged.

\[ \boldsymbol{A} = \begin{pmatrix} 1 & 0 & v_x & 0 \\ 0 & 1 & v_y & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 1 \end{pmatrix} \]

template<class T>
static Matrix4<T> Magnum::Math::Matrix4<T>::shearingXZ(T amountX, T amountZ) constexpr

3D shearing matrix along XZ plane

Parameters
amountX Amount of shearing along X axis
amountZ Amount of shearing along Z axis

Y axis remains unchanged.

\[ \boldsymbol{A} = \begin{pmatrix} 1 & v_x & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & v_z & 1 & 0 \\ 0 & 0 & 0 & 1 \end{pmatrix} \]

template<class T>
static Matrix4<T> Magnum::Math::Matrix4<T>::shearingYZ(T amountY, T amountZ) constexpr

3D shearing matrix along YZ plane

Parameters
amountY Amount of shearing along Y axis
amountZ Amount of shearing along Z axis

X axis remains unchanged.

\[ \boldsymbol{A} = \begin{pmatrix} 1 & 0 & 0 & 0 \\ v_y & 1 & 0 & 0 \\ v_z & 0 & 1 & 0 \\ 0 & 0 & 0 & 1 \end{pmatrix} \]

template<class T>
static Matrix4<T> Magnum::Math::Matrix4<T>::orthographicProjection(const Vector2<T>& size, T near, T far)

3D orthographic projection matrix

Parameters
size Size of the view
near Distance to near clipping plane, positive is ahead
far Distance to far clipping plane, positive is ahead
\[ \boldsymbol{A} = \begin{pmatrix} \frac{2}{s_x} & 0 & 0 & 0 \\ 0 & \frac{2}{s_y} & 0 & 0 \\ 0 & 0 & \frac{2}{n - f} & \frac{2n}{n - f} - 1 \\ 0 & 0 & 0 & 1 \end{pmatrix} \]

template<class T>
static Matrix4<T> Magnum::Math::Matrix4<T>::perspectiveProjection(const Vector2<T>& size, T near, T far)

3D perspective projection matrix

Parameters
size Size of near clipping plane
near Distance to near clipping plane, positive is ahead
far Distance to far clipping plane, positive is ahead

If far is finite, the result is:

\[ \boldsymbol{A} = \begin{pmatrix} \frac{2n}{s_x} & 0 & 0 & 0 \\ 0 & \frac{2n}{s_y} & 0 & 0 \\ 0 & 0 & \frac{n + f}{n - f} & \frac{2nf}{n - f} \\ 0 & 0 & -1 & 0 \end{pmatrix} \]

For infinite far, the result is:

\[ \boldsymbol{A} = \begin{pmatrix} \frac{2n}{s_x} & 0 & 0 & 0 \\ 0 & \frac{2n}{s_y} & 0 & 0 \\ 0 & 0 & -1 & -2n \\ 0 & 0 & -1 & 0 \end{pmatrix} \]

template<class T>
static Matrix4<T> Magnum::Math::Matrix4<T>::perspectiveProjection(Rad<T> fov, T aspectRatio, T near, T far)

3D perspective projection matrix

Parameters
fov Field of view angle (horizontal)
aspectRatio Aspect ratio
near Near clipping plane
far Far clipping plane

If far is finite, the result is:

\[ \boldsymbol{A} = \begin{pmatrix} \frac{1}{\tan{\frac{\theta}{2}}} & 0 & 0 & 0 \\ 0 & \frac{a}{\tan{\frac{\theta}{2}}} & 0 & 0 \\ 0 & 0 & \frac{n + f}{n - f} & \frac{2nf}{n - f} \\ 0 & 0 & -1 & 0 \end{pmatrix} \]

For infinite far, the result is:

\[ \boldsymbol{A} = \begin{pmatrix} \frac{1}{\tan{\frac{\theta}{2}}} & 0 & 0 & 0 \\ 0 & \frac{a}{\tan{\frac{\theta}{2}}} & 0 & 0 \\ 0 & 0 & -1 & -2n \\ 0 & 0 & -1 & 0 \end{pmatrix} \]

template<class T>
static Matrix4<T> Magnum::Math::Matrix4<T>::lookAt(const Vector3<T>& eye, const Vector3<T>& target, const Vector3<T>& up)

Matrix oriented towards a specific point.

Parameters
eye Location to place the matrix
target Location towards which the matrix is oriented
up Vector as a guide of which way is up (should not be the same direction as target - eye)

template<class T>
static Matrix4<T> Magnum::Math::Matrix4<T>::from(const Matrix3x3<T>& rotationScaling, const Vector3<T>& translation) constexpr

Create matrix from rotation/scaling part and translation part.

Parameters
rotationScaling Rotation/scaling part (upper-left 3x3 matrix)
translation Translation part (first three elements of fourth column)

template<class T>
Magnum::Math::Matrix4<T>::Matrix4(IdentityInitT = IdentityInit, T value = T{1}) constexpr noexcept

Default constructor.

Creates identity matrix. value allows you to specify value on diagonal.

template<class T> template<class U>
Magnum::Math::Matrix4<T>::Matrix4(const RectangularMatrix<4, 4, U>& other) explicit constexpr noexcept

Construct matrix from another of different type.

Performs only default casting on the values, no rounding or anything else. Example usage:

Matrix2x2<Float> floatingPoint({1.3f, 2.7f},
                               {-15.0f, 7.0f});
Matrix2x2<Byte> integral(floatingPoint);
// integral == {{1, 2}, {-15, 7}}

template<class T>
bool Magnum::Math::Matrix4<T>::isRigidTransformation() const

Check whether the matrix represents rigid transformation.

Rigid transformation consists only of rotation and translation (i.e. no scaling or projection).

template<class T>
Matrix3x3<T> Magnum::Math::Matrix4<T>::rotationScaling() const constexpr

3D rotation and scaling part of the matrix

Upper-left 3x3 part of the matrix.

template<class T>
Matrix3x3<T> Magnum::Math::Matrix4<T>::rotationNormalized() const

3D rotation part of the matrix assuming there is no scaling

Similar to rotationScaling(), but additionally checks that the base vectors are normalized.

template<class T>
Matrix3x3<T> Magnum::Math::Matrix4<T>::rotation() const

3D rotation part of the matrix

Normalized upper-left 3x3 part of the matrix. Expects uniform scaling.

template<class T>
T Magnum::Math::Matrix4<T>::uniformScalingSquared() const

Uniform scaling part of the matrix, squared.

Squared length of vectors in upper-left 3x3 part of the matrix. Expects that the scaling is the same in all axes. Faster alternative to uniformScaling(), because it doesn't compute the square root.

template<class T>
T Magnum::Math::Matrix4<T>::uniformScaling() const

Uniform scaling part of the matrix.

Length of vectors in upper-left 3x3 part of the matrix. Expects that the scaling is the same in all axes. Use faster alternative uniformScalingSquared() where possible.

template<class T>
Vector3<T>& Magnum::Math::Matrix4<T>::right()

Right-pointing 3D vector.

First three elements of first column.

template<class T>
Vector3<T> Magnum::Math::Matrix4<T>::right() const constexpr

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<class T>
Vector3<T>& Magnum::Math::Matrix4<T>::up()

Up-pointing 3D vector.

First three elements of second column.

template<class T>
Vector3<T> Magnum::Math::Matrix4<T>::up() const constexpr

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<class T>
Vector3<T>& Magnum::Math::Matrix4<T>::backward()

Backward-pointing 3D vector.

First three elements of third column.

template<class T>
Vector3<T> Magnum::Math::Matrix4<T>::backward() const constexpr

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<class T>
Vector3<T>& Magnum::Math::Matrix4<T>::translation()

3D translation part of the matrix

First three elements of fourth column.

template<class T>
Vector3<T> Magnum::Math::Matrix4<T>::translation() const constexpr

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<class T>
Matrix4<T> Magnum::Math::Matrix4<T>::invertedRigid() const

Inverted rigid transformation matrix.

Expects that the matrix represents rigid transformation. Significantly faster than the general algorithm in inverted().

\[ A^{-1} = \begin{pmatrix} (A^{3,3})^T & (A^{3,3})^T \begin{pmatrix} a_{3,0} \\ a_{3,1} \\ a_{3,2} \\ \end{pmatrix} \\ \begin{array}{ccc} 0 & 0 & 0 \end{array} & 1 \end{pmatrix} \]

$ A^{i, j} $ is matrix without i-th row and j-th column, see ij()

template<class T>
Vector3<T> Magnum::Math::Matrix4<T>::transformVector(const Vector3<T>& vector) const

Transform 3D vector with the matrix.

Unlike in transformVector(), translation is not involved in the transformation.

\[ \boldsymbol v' = \boldsymbol M \begin{pmatrix} v_x \\ v_y \\ v_z \\ 0 \end{pmatrix} \]

template<class T>
Vector3<T> Magnum::Math::Matrix4<T>::transformPoint(const Vector3<T>& vector) const

Transform 3D point with the matrix.

Unlike in transformVector(), translation is also involved in the transformation.

\[ \boldsymbol v' = \boldsymbol v''_{xyz} / v''_w ~~~~~~~~~~ \boldsymbol v'' = \begin{pmatrix} v''_x \\ v''_y \\ v''_z \\ v''_w \end{pmatrix} = \boldsymbol M \begin{pmatrix} v_x \\ v_y \\ v_z \\ 1 \end{pmatrix} \\ \]