Imath
<navlinks>
<page>

# Matrix44

    #include <Imath/ImathMatrix.h>

The `Matrix44` class template represents a 4x4 matrix, with predefined typedefs for `float` and `double`.

There are also various utility functions that operate on matrices defined in `ImathMatrixAlgo.h` and described in Matrix Functions.

Individual components of a matrix `M` may be referenced as either `M[j][i]` or `M.x[j][i]`. While the latter is a little awkward, it has an advantage when used in loops that may be auto-vectorized or explicitly vectorized by `#pragma omp simd` or other such hints, because the function call and pointer casting of `operator[]` can confuse the compiler just enough to prevent vectorization of the loop, whereas directly addressing the real underlying array (`M.x[j][i]`) does not.

Example:

    #include <Imath/ImathMatrix.h>
    #include <Imath/ImathMatrixAlgo.h>
    #include <cassert>

    void
    matrix44_example()
    {
        Imath::M44f M (Imath::UNINITIALIZED); // uninitialized

        M.makeIdentity();
        assert (M[0][0] == 1.0f);
        assert (M[0][1] == 0.0f);

        Imath::M44f Minv = M.inverse();

        Imath::M44f R;
        assert (R == Imath::identity44f);

        R.rotate (Imath::V3f (0.02f, M_PI/4, 0.0f));

        M = R * M;

        Imath::V3f v3 (1.0f, 0.0f, 0.0f);
        Imath::V4f v4 (1.0f, 0.0f, 0.0f, 1.0f);

        Imath::V3f r3 = v3 * M;
        assert (r3.equalWithAbsError (Imath::V3f (0.707107f, 0.0f, -0.7071070f), 1e-6f));

        Imath::V4f r4 = v4 * M;
        assert (r4.equalWithAbsError (Imath::V4f (0.707107f, 0.0f, -0.7071070f, 1.0f), 1e-6f));
    }

typedef Matrix44<float> Imath::M44f

  4x4 matrix of float

typedef Matrix44<double> Imath::M44d

  4x4 matrix of double

template<class T>
class Imath::Matrix44

  4x4 transformation matrix

  Direct access to elements

  T x[4][4]

    Matrix elements.

  Constructors and Assignment

  inline constexpr Matrix44(Uninitialized) noexcept

    Uninitialized.

  inline constexpr Matrix44() noexcept

    Default constructor: initialize to identity 1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1.

  inline constexpr Matrix44(T a) noexcept

    Initialize to scalar constant a a a a a a a a a a a a a a a a.

  inline constexpr Matrix44(const T a[4][4]) noexcept

    Construct from 4x4 array a[0][0] a[0][1] a[0][2] a[0][3] a[1][0] a[1][1] a[1][2] a[1][3] a[2][0] a[2][1] a[2][2] a[2][3] a[3][0] a[3][1] a[3][2] a[3][3].

  inline constexpr Matrix44(T a, T b, T c, T d, T e, T f, T g, T h, T i, T j, T k, T l, T m, T n, T o, T p) noexcept

    Construct from given scalar values a b c d e f g h i j k l m n o p.

  inline constexpr Matrix44(Matrix33<T> r, Vec3<T> t) noexcept

    Construct from a 3x3 rotation matrix and a translation vector r r r 0 r r r 0 r r r 0 t t t 1.

  inline constexpr Matrix44(const Matrix44 &v) noexcept

    Copy constructor.

  template<class S>
  inline explicit constexpr Matrix44(const Matrix44<S> &v) noexcept

    Construct from Matrix44 of another base type.

  inline constexpr const Matrix44 &operator=(const Matrix44 &v) noexcept

    Assignment operator.

  inline constexpr const Matrix44 &operator=(T a) noexcept

    Assignment from scalar.

  ~Matrix44() noexcept = default

    Destructor.

  Compatibility with Sb

  inline T *getValue() noexcept

    Return a raw pointer to the array of values.

  inline const T *getValue() const noexcept

    Return a raw pointer to the array of values.

  template<class S>
  inline void getValue(Matrix44<S> &v) const noexcept

    Return the value in `v`

  template<class S>
  constexpr Matrix44 &setValue(const Matrix44<S> &v) noexcept

    Set the value.

  template<class S>
  constexpr Matrix44 &setTheMatrix(const Matrix44<S> &v) noexcept

    Set the value.

  Arithmetic and Comparison

  inline constexpr bool operator==(const Matrix44 &v) const noexcept

    Equality.

  inline constexpr bool operator!=(const Matrix44 &v) const noexcept

    Inequality.

  inline constexpr bool equalWithAbsError(const Matrix44<T> &v, T e) const noexcept

    Compare two matrices and test if they are “approximately equal”:

    Returns:

      True if the coefficients of this and `m` are the same with an absolute error of no more than e, i.e., for all i, j:

          abs (this[i][j] - m[i][j]) <= e

  inline constexpr bool equalWithRelError(const Matrix44<T> &v, T e) const noexcept

    Compare two matrices and test if they are “approximately equal”:

    Returns:

      True if the coefficients of this and m are the same with a relative error of no more than e, i.e., for all i, j:

          abs (this[i] - v[i][j]) <= e * abs (this[i][j])

  inline constexpr const Matrix44 &operator+=(const Matrix44 &v) noexcept

    Component-wise addition.

  inline constexpr const Matrix44 &operator+=(T a) noexcept

    Component-wise addition.

  inline constexpr Matrix44 operator+(const Matrix44 &v) const noexcept

    Component-wise addition.

  inline constexpr const Matrix44 &operator-=(const Matrix44 &v) noexcept

    Component-wise subtraction.

  inline constexpr const Matrix44 &operator-=(T a) noexcept

    Component-wise subtraction.

  inline constexpr Matrix44 operator-(const Matrix44 &v) const noexcept

    Component-wise subtraction.

  inline constexpr Matrix44 operator-() const noexcept

    Component-wise multiplication by -1.

  inline constexpr const Matrix44 &negate() noexcept

    Component-wise multiplication by -1.

  inline constexpr const Matrix44 &operator*=(T a) noexcept

    Component-wise multiplication.

  inline constexpr Matrix44 operator*(T a) const noexcept

    Component-wise multiplication.

  inline constexpr const Matrix44 &operator/=(T a) noexcept

    Component-wise division.

  inline constexpr Matrix44 operator/(T a) const noexcept

    Component-wise division.

  inline constexpr const Matrix44 &operator*=(const Matrix44 &v) noexcept

    Matrix-matrix multiplication.

  inline constexpr Matrix44 operator*(const Matrix44 &v) const noexcept

    Matrix-matrix multiplication.

  template<class S>
  inline void multVecMatrix(const Vec3<S> &src, Vec3<S> &dst) const noexcept

    Vector-matrix multiplication: a homogeneous transformation by computing Vec3 (src.x, src.y, src.z, 1) * m and dividing by the result’s third element.

    Parameters:

      - src – [in] The input vector

      - dst – [out] The output vector

  template<class S>
  inline void multDirMatrix(const Vec3<S> &src, Vec3<S> &dst) const noexcept

    Vector-matrix multiplication: multiply `src` by the upper left 2x2 submatrix, ignoring the rest of matrix.

    Parameters:

      - src – [in] The input vector

      - dst – [out] The output vector

  static inline void multiply(const Matrix44 &a, const Matrix44 &b, Matrix44 &c) noexcept

    Matrix-matrix multiplication: compute c = a * b.

  static inline constexpr Matrix44 multiply(const Matrix44 &a, const Matrix44 &b) noexcept

    Matrix-matrix multiplication returning a result.

  Maniplation

  inline void makeIdentity() noexcept

    Set to the identity matrix.

  inline constexpr const Matrix44 &transpose() noexcept

    Transpose.

  inline constexpr Matrix44 transposed() const noexcept

    Return the transpose.

  inline constexpr const Matrix44 &invert(bool singExc)

    Invert in place using the determinant.

    Parameters:

      singExc – If true, throw an exception if the matrix cannot be inverted.

    Returns:

      const reference to this

  inline constexpr const Matrix44 &invert() noexcept

    Invert in place using the determinant.

    Returns:

      const reference to this

  inline constexpr Matrix44<T> inverse(bool singExc) const

    Return the inverse using the determinant, leaving this unmodified.

    Parameters:

      singExc – If true, throw an exception if the matrix cannot be inverted.

  inline constexpr Matrix44<T> inverse() const noexcept

    Return the inverse using the determinant, leaving this unmodified.

  inline constexpr const Matrix44 &gjInvert(bool singExc)

    Invert in place using the Gauss-Jordan method.

    Significantly slower but more accurate than invert().

    Parameters:

      singExc – If true, throw an exception if the matrix cannot be inverted.

    Returns:

      const reference to this

  inline constexpr const Matrix44 &gjInvert() noexcept

    Invert in place using the Gauss-Jordan method.

    Significantly slower but more accurate than invert().

    Returns:

      const reference to this

  inline Matrix44<T> gjInverse(bool singExc) const

    Return the inverse using the Gauss-Jordan method, leaving this unmodified.

    Significantly slower but more accurate than inverse().

  inline Matrix44<T> gjInverse() const noexcept

    Return the inverse using the Gauss-Jordan method, leaving this unmodified Significantly slower but more accurate than inverse().

  inline constexpr T minorOf(const int r, const int c) const noexcept

    Calculate the matrix minor of the (r,c) element.

  inline constexpr T fastMinor(const int r0, const int r1, const int r2, const int c0, const int c1, const int c2) const noexcept

    Build a minor using the specified rows and columns.

  inline constexpr T determinant() const noexcept

    Determinant.

  inline constexpr T trace() const noexcept

    Trace.

  template<class S>
  const Matrix44 &setEulerAngles(const Vec3<S> &r) noexcept

    Set matrix to rotation by XYZ euler angles (in radians)

    Returns:

      const referenced to this

  template<class S>
  constexpr const Matrix44 &setAxisAngle(const Vec3<S> &ax, S ang) noexcept

    Set matrix to rotation around given axis by given angle (in radians)

    Returns:

      const referenced to this

  template<class S>
  const Matrix44 &rotate(const Vec3<S> &r) noexcept

    Rotate the matrix by XYZ euler angles in r (in radians)

    Returns:

      const referenced to this

  inline constexpr const Matrix44 &setScale(T s) noexcept

    Set matrix to scale by given uniform factor.

    Returns:

      const referenced to this

  template<class S>
  constexpr const Matrix44 &setScale(const Vec3<S> &s) noexcept

    Set matrix to scale by given vector.

    Returns:

      const referenced to this

  template<class S>
  constexpr const Matrix44 &scale(const Vec3<S> &s) noexcept

    Scale the matrix by s.

    Returns:

      const referenced to this

  template<class S>
  constexpr const Matrix44 &setTranslation(const Vec3<S> &t) noexcept

    Set matrix to translation by given vector.

    Returns:

      const referenced to this

  inline constexpr const Vec3<T> translation() const noexcept

    Return translation component.

  template<class S>
  constexpr const Matrix44 &translate(const Vec3<S> &t) noexcept

    Translate the matrix by t.

    Returns:

      const referenced to this

  template<class S>
  constexpr const Matrix44 &setShear(const Vec3<S> &h) noexcept

    Set matrix to shear by given vector h.

    The resulting matrix

    - will shear x for each y coord. by a factor of h[0] ;

    - will shear x for each z coord. by a factor of h[1] ;

    - will shear y for each z coord. by a factor of h[2] .

    Returns:

      const referenced to this

  template<class S>
  constexpr const Matrix44 &setShear(const Shear6<S> &h) noexcept

    Set matrix to shear by given factors.

    The resulting matrix

    - will shear x for each y coord. by a factor of h.xy ;

    - will shear x for each z coord. by a factor of h.xz ;

    - will shear y for each z coord. by a factor of h.yz ;

    - will shear y for each x coord. by a factor of h.yx ;

    - will shear z for each x coord. by a factor of h.zx ;

    - will shear z for each y coord. by a factor of h.zy .

    Returns:

      const referenced to this

  template<class S>
  constexpr const Matrix44 &shear(const Vec3<S> &h) noexcept

    Shear the matrix by given vector.

    The composed matrix will be `shear` * `this`, where the shear matrix …

    - will shear x for each y coord. by a factor of h[0] ;

    - will shear x for each z coord. by a factor of h[1] ;

    - will shear y for each z coord. by a factor of h[2] .

    Returns:

      const referenced to this

  template<class S>
  constexpr const Matrix44 &shear(const Shear6<S> &h) noexcept

    Shear the matrix by the given factors.

    The composed matrix will be `shear` * `this`, where the shear matrix …

    - will shear x for each y coord. by a factor of h.xy ;

    - will shear x for each z coord. by a factor of h.xz ;

    - will shear y for each z coord. by a factor of h.yz ;

    - will shear y for each x coord. by a factor of h.yx ;

    - will shear z for each x coord. by a factor of h.zx ;

    - will shear z for each y coord. by a factor of h.zy .

    Returns:

      const referenced to this

  Numeric Limits

  static inline constexpr T baseTypeLowest() noexcept

    Largest possible negative value.

  static inline constexpr T baseTypeMax() noexcept

    Largest possible positive value.

  static inline constexpr T baseTypeSmallest() noexcept

    Smallest possible positive value.

  static inline constexpr T baseTypeEpsilon() noexcept

    Smallest possible e for which 1+e != 1.

  Public Types

  typedef T BaseType

    The base type: In templates that accept a parameter `V` (could be a Color4), you can refer to `T` as `V::BaseType`

  typedef Vec4<T> BaseVecType

    The base vector type.

  Public Functions

  inline T *operator[](int i) noexcept

    Row access.

  inline const T *operator[](int i) const noexcept

    Row access.

  template<class S>
  inline constexpr Matrix44<T> &setValue(const Matrix44<S> &v) noexcept
  template<class S>
  inline constexpr Matrix44<T> &setTheMatrix(const Matrix44<S> &v) noexcept
  template<class S>
  inline const Matrix44<T> &setEulerAngles(const Vec3<S> &r) noexcept
  template<class S>
  inline constexpr const Matrix44<T> &setAxisAngle(const Vec3<S> &axis, S angle) noexcept
  template<class S>
  inline const Matrix44<T> &rotate(const Vec3<S> &r) noexcept
  template<class S>
  inline constexpr const Matrix44<T> &setScale(const Vec3<S> &s) noexcept
  template<class S>
  inline constexpr const Matrix44<T> &scale(const Vec3<S> &s) noexcept
  template<class S>
  inline constexpr const Matrix44<T> &setTranslation(const Vec3<S> &t) noexcept
  template<class S>
  inline constexpr const Matrix44<T> &translate(const Vec3<S> &t) noexcept
  template<class S>
  inline constexpr const Matrix44<T> &setShear(const Vec3<S> &h) noexcept
  template<class S>
  inline constexpr const Matrix44<T> &setShear(const Shear6<S> &h) noexcept
  template<class S>
  inline constexpr const Matrix44<T> &shear(const Vec3<S> &h) noexcept
  template<class S>
  inline constexpr const Matrix44<T> &shear(const Shear6<S> &h) noexcept

  Public Static Functions

  static inline constexpr unsigned int dimensions() noexcept

    Return the number of the row and column dimensions, i.e. 4.

template<class T>
std::ostream &Imath::operator<<(std::ostream &s, const Matrix44<T> &m)

  Stream output, as:

      (m00 m01 m02 m03
       m10 m11 m12 m13
       m20 m21 m22 m23
       m30 m31 m32 m33)

</page>