mat4 Struct Template

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

Declaration

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

Public Constructors Index

template <helios::math::Numeric T>
constexpr	mat4 () noexcept
	Default constructor. Initializes all components to 0. More...
template <helios::math::Numeric T>
constexpr	mat4 (const T f) noexcept
	Creates a diagonal matrix. The diagonal components are initialized with the value f. More...
template <helios::math::Numeric T>
constexpr	mat4 (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::Numeric T>
constexpr	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)
	Constructs a new `mat4` with all 16 components explicitly specified. More...

Public Operators Index

template <helios::math::Numeric 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::Numeric T>
constexpr T &	operator() (const size_t row, const size_t col)
	Provides read-write access to a matrix component. More...
template <helios::math::Numeric T>
constexpr bool	operator== (const mat4< T > &rgt) const
	Strictly compares the elements of this matrix with the elements of the rgt matrix. More...
template <helios::math::Numeric T>
constexpr auto	operator* (const mat4< T > &m) const -> mat4< T >
	Performs matrix-multiplication with another `mat4`. This matrix is the left operand, while `m` is the right operand. More...
template <helios::math::Numeric T>
constexpr auto	operator* (const vec4< T > &v) const -> vec4< T >
	Performs matrix-vector-multiplication with a `vec4<T> v`. More...

Public Member Functions Index

template <helios::math::Numeric T>
constexpr bool	same (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::Numeric T>
auto	transpose () const noexcept -> helios::math::mat4< T >
	Computes the transpose of a 4x4 matrix. More...
template <helios::math::Numeric T>
auto	column (unsigned int i) const noexcept -> helios::math::vec4< T >
	Returns the i-th column of the matrix. More...
template <helios::math::Numeric T>
constexpr auto	inverse () const noexcept -> helios::math::mat4< T >
	Computes the inverse of the matrix. More...
template <helios::math::Numeric T>
auto	translation () const noexcept -> helios::math::vec3< T >
	Extracts the translation component from this matrix. More...
template <helios::math::Numeric 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::Numeric 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::Numeric 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::Numeric 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::Numeric T>
T	m[16]
	Internal array storing matrix components. More...

Public Static Functions Index

template <helios::math::Numeric 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 36 of file mat4.ixx.

Public Constructors

mat4()

template <helios::math::Numeric T>

helios::math::mat4< T >::mat4 ()

inline explicit constexpr noexcept

Default constructor. Initializes all components to 0.

Definition at line 50 of file mat4.ixx.

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

Referenced by helios::math::mat4< float >::identity.

mat4()

template <helios::math::Numeric T>

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

58 explicit constexpr mat4(const T f) noexcept

59 : m{ f, T{}, T{}, T{},

60 T{}, f, T{}, T{},

61 T{}, T{}, f, T{},

62 T{}, T{}, T{}, f} {}

mat4()

template <helios::math::Numeric T>

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

70 explicit constexpr mat4(const vec3<T> f) noexcept

71 : m{ f[0], T{}, T{}, T{},

72 T{}, f[1], T{}, T{},

73 T{}, T{}, f[2], T{},

74 T{}, T{}, T{}, static_cast<T>(1)} {}

mat4()

template <helios::math::Numeric T>

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

84 constexpr mat4(

85 const T f0_0, const T f1_0, const T f2_0, const T f3_0,

86 const T f0_1, const T f1_1, const T f2_1, const T f3_1,

87 const T f0_2, const T f1_2, const T f2_2, const T f3_2,

88 const T f0_3, const T f1_3, const T f2_3, const T f3_3

89 ) : m{

90 f0_0, f1_0, f2_0, f3_0,

91 f0_1, f1_1, f2_1, f3_1,

92 f0_2, f1_2, f2_2, f3_2,

93 f0_3, f1_3, f2_3, f3_3

94 } { }

Public Operators

operator()()

template <helios::math::Numeric T>

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

130 constexpr const T& operator()(const size_t row, const size_t col) const {

131 assert(row < 4 && col < 4 && "mat4 - Index out of bounds.");

132 return m[row + col * 4];

133 }

operator()()

template <helios::math::Numeric T>

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

157 constexpr T& operator()(const size_t row, const size_t col) {

158 assert(row < 4 && col < 4 && "mat4 - Index out of bounds.");

159 return m[row + col * 4];

160 }

operator*()

template <helios::math::Numeric T>

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

229 constexpr mat4<T> operator*(const mat4<T>& m) const {

230 mat4<T> A{};

231 for (int row = 0; row < 4; row++) {

232 for (int col = 0; col < 4; col++) {

233 T sum = T{};

234 sum += (*this)(row, 0) * m(0, col);

235 sum += (*this)(row, 1) * m(1, col);

236 sum += (*this)(row, 2) * m(2, col);

237 sum += (*this)(row, 3) * m(3, col);

238 A(row, col) = sum;

239 }

240 }

241

242 return A;

243 }

operator*()

template <helios::math::Numeric T>

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

255 constexpr vec4<T> operator*(const vec4<T>& v) const {

256 const auto m = *this;

257 return vec4<T>{

258 m(0, 0) * v[0] + m(0, 1) * v[1] + m(0, 2) * v[2] + m(0, 3) * v[3],

259 m(1, 0) * v[0] + m(1, 1) * v[1] + m(1, 2) * v[2] + m(1, 3) * v[3],

260 m(2, 0) * v[0] + m(2, 1) * v[1] + m(2, 2) * v[2] + m(2, 3) * v[3],

261 m(3, 0) * v[0] + m(3, 1) * v[1] + m(3, 2) * v[2] + m(3, 3) * v[3]

262 };

263 }

operator==()

template <helios::math::Numeric T>

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

206 constexpr bool operator==(const mat4<T>& rgt) const {

207

208 const auto* leftPtr = value_ptr(*this);

209 const auto* rgtPtr = value_ptr(rgt);

210

211 for (int i = 0; i < 16; i++) {

212 if (leftPtr[i] != rgtPtr[i]) {

213 return false;

214 }

215 }

216

217 return true;

218 }

Public Member Functions

column()

template <helios::math::Numeric 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 293 of file mat4.ixx.

293 helios::math::vec4<T> column(unsigned int i) const noexcept {

294 assert(i <= 3 && "unexpected value for column");

295 const auto m = *this;

296 return helios::math::vec4<T>{

297 m(0, i), m(1, i), m(2, i), m(3, i)

298 };

299 }

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

decompose()

template <helios::math::Numeric 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:

• **TransformType::All**: Returns the original matrix unchanged.
• **TransformType::Translation**: Extracts only the translation (column 3).
• **TransformType::Rotation**: Extracts the normalized rotation from the upper-left 3x3.
• **TransformType::Scale**: Extracts the scale factors (column vector lengths).
• **Combined flags**: Extracts multiple components as specified.

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

449 helios::math::mat4<T> decompose(const helios::math::TransformType type) const noexcept {

450 const auto m = *this;

451 if (type == helios::math::TransformType::All) {

452 return m;

453 }

454

455 auto id = identity();

456 if (helios::math::transformTypeMatch(type, helios::math::TransformType::Translation)) {

457 id(0, 3) = m(0, 3);

458 id(1, 3) = m(1, 3);

459 id(2, 3) = m(2, 3);

460 }

461

462 if (helios::math::transformTypeMatch(type, helios::math::TransformType::Rotation)

463 && helios::math::transformTypeMatch(type, helios::math::TransformType::Scale)) {

464 id(0, 0) = m(0, 0); id(0, 1) = m(0, 1); id(0, 2) = m(0, 2);

465 id(1, 0) = m(1, 0); id(1, 1) = m(1, 1); id(1, 2) = m(1, 2);

466 id(2, 0) = m(2, 0); id(2, 1) = m(2, 1); id(2, 2) = m(2, 2);

467 } else {

468

469 const auto bx = vec3<T>(m(0, 0), m(1, 0), m(2, 0));

470 const auto by = vec3<T>(m(0, 1), m(1, 1), m(2, 1));

471 const auto bz = vec3<T>(m(0, 2), m(1, 2), m(2, 2));

472

473 const auto sx = bx.length();

474 const auto sy = by.length();

475 const auto sz = bz.length();

476

477 if (helios::math::transformTypeMatch(type, helios::math::TransformType::Rotation)) {

478 vec3<T> rx = sx != 0 ? bx/sx : vec3<T>{1, 0, 0};

479 vec3<T> ry = sy != 0 ? by/sy : vec3<T>{0, 1, 0};

480 vec3<T> rz = sz != 0 ? bz/sz : vec3<T>{0, 0, 1};

481

482 id(0, 0) = rx[0]; id(0, 1) = ry[0]; id(0, 2) = rz[0];

483 id(1, 0) = rx[1]; id(1, 1) = ry[1]; id(1, 2) = rz[1];

484 id(2, 0) = rx[2]; id(2, 1) = ry[2]; id(2, 2) = rz[2];

485 } else if (helios::math::transformTypeMatch(type, helios::math::TransformType::Scale)) {

486 id(0, 0) = sx;

487 id(1, 1) = sy;

488 id(2, 2) = sz;

489 }

490 }

491

492 return id;

493 }

Referenced by helios::scene::CameraSceneNode::lookAt.

inverse()

template <helios::math::Numeric T>

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

308 constexpr helios::math::mat4<T> inverse() const noexcept {

309 const auto m = *this;

310

311 const auto a = column(0).toVec3();

312 const auto b = column(1).toVec3();

313 const auto c = column(2).toVec3();

314 const auto d = column(3).toVec3();

315

316 const T x = m(3, 0);

317 const T y = m(3, 1);

318 const T z = m(3, 2);

319 const T w = m(3, 3);

320

321 auto s = helios::math::cross(a, b);

322 auto t = helios::math::cross(c, d);

323 auto u = a*y - b*x;

324 auto v = c*w - d*z;

325

326 T invDet = static_cast<T>(1) / (helios::math::dot(s, v) + helios::math::dot(t, u));

327

328 s = s * invDet;

329 t = t * invDet;

330 u = u * invDet;

331 v = v * invDet;

332

333 auto r0 = (helios::math::cross(b, v)) + t*y;

334 auto r1 = (helios::math::cross(v, a)) - t*x;

335 auto r2 = (helios::math::cross(d, u)) + s*w;

336 auto r3 = (helios::math::cross(u, c)) - s*z;

337

338 return helios::math::mat4<T>{

339 r0[0], r0[1], r0[2], -helios::math::dot(b, t),

340 r1[0], r1[1], r1[2], helios::math::dot(a, t),

341 r2[0], r2[1], r2[2], -helios::math::dot(d, s),

342 r3[0], r3[1], r3[2], helios::math::dot(c, s)

343 };

344 }

Referenced by helios::engine::mechanics::bounds::systems::LevelBoundsBehaviorSystem::update.

same()

template <helios::math::Numeric T>

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

Todo

account for abs (values close to zero) and rel (larger values), move EPSILON to global constant

Definition at line 181 of file mat4.ixx.

181 constexpr bool same(const mat4<T>& rgt) const {

182

183 static const T EPSILON = static_cast<T>(0.00001);

184

185 const auto* leftPtr = value_ptr(*this);

186 const auto* rgtPtr = value_ptr(rgt);

187

188 for (int i = 0; i < 16; i++) {

189 if (std::fabs(leftPtr[i] - rgtPtr[i]) > EPSILON) {

190 return false;

191 }

192 }

193

194 return true;

195 }

translation()

template <helios::math::Numeric 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 354 of file mat4.ixx.

354 helios::math::vec3<T> translation() const noexcept {

355 const auto m = *this;

356 return helios::math::vec3<T>{

357 m(0, 3), m(1, 3), m(2, 3)

358 };

359 }

Referenced by helios::engine::mechanics::bounds::systems::LevelBoundsBehaviorSystem::update.

transpose()

template <helios::math::Numeric 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 277 of file mat4.ixx.

277 helios::math::mat4<T> transpose() const noexcept {

278 const auto m = *this;

279 return helios::math::mat4<T>{

280 m(0, 0), m(0, 1), m(0, 2), m(0, 3),

281 m(1, 0), m(1, 1), m(1, 2), m(1, 3),

282 m(2, 0), m(2, 1), m(2, 2), m(2, 3),

283 m(3, 0), m(3, 1), m(3, 2), m(3, 3)

284 };

285 }

withScaling()

template <helios::math::Numeric 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 392 of file mat4.ixx.

392 helios::math::mat4<T> withScaling(helios::math::vec3<T> v) const noexcept {

393 const auto m = *this;

394 return helios::math::mat4<T>{

395 m(0, 0) * v[0], m(1, 0) * v[0], m(2, 0) * v[0], m(3, 0) * v[0],

396 m(0, 1) * v[1], m(1, 1) * v[1], m(2, 1) * v[1], m(3, 1) * v[1],

397 m(0, 2) * v[2], m(1, 2) * v[2], m(2, 2) * v[2], m(3, 2) * v[2],

398 m(0, 3), m(1, 3), m(2, 3), m(3, 3),

399 };

400 }

withTranslation()

template <helios::math::Numeric 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 371 of file mat4.ixx.

371 helios::math::mat4<T> withTranslation(helios::math::vec3<T> v) const noexcept {

372 const auto m = *this;

373 return helios::math::mat4<T>{

374 m(0, 0), m(1, 0), m(2, 0), m(3, 0),

375 m(0, 1), m(1, 1), m(2, 1), m(3, 1),

376 m(0, 2), m(1, 2), m(2, 2), m(3, 2),

377 v[0], v[1], v[2], static_cast<T>(1)

378 };

379 }

Referenced by helios::engine::mechanics::bounds::systems::LevelBoundsBehaviorSystem::update.

withTranslation()

template <helios::math::Numeric 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 413 of file mat4.ixx.

413 helios::math::mat4<T> withTranslation(helios::math::vec4<T> v) const noexcept {

414 const auto m = *this;

415 return helios::math::mat4<T>{

416 m(0, 0), m(1, 0), m(2, 0), m(3, 0),

417 m(0, 1), m(1, 1), m(2, 1), m(3, 1),

418 m(0, 2), m(1, 2), m(2, 2), m(3, 2),

419 v[0], v[1], v[2], static_cast<T>(1)

420 };

421 }

Private Member Attributes

m

template <helios::math::Numeric 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 44 of file mat4.ixx.

44 T m[16];

Public Static Functions

identity()

template <helios::math::Numeric 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 104 of file mat4.ixx.

104 static mat4<T> identity() noexcept {

105 return mat4<T>(1);

106 }

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

---

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

• mat4.ixx

---

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.