5 * Copyright (c) 2023 Samsung Electronics Co., Ltd.
7 * Licensed under the Apache License, Version 2.0 (the "License");
8 * you may not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
11 * http://www.apache.org/licenses/LICENSE-2.0
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
25 #include <dali/public-api/common/dali-common.h>
26 #include <dali/public-api/common/type-traits.h>
27 #include <dali/public-api/math/vector4.h>
32 * @addtogroup dali_core_math
39 * @brief The Matrix class represents transformations and projections.
41 * The matrix is stored as a flat array and is Column Major, i.e. the storage order is as follows (numbers represent
53 * Each axis is contiguous in memory, so the x-axis corresponds to elements 0, 1, 2 and 3, the y-axis corresponds to
54 * elements 4, 5, 6, 7, the z-axis corresponds to elements 12, 13, 14 and 15, and the translation vector corresponds to
55 * elements 12, 13 and 14.
59 class DALI_CORE_API Matrix
62 friend DALI_CORE_API std::ostream& operator<<(std::ostream& o, const Matrix& matrix);
67 * Zero initializes the matrix.
76 * @param[in] initialize True for initialization by zero or otherwise
78 explicit Matrix(bool initialize);
83 * The matrix is initialized with the contents of 'array' which must contain 16 floats.
84 * The order of the values for a transform matrix is:
87 * [ xAxis.x, xAxis.y, xAxis.z, 0.0f, yAxis.x, yAxis.y, yAxis.z, 0.0f, zAxis.x, zAxis.y, zAxis.z, 0.0f, trans.x, trans.y, trans.z, 1.0f ]
91 * @param[in] array Pointer of 16 floats data
93 explicit Matrix(const float* array);
96 * @brief Constructs a matrix from quaternion.
99 * @param rotation Rotation as quaternion
101 explicit Matrix(const Quaternion& rotation);
104 * @brief Copy constructor.
107 * @param[in] matrix A reference to the copied matrix
109 Matrix(const Matrix& matrix);
112 * @brief Assignment operator.
115 * @param[in] matrix A reference to the copied matrix
116 * @return A reference to this
118 Matrix& operator=(const Matrix& matrix);
121 * @brief Move constructor.
124 * @param[in] matrix A reference to the moved matrix
126 Matrix(Matrix&& matrix) noexcept;
129 * @brief Move assignment operator.
132 * @param[in] matrix A reference to the moved matrix
133 * @return A reference to this
135 Matrix& operator=(Matrix&& matrix) noexcept;
138 * @brief The identity matrix.
140 static const Matrix IDENTITY;
143 * @brief Sets this matrix to be an identity matrix.
149 * @brief Sets this matrix to be an identity matrix with scale.
152 * @param[in] scale Scale to set on top of identity matrix
154 void SetIdentityAndScale(const Vector3& scale);
157 * @brief Inverts a transform Matrix.
159 * Any Matrix representing only a rotation and/or translation
160 * can be inverted using this function. It is faster and more accurate then using Invert().
162 * @param[out] result The inverse of this matrix
164 void InvertTransform(Matrix& result) const;
167 * @brief Generic brute force Matrix Invert.
169 * Using the Matrix invert function for the specific type
170 * of matrix you are dealing with is faster, more accurate.
172 * @return True if successful
177 * @brief Swaps the rows to columns.
183 * @brief Returns the xAxis from a Transform matrix.
188 Vector3 GetXAxis() const;
191 * @brief Returns the yAxis from a Transform matrix.
196 Vector3 GetYAxis() const;
199 * @brief Returns the zAxis from a Transform matrix.
204 Vector3 GetZAxis() const;
207 * @brief Sets the x axis.
209 * This assumes the matrix is a transform matrix.
211 * @param[in] axis The values to set the axis to
213 void SetXAxis(const Vector3& axis);
216 * @brief Sets the y axis.
218 * This assumes the matrix is a transform matrix.
220 * @param[in] axis The values to set the axis to
222 void SetYAxis(const Vector3& axis);
225 * @brief Sets the z axis.
227 * This assumes the matrix is a transform matrix.
229 * @param[in] axis The values to set the axis to
231 void SetZAxis(const Vector3& axis);
234 * @brief Gets the translation.
236 * This assumes the matrix is a transform matrix.
238 * @return The translation
239 * @note inlined for performance reasons (generates less code than a function call)
241 const Vector4& GetTranslation() const
243 return reinterpret_cast<const Vector4&>(mMatrix[12]);
247 * @brief Gets the x,y and z components of the translation as a Vector3.
249 * This assumes the matrix is a transform matrix.
251 * @return The translation
252 * @note inlined for performance reasons (generates less code than a function call)
254 const Vector3& GetTranslation3() const
256 return reinterpret_cast<const Vector3&>(mMatrix[12]);
260 * @brief Gets the x,y and z components of the scale as a Vector3.
261 * Note that transform scale always has positive components.
263 * This assumes the matrix is a transform matrix.
267 Vector3 GetScale() const;
270 * @brief Sets the translation.
272 * This assumes the matrix is a transform matrix.
274 * @param[in] translation The translation
276 void SetTranslation(const Vector4& translation);
279 * @brief Sets the x,y and z components of the translation from a Vector3.
281 * This assumes the matrix is a transform matrix.
283 * @param[in] translation The translation
285 void SetTranslation(const Vector3& translation);
288 * @brief Makes the axes of the matrix orthogonal to each other and of unit length.
290 * This function is used to correct floating point errors which would otherwise accumulate
291 * as operations are applied to the matrix. This function assumes the matrix is a transform
295 void OrthoNormalize();
298 * @brief Returns the contents of the matrix as an array of 16 floats.
300 * The order of the values for a transform matrix is:
303 * [ xAxis.x, xAxis.y, xAxis.z, 0.0f, yAxis.x, yAxis.y, yAxis.z, 0.0f, zAxis.x, zAxis.y, zAxis.z, 0.0f, trans.x, trans.y, trans.z, 1.0f ]
307 * @return The matrix contents as an array of 16 floats
308 * @note inlined for performance reasons (generates less code than a function call)
310 const float* AsFloat() const
316 * @brief Returns the contents of the matrix as an array of 16 floats.
318 * The order of the values for a transform matrix is:
321 * [ xAxis.x, xAxis.y, xAxis.z, 0.0f, yAxis.x, yAxis.y, yAxis.z, 0.0f, zAxis.x, zAxis.y, zAxis.z, 0.0f, trans.x, trans.y, trans.z, 1.0f ]
325 * @return The matrix contents as an array of 16 floats
326 * @note inlined for performance reasons (generates less code than a function call)
333 * @brief Function to multiply two matrices and store the result onto third.
335 * Use this method in time critical path as it does not require temporaries.
340 * @param[out] result Result of the multiplication
341 * @param[in] lhs Matrix, this can be same matrix as result
342 * @param[in] rhs Matrix, this cannot be same matrix as result
344 static void Multiply(Matrix& result, const Matrix& lhs, const Matrix& rhs);
347 * @brief Function to multiply a matrix and quaternion and store the result onto third.
349 * Use this method in time critical path as it does not require temporaries.
351 * @param[out] result Result of the multiplication
352 * @param[in] lhs Matrix, this can be same matrix as result
353 * @param[in] rhs Quaternion
355 static void Multiply(Matrix& result, const Matrix& lhs, const Quaternion& rhs);
358 * @brief Multiplication operator.
360 * Returned Matrix = This Matrix * rhs
362 * @note It makes some memory allocate & copy internally.
363 * Use Matrix::Multiply API for time critical path.
366 * @param[in] rhs The Matrix to multiply this by
367 * @return A Matrix containing the result
369 Matrix operator*(const Matrix& rhs) const;
372 * @brief Multiplication assignment operator.
376 * @note It makes some memory allocate & copy internally.
379 * @param[in] rhs The Matrix to multiply this by
382 Matrix& operator*=(const Matrix& rhs);
385 * @brief The multiplication operator.
387 * Returned Vector = This Matrix * rhs
390 * @param[in] rhs The Vector4 to multiply this by
391 * @return A Vector4 containing the result
393 Vector4 operator*(const Vector4& rhs) const;
396 * @brief The equality operator.
398 * Utilizes appropriate machine epsilon values.
401 * @param[in] rhs The Matrix to compare this to
402 * @return true if the matrices are equal
404 bool operator==(const Matrix& rhs) const;
407 * @brief The inequality operator.
409 * Utilizes appropriate machine epsilon values.
411 * @param[in] rhs The Matrix to compare this to
412 * @return true if the matrices are not equal.
414 bool operator!=(const Matrix& rhs) const;
417 * @brief Sets this matrix to contain the position, scale and rotation components.
419 * Performs scale, rotation, then translation
421 * @param[in] scale Scale to apply
422 * @param[in] rotation Rotation to apply
423 * @param[in] translation Translation to apply
425 void SetTransformComponents(const Vector3& scale,
426 const Quaternion& rotation,
427 const Vector3& translation);
430 * @brief Sets this matrix to contain the inverse of the position, scale and rotation components.
432 * Performs translation, then rotation, then scale.
434 * @param[in] scale Scale to apply
435 * @param[in] rotation Rotation to apply
436 * @param[in] translation Translation to apply
438 void SetInverseTransformComponents(const Vector3& scale,
439 const Quaternion& rotation,
440 const Vector3& translation);
443 * @brief Sets this matrix to contain the inverse of the orthonormal basis and position components.
445 * Performs translation, then rotation.
447 * @param[in] xAxis The X axis of the basis
448 * @param[in] yAxis The Y axis of the basis
449 * @param[in] zAxis The Z axis of the basis
450 * @param[in] translation Translation to apply
452 void SetInverseTransformComponents(const Vector3& xAxis,
453 const Vector3& yAxis,
454 const Vector3& zAxis,
455 const Vector3& translation);
458 * @brief Gets the position, scale and rotation components from the given transform matrix.
461 * @param[out] position Position to set
462 * @param[out] rotation Rotation to set - only valid if the transform matrix has not been skewed or sheared
463 * @param[out] scale Scale to set - only valid if the transform matrix has not been skewed or sheared
464 * @pre This matrix must not contain skews or shears.
466 void GetTransformComponents(Vector3& position,
467 Quaternion& rotation,
468 Vector3& scale) const;
471 float mMatrix[16]; ///< The elements of the matrix
475 * @brief Prints a matrix.
477 * It is printed in memory order.
479 * @param[in] o The output stream operator
480 * @param[in] matrix The matrix to print
481 * @return The output stream operator
483 DALI_CORE_API std::ostream& operator<<(std::ostream& o, const Matrix& matrix);
485 // Allow Matrix to be treated as a POD type
487 struct TypeTraits<Matrix> : public BasicTypes<Matrix>
491 IS_TRIVIAL_TYPE = true
500 #endif // DALI_MATRIX_H