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...

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

Performs matrix-scalar-multiplication with a 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{
92 f0_0, f1_0, f2_0, f3_0,
93 f0_1, f1_1, f2_1, f3_1,
94 f0_2, f1_2, f2_2, f3_2,
95 f0_3, f1_3, f2_3, f3_3
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 228 of file mat4.ixx.

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

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 254 of file mat4.ixx.

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

operator*()

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

Performs matrix-scalar-multiplication with a T v.

Parameters
v

The value used for scaling each matrix component.

Returns

A new mat4<T>, where each component is scaled by v.

Definition at line 272 of file mat4.ixx.

272 constexpr mat4<T> operator*(const T v) const {
273 const auto m = *this;
274 return mat4<T>{
275 m(0, 0) * v, m(0, 1) * v, m(0, 2) * v, m(0, 3) * v,
276 m(1, 0) * v, m(1, 1) * v, m(1, 2) * v, m(1, 3) * v,
277 m(2, 0) * v, m(2, 1) * v, m(2, 2) * v, m(2, 3) * v,
278 m(3, 0) * v, m(3, 1) * v, m(3, 2) * v, m(3, 3) * v
279 };
280 }

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 205 of file mat4.ixx.

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

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 310 of file mat4.ixx.

310 helios::math::vec4<T> column(unsigned int i) const noexcept {
311 assert(i <= 3 && "unexpected value for column");
312 const auto m = *this;
314 m(0, i), m(1, i), m(2, i), m(3, i)
315 };
316 }

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 466 of file mat4.ixx.

467 const auto m = *this;
469 return m;
470 }
471
472 auto id = identity();
474 id(0, 3) = m(0, 3);
475 id(1, 3) = m(1, 3);
476 id(2, 3) = m(2, 3);
477 }
478
481 id(0, 0) = m(0, 0); id(0, 1) = m(0, 1); id(0, 2) = m(0, 2);
482 id(1, 0) = m(1, 0); id(1, 1) = m(1, 1); id(1, 2) = m(1, 2);
483 id(2, 0) = m(2, 0); id(2, 1) = m(2, 1); id(2, 2) = m(2, 2);
484 } else {
485
486 const auto bx = vec3<T>(m(0, 0), m(1, 0), m(2, 0));
487 const auto by = vec3<T>(m(0, 1), m(1, 1), m(2, 1));
488 const auto bz = vec3<T>(m(0, 2), m(1, 2), m(2, 2));
489
490 const auto sx = bx.length();
491 const auto sy = by.length();
492 const auto sz = bz.length();
493
495 vec3<T> rx = sx != 0 ? bx/sx : vec3<T>{1, 0, 0};
496 vec3<T> ry = sy != 0 ? by/sy : vec3<T>{0, 1, 0};
497 vec3<T> rz = sz != 0 ? bz/sz : vec3<T>{0, 0, 1};
498
499 id(0, 0) = rx[0]; id(0, 1) = ry[0]; id(0, 2) = rz[0];
500 id(1, 0) = rx[1]; id(1, 1) = ry[1]; id(1, 2) = rz[1];
501 id(2, 0) = rx[2]; id(2, 1) = ry[2]; id(2, 2) = rz[2];
503 id(0, 0) = sx;
504 id(1, 1) = sy;
505 id(2, 2) = sz;
506 }
507 }
508
509 return id;
510 }

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 325 of file mat4.ixx.

325 constexpr helios::math::mat4<T> inverse() const noexcept {
326 const auto m = *this;
327
328 const auto a = column(0).toVec3();
329 const auto b = column(1).toVec3();
330 const auto c = column(2).toVec3();
331 const auto d = column(3).toVec3();
332
333 const T x = m(3, 0);
334 const T y = m(3, 1);
335 const T z = m(3, 2);
336 const T w = m(3, 3);
337
338 auto s = helios::math::cross(a, b);
339 auto t = helios::math::cross(c, d);
340 auto u = a*y - b*x;
341 auto v = c*w - d*z;
342
343 T invDet = static_cast<T>(1) / (helios::math::dot(s, v) + helios::math::dot(t, u));
344
345 s = s * invDet;
346 t = t * invDet;
347 u = u * invDet;
348 v = v * invDet;
349
350 auto r0 = (helios::math::cross(b, v)) + t*y;
351 auto r1 = (helios::math::cross(v, a)) - t*x;
352 auto r2 = (helios::math::cross(d, u)) + s*w;
353 auto r3 = (helios::math::cross(u, c)) - s*z;
354
356 r0[0], r0[1], r0[2], -helios::math::dot(b, t),
357 r1[0], r1[1], r1[2], helios::math::dot(a, t),
358 r2[0], r2[1], r2[2], -helios::math::dot(d, s),
359 r3[0], r3[1], r3[2], helios::math::dot(c, s)
360 };
361 }

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 180 of file mat4.ixx.

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

References helios::math::EPSILON_LENGTH and 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 371 of file mat4.ixx.

372 const auto m = *this;
374 m(0, 3), m(1, 3), m(2, 3)
375 };
376 }

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 294 of file mat4.ixx.

295 const auto m = *this;
297 m(0, 0), m(0, 1), m(0, 2), m(0, 3),
298 m(1, 0), m(1, 1), m(1, 2), m(1, 3),
299 m(2, 0), m(2, 1), m(2, 2), m(2, 3),
300 m(3, 0), m(3, 1), m(3, 2), m(3, 3)
301 };
302 }

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 409 of file mat4.ixx.

410 const auto m = *this;
412 m(0, 0) * v[0], m(1, 0) * v[0], m(2, 0) * v[0], m(3, 0) * v[0],
413 m(0, 1) * v[1], m(1, 1) * v[1], m(2, 1) * v[1], m(3, 1) * v[1],
414 m(0, 2) * v[2], m(1, 2) * v[2], m(2, 2) * v[2], m(3, 2) * v[2],
415 m(0, 3), m(1, 3), m(2, 3), m(3, 3),
416 };
417 }

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 388 of file mat4.ixx.

389 const auto m = *this;
391 m(0, 0), m(1, 0), m(2, 0), m(3, 0),
392 m(0, 1), m(1, 1), m(2, 1), m(3, 1),
393 m(0, 2), m(1, 2), m(2, 2), m(3, 2),
394 v[0], v[1], v[2], static_cast<T>(1)
395 };
396 }

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 430 of file mat4.ixx.

431 const auto m = *this;
433 m(0, 0), m(1, 0), m(2, 0), m(3, 0),
434 m(0, 1), m(1, 1), m(2, 1), m(3, 1),
435 m(0, 2), m(1, 2), m(2, 2), m(3, 2),
436 v[0], v[1], v[2], static_cast<T>(1)
437 };
438 }

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.

106 static mat4<T> identity() noexcept {
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.