Skip to main content

mat4 Struct Template

Represents a 4x4 matrix, stored in column-major order. More...

Declaration

template <helios::math::concepts::IsNumeric T> struct helios::math::mat4<T> { ... }

Public Constructors Index

template <helios::math::concepts::IsNumeric T>
constexprmat4 () noexcept

Default constructor. Initializes all components to 0. More...

template <helios::math::concepts::IsNumeric T>
constexprmat4 (const T f) noexcept

Creates a diagonal matrix. The diagonal components are initialized with the value f. More...

template <helios::math::concepts::IsNumeric T>
constexprmat4 (const vec3< T > f) noexcept

Creates a diagonal matrix with the components of vec3<T> as the diagonal elements. Element at [4, 4] is set to 1. More...

template <helios::math::concepts::IsNumeric T>
constexprmat4 (const T f0_0, const T f1_0, const T f2_0, const T f3_0, const T f0_1, const T f1_1, const T f2_1, const T f3_1, const T f0_2, const T f1_2, const T f2_2, const T f3_2, const T f0_3, const T f1_3, const T f2_3, const T f3_3)

Constructs a new mat4 with all 16 components explicitly specified. More...

Public Operators Index

template <helios::math::concepts::IsNumeric T>
constexpr const T &operator() (const size_t row, const size_t col) const

Provides read-only access to a matrix component. More...

template <helios::math::concepts::IsNumeric T>
constexpr T &operator() (const size_t row, const size_t col)

Provides read-write access to a matrix component. More...

template <helios::math::concepts::IsNumeric T>
constexpr booloperator== (const mat4< T > &rgt) const

Strictly compares the elements of this matrix with the elements of the rgt matrix. More...

template <helios::math::concepts::IsNumeric T>
auto operator* (const mat4< T > &m) const -> constexpr mat4< T >

Performs matrix-multiplication with another mat4. This matrix is the left operand, while m is the right operand. More...

template <helios::math::concepts::IsNumeric T>
auto operator* (const vec4< T > &v) const -> constexpr vec4< T >

Performs matrix-vector-multiplication with a vec4<T> v. More...

Public Member Functions Index

template <helios::math::concepts::IsNumeric T>
constexpr boolsame (const mat4< T > &rgt) const

Compares this matrix element's with the rgt matrix considering an epsilon value. Returns true if for all elements the equation |a-b| <= EPSILON holds. More...

template <helios::math::concepts::IsNumeric T>
auto transpose () const noexcept -> helios::math::mat4< T >

Computes the transpose of a 4x4 matrix. More...

template <helios::math::concepts::IsNumeric T>
auto column (unsigned int i) const noexcept -> helios::math::vec4< T >

Returns the i-th column of the matrix. More...

template <helios::math::concepts::IsNumeric T>
auto inverse () const noexcept -> constexpr helios::math::mat4< T >

Computes the inverse of the matrix. More...

template <helios::math::concepts::IsNumeric T>
auto translation () const noexcept -> helios::math::vec3< T >

Extracts the translation component from this matrix. More...

template <helios::math::concepts::IsNumeric T>
auto withTranslation (helios::math::vec3< T > v) const noexcept -> helios::math::mat4< T >

Creates a new matrix with the specified translation, preserving other components. More...

template <helios::math::concepts::IsNumeric T>
auto withScaling (helios::math::vec3< T > v) const noexcept -> helios::math::mat4< T >

Returns a new 4x4 matrix derived by applying a scaling transformation. More...

template <helios::math::concepts::IsNumeric T>
auto withTranslation (helios::math::vec4< T > v) const noexcept -> helios::math::mat4< T >

Creates a new matrix with the specified translation, preserving other components. More...

template <helios::math::concepts::IsNumeric T>
auto decompose (const helios::math::TransformType type) const noexcept -> helios::math::mat4< T >

Decomposes this matrix, extracting only specified components. More...

Private Member Attributes Index

template <helios::math::concepts::IsNumeric T>
Tm[16]

Internal array storing matrix components. More...

Public Static Functions Index

template <helios::math::concepts::IsNumeric T>
static auto identity () noexcept -> mat4< T >

Convenient method to construct a 4x4 identity matrix. More...

Description

Represents a 4x4 matrix, stored in column-major order.

The mat4 struct provides a lightweight and efficient way to handle 4D matrix mathematics for numeric data types. It stores its components as type T. For convenient access, type aliases mat4f, mat4d and mat4i are available, providing float/double/integer matrix representatives.

Template Parameters
T

the numeric type of the matrix components.

Definition at line 38 of file mat4.ixx.

Public Constructors

mat4()

template <helios::math::concepts::IsNumeric T>
constexpr helios::math::mat4< T >::mat4 ()
inline explicit constexpr noexcept

Default constructor. Initializes all components to 0.

Definition at line 52 of file mat4.ixx.

52 explicit constexpr mat4() noexcept : m{} {};

mat4()

template <helios::math::concepts::IsNumeric T>
constexpr helios::math::mat4< T >::mat4 (const T f)
inline explicit constexpr noexcept

Creates a diagonal matrix. The diagonal components are initialized with the value f.

Parameters
f

The scalar value for the diagonal components.

Definition at line 60 of file mat4.ixx.

60 explicit constexpr mat4(const T f) noexcept
61 : m{ f, T{}, T{}, T{},
62 T{}, f, T{}, T{},
63 T{}, T{}, f, T{},
64 T{}, T{}, T{}, f} {}

mat4()

template <helios::math::concepts::IsNumeric T>
constexpr helios::math::mat4< T >::mat4 (const vec3< T > f)
inline explicit constexpr noexcept

Creates a diagonal matrix with the components of vec3<T> as the diagonal elements. Element at [4, 4] is set to 1.

Parameters
f

The vector containing the diagonal components.

Definition at line 72 of file mat4.ixx.

72 explicit constexpr mat4(const vec3<T> f) noexcept
73 : m{ f[0], T{}, T{}, T{},
74 T{}, f[1], T{}, T{},
75 T{}, T{}, f[2], T{},
76 T{}, T{}, T{}, static_cast<T>(1)} {}

mat4()

template <helios::math::concepts::IsNumeric T>
constexpr helios::math::mat4< T >::mat4 (const T f0_0, const T f1_0, const T f2_0, const T f3_0, const T f0_1, const T f1_1, const T f2_1, const T f3_1, const T f0_2, const T f1_2, const T f2_2, const T f3_2, const T f0_3, const T f1_3, const T f2_3, const T f3_3)
inline constexpr

Constructs a new mat4 with all 16 components explicitly specified.

The values are stored in column major order, that is, the first 4 arguments represent the first column, and so on.

Parameter naming convention: fR_C where R is the row index and C is the column index.

Definition at line 86 of file mat4.ixx.

86 constexpr mat4(
87 const T f0_0, const T f1_0, const T f2_0, const T f3_0,
88 const T f0_1, const T f1_1, const T f2_1, const T f3_1,
89 const T f0_2, const T f1_2, const T f2_2, const T f3_2,
90 const T f0_3, const T f1_3, const T f2_3, const T f3_3
91 ) : m{
96 } { }

Public Operators

operator()()

template <helios::math::concepts::IsNumeric T>
constexpr const T & helios::math::mat4< T >::operator() (const size_t row, const size_t col)
inline constexpr

Provides read-only access to a matrix component.

Elements are accessed in column major order: m[row + col * 4], while the specified indices represent an usual mxn-matrix access, i.e. for a given 2x4-matrix [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]

a call to row(0, 2) returns "2", while the matrix is internally stored as (1, 4, 8, 12, 1, 5, 9, 13, 2, 6, 10, 14, 3, 7, 11, 15).

Bounds checking is performed via assert in debug builds.

Parameters
row

The zero based row index.

col

The zero based col index.

Returns

A const ref to the component at the specified position.

Definition at line 132 of file mat4.ixx.

132 constexpr const T& operator()(const size_t row, const size_t col) const {
133 assert(row < 4 && col < 4 && "mat4 - Index out of bounds.");
134 return m[row + col * 4];
135 }

operator()()

template <helios::math::concepts::IsNumeric T>
constexpr T & helios::math::mat4< T >::operator() (const size_t row, const size_t col)
inline constexpr

Provides read-write access to a matrix component.

Elements are accessed in column major order: m[row + col * 4], while the specified indices represent an usual mxn-matrix access, i.e. for a given 2x4-matrix [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]

a call to row(0, 2) returns "2", while the matrix is internally stored as (0, 4, 8, 12, 1, 5, 9, 13, 2, 6, 10, 14, 3, 7, 11, 15).

Bounds checking is performed via assert in debug builds.

Parameters
row

The zero based row index.

col

The zero based col index.

Returns

A ref to the component at the specified position.

Definition at line 159 of file mat4.ixx.

159 constexpr T& operator()(const size_t row, const size_t col) {
160 assert(row < 4 && col < 4 && "mat4 - Index out of bounds.");
161 return m[row + col * 4];
162 }

operator*()

template <helios::math::concepts::IsNumeric T>
constexpr mat4< T > helios::math::mat4< T >::operator* (const mat4< T > & m)
inline constexpr

Performs matrix-multiplication with another mat4. This matrix is the left operand, while m is the right operand.

Parameters
m

The right-hand side mat4<T> for multiplication.

Returns

A new mat4<T>, representing the result of the matrix-multiplication.

Definition at line 231 of file mat4.ixx.

231 constexpr mat4<T> operator*(const mat4<T>& m) const {
232 mat4<T> A{};
233 for (int row = 0; row < 4; row++) {
234 for (int col = 0; col < 4; col++) {
235 T sum = T{};
236 sum += (*this)(row, 0) * m(0, col);
237 sum += (*this)(row, 1) * m(1, col);
238 sum += (*this)(row, 2) * m(2, col);
239 sum += (*this)(row, 3) * m(3, col);
240 A(row, col) = sum;
241 }
242 }
243
244 return A;
245 }

operator*()

template <helios::math::concepts::IsNumeric T>
constexpr vec4< T > helios::math::mat4< T >::operator* (const vec4< T > & v)
inline constexpr

Performs matrix-vector-multiplication with a vec4<T> v.

This matrix is the left operand, while v is the right operand.

Parameters
v

The right-hand side vec4<T> for multiplication.

Returns

A new vec4<T>, representing the result of the matrix-vector-multiplication.

Definition at line 257 of file mat4.ixx.

257 constexpr vec4<T> operator*(const vec4<T>& v) const {
258 const auto m = *this;
259 return vec4<T>{
260 m(0, 0) * v[0] + m(0, 1) * v[1] + m(0, 2) * v[2] + m(0, 3) * v[3],
261 m(1, 0) * v[0] + m(1, 1) * v[1] + m(1, 2) * v[2] + m(1, 3) * v[3],
262 m(2, 0) * v[0] + m(2, 1) * v[1] + m(2, 2) * v[2] + m(2, 3) * v[3],
263 m(3, 0) * v[0] + m(3, 1) * v[1] + m(3, 2) * v[2] + m(3, 3) * v[3]
264 };
265 }

operator==()

template <helios::math::concepts::IsNumeric T>
constexpr bool helios::math::mat4< T >::operator== (const mat4< T > & rgt)
inline constexpr

Strictly compares the elements of this matrix with the elements of the rgt matrix.

Parameters
rgt

The right matrix to compare for equal values

Returns

True if all elements are equal (==), false otherwise.

Definition at line 208 of file mat4.ixx.

208 constexpr bool operator==(const mat4<T>& rgt) const {
209
210 const auto* leftPtr = value_ptr(*this);
211 const auto* rgtPtr = value_ptr(rgt);
212
213 for (int i = 0; i < 16; i++) {
214 if (leftPtr[i] != rgtPtr[i]) {
215 return false;
216 }
217 }
218
219 return true;
220 }

Reference helios::math::value_ptr.

Public Member Functions

column()

template <helios::math::concepts::IsNumeric T>
helios::math::vec4< T > helios::math::mat4< T >::column (unsigned int i)
inline noexcept

Returns the i-th column of the matrix.

Parameters
i

The zero-based index of the column (0-3).

Returns

A vec4<T> representing the column.

Definition at line 295 of file mat4.ixx.

295 helios::math::vec4<T> column(unsigned int i) const noexcept {
296 assert(i <= 3 && "unexpected value for column");
297 const auto m = *this;
299 m(0, i), m(1, i), m(2, i), m(3, i)
300 };
301 }

Referenced by helios::math::mat4< T >::inverse.

decompose()

template <helios::math::concepts::IsNumeric T>
helios::math::mat4< T > helios::math::mat4< T >::decompose (const helios::math::TransformType type)
inline noexcept

Decomposes this matrix, extracting only specified components.

This function extracts Translation, Rotation, and/or Scale components from this 4x4 matrix based on the provided TransformType mask. Components not included in the mask are replaced with identity values.

The decomposition supports the following cases:

info

For combined Rotation + Scale without Translation, the upper-left 3x3 is copied directly. For Rotation-only, scale is removed by normalizing columns.

Template Parameters
T

The numeric type of the matrix elements.

Parameters
type

Bitmask specifying which components to extract.

Returns

A new matrix containing only the requested transform components.

See Also

helios::math::TransformType

See Also

helios::math::transformTypeMatch()

Definition at line 451 of file mat4.ixx.

452 const auto m = *this;
454 return m;
455 }
456
457 auto id = identity();
459 id(0, 3) = m(0, 3);
460 id(1, 3) = m(1, 3);
461 id(2, 3) = m(2, 3);
462 }
463
466 id(0, 0) = m(0, 0); id(0, 1) = m(0, 1); id(0, 2) = m(0, 2);
467 id(1, 0) = m(1, 0); id(1, 1) = m(1, 1); id(1, 2) = m(1, 2);
468 id(2, 0) = m(2, 0); id(2, 1) = m(2, 1); id(2, 2) = m(2, 2);
469 } else {
470
471 const auto bx = vec3<T>(m(0, 0), m(1, 0), m(2, 0));
472 const auto by = vec3<T>(m(0, 1), m(1, 1), m(2, 1));
473 const auto bz = vec3<T>(m(0, 2), m(1, 2), m(2, 2));
474
475 const auto sx = bx.length();
476 const auto sy = by.length();
477 const auto sz = bz.length();
478
480 vec3<T> rx = sx != 0 ? bx/sx : vec3<T>{1, 0, 0};
481 vec3<T> ry = sy != 0 ? by/sy : vec3<T>{0, 1, 0};
482 vec3<T> rz = sz != 0 ? bz/sz : vec3<T>{0, 0, 1};
483
484 id(0, 0) = rx[0]; id(0, 1) = ry[0]; id(0, 2) = rz[0];
485 id(1, 0) = rx[1]; id(1, 1) = ry[1]; id(1, 2) = rz[1];
486 id(2, 0) = rx[2]; id(2, 1) = ry[2]; id(2, 2) = rz[2];
488 id(0, 0) = sx;
489 id(1, 1) = sy;
490 id(2, 2) = sz;
491 }
492 }
493
494 return id;
495 }

References helios::math::All, helios::math::mat4< T >::identity, helios::math::Rotation, helios::math::Scale, helios::math::transformTypeMatch and helios::math::Translation.

inverse()

template <helios::math::concepts::IsNumeric T>
constexpr helios::math::mat4< T > helios::math::mat4< T >::inverse ()
inline constexpr noexcept

Computes the inverse of the matrix.

Returns

The inverse matrix.

See Also

[Len16, Listing 1.11, 44]

Definition at line 310 of file mat4.ixx.

311 const auto m = *this;
312
313 const auto a = column(0).toVec3();
314 const auto b = column(1).toVec3();
315 const auto c = column(2).toVec3();
316 const auto d = column(3).toVec3();
317
318 const T x = m(3, 0);
319 const T y = m(3, 1);
320 const T z = m(3, 2);
321 const T w = m(3, 3);
322
323 auto s = helios::math::cross(a, b);
324 auto t = helios::math::cross(c, d);
325 auto u = a*y - b*x;
326 auto v = c*w - d*z;
327
328 T invDet = static_cast<T>(1) / (helios::math::dot(s, v) + helios::math::dot(t, u));
329
330 s = s * invDet;
331 t = t * invDet;
332 u = u * invDet;
333 v = v * invDet;
334
335 auto r0 = (helios::math::cross(b, v)) + t*y;
336 auto r1 = (helios::math::cross(v, a)) - t*x;
337 auto r2 = (helios::math::cross(d, u)) + s*w;
338 auto r3 = (helios::math::cross(u, c)) - s*z;
339
341 r0[0], r0[1], r0[2], -helios::math::dot(b, t),
342 r1[0], r1[1], r1[2], helios::math::dot(a, t),
343 r2[0], r2[1], r2[2], -helios::math::dot(d, s),
344 r3[0], r3[1], r3[2], helios::math::dot(c, s)
345 };
346 }

References helios::math::mat4< T >::column, helios::math::cross and helios::math::dot.

same()

template <helios::math::concepts::IsNumeric T>
constexpr bool helios::math::mat4< T >::same (const mat4< T > & rgt)
inline constexpr

Compares this matrix element's with the rgt matrix considering an epsilon value. Returns true if for all elements the equation |a-b| <= EPSILON holds.

EPSILON is set to 0.00001

Parameters
rgt

The other matix to compare with this matrix for equality.

Returns

True is the elements of the matrices are considered equal, otherwise false.

See Also

https://realtimecollisiondetection.net/blog/?p=89

Definition at line 183 of file mat4.ixx.

183 constexpr bool same(const mat4<T>& rgt) const {
184
185 static const T EPSILON = static_cast<T>(0.00001);
186
187 const auto* leftPtr = value_ptr(*this);
188 const auto* rgtPtr = value_ptr(rgt);
189
190 for (int i = 0; i < 16; i++) {
191 if (std::fabs(leftPtr[i] - rgtPtr[i]) > EPSILON) {
192 return false;
193 }
194 }
195
196 return true;
197 }

Reference helios::math::value_ptr.

translation()

template <helios::math::concepts::IsNumeric T>
helios::math::vec3< T > helios::math::mat4< T >::translation ()
inline noexcept

Extracts the translation component from this matrix.

Returns the translation vector stored in column 3 (elements [0,3], [1,3], [2,3]). This represents the position offset in a standard TRS (Translation-Rotation-Scale) matrix.

Returns

A vec3<T> containing the x, y, z translation components.

Definition at line 356 of file mat4.ixx.

357 const auto m = *this;
359 m(0, 3), m(1, 3), m(2, 3)
360 };
361 }

transpose()

template <helios::math::concepts::IsNumeric T>
helios::math::mat4< T > helios::math::mat4< T >::transpose ()
inline noexcept

Computes the transpose of a 4x4 matrix.

This function swaps rows and columns: M^T_{ij} = M_{ji}

info

This is not a general-purpose inverse function. For matrices containing non-uniform scale or shear, use a full inverse calculation instead.

Template Parameters
T

The numeric type of the matrix elements.

Returns

The transposed matrix.

Definition at line 279 of file mat4.ixx.

280 const auto m = *this;
282 m(0, 0), m(0, 1), m(0, 2), m(0, 3),
283 m(1, 0), m(1, 1), m(1, 2), m(1, 3),
284 m(2, 0), m(2, 1), m(2, 2), m(2, 3),
285 m(3, 0), m(3, 1), m(3, 2), m(3, 3)
286 };
287 }

withScaling()

template <helios::math::concepts::IsNumeric T>
helios::math::mat4< T > helios::math::mat4< T >::withScaling (helios::math::vec3< T > v)
inline noexcept

Returns a new 4x4 matrix derived by applying a scaling transformation.

This function scales the current matrix by modifying specific components based on the scaling factors provided in the input vector.

Template Parameters
T

The numeric type used for the matrix and vector components.

Parameters
v

A 3D vector representing the scaling factors along the x, y, and z axes.

Returns

A new 4x4 matrix with the scaling transformation applied.

info

The operation maintains column-major order for the matrix components.

Definition at line 394 of file mat4.ixx.

395 const auto m = *this;
397 m(0, 0) * v[0], m(1, 0) * v[0], m(2, 0) * v[0], m(3, 0) * v[0],
398 m(0, 1) * v[1], m(1, 1) * v[1], m(2, 1) * v[1], m(3, 1) * v[1],
399 m(0, 2) * v[2], m(1, 2) * v[2], m(2, 2) * v[2], m(3, 2) * v[2],
400 m(0, 3), m(1, 3), m(2, 3), m(3, 3),
401 };
402 }

withTranslation()

template <helios::math::concepts::IsNumeric T>
helios::math::mat4< T > helios::math::mat4< T >::withTranslation (helios::math::vec3< T > v)
inline noexcept

Creates a new matrix with the specified translation, preserving other components.

Returns a copy of this matrix with column 3 (translation) replaced by the given vector. The w-component [3,3] is set to 1.0 for homogeneous coordinates.

Parameters
v

The new translation vector (x, y, z).

Returns

A new mat4<T> with the updated translation component.

Definition at line 373 of file mat4.ixx.

374 const auto m = *this;
376 m(0, 0), m(1, 0), m(2, 0), m(3, 0),
377 m(0, 1), m(1, 1), m(2, 1), m(3, 1),
378 m(0, 2), m(1, 2), m(2, 2), m(3, 2),
379 v[0], v[1], v[2], static_cast<T>(1)
380 };
381 }

withTranslation()

template <helios::math::concepts::IsNumeric T>
helios::math::mat4< T > helios::math::mat4< T >::withTranslation (helios::math::vec4< T > v)
inline noexcept

Creates a new matrix with the specified translation, preserving other components.

Overload accepting a vec4. Only the xyz components are used; the w component is ignored and set to 1.0 in the resulting matrix.

Parameters
v

The new translation vector (x, y, z, w). The w component is ignored.

Returns

A new mat4<T> with the updated translation component.

Definition at line 415 of file mat4.ixx.

416 const auto m = *this;
418 m(0, 0), m(1, 0), m(2, 0), m(3, 0),
419 m(0, 1), m(1, 1), m(2, 1), m(3, 1),
420 m(0, 2), m(1, 2), m(2, 2), m(3, 2),
421 v[0], v[1], v[2], static_cast<T>(1)
422 };
423 }

Private Member Attributes

m

template <helios::math::concepts::IsNumeric T>
T helios::math::mat4< T >::m[16]

Internal array storing matrix components.

Components are stored in column-major order, that is, each 4 subsequent elements represent a matrix column.

Definition at line 46 of file mat4.ixx.

46 T m[16];

Public Static Functions

identity()

template <helios::math::concepts::IsNumeric T>
mat4< T > helios::math::mat4< T >::identity ()
inline noexcept static

Convenient method to construct a 4x4 identity matrix.

Template Parameters
T

The numeric type of the matrix components.

Returns

A new mat4<T>-identity matrix-

Definition at line 106 of file mat4.ixx.

107 return mat4<T>(1);
108 }

Referenced by helios::math::mat4< T >::decompose.


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


Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.9.8.