dali/public-api/math/matrix.h

   1 #ifndef DALI_MATRIX_H
   2 #define DALI_MATRIX_H
   3
   4 /*
   5  * Copyright (c) 2023 Samsung Electronics Co., Ltd.
   6  *
   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
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  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.
  18  *
  19  */
  20
  21 // EXTERNAL INCLUDES
  22 #include <iosfwd>
  23
  24 // INTERNAL INCLUDES
  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>
  28
  29 namespace Dali
  30 {
  31 /**
  32  * @addtogroup dali_core_math
  33  * @{
  34  */
  35
  36 class Quaternion;
  37
  38 /**
  39  * @brief The Matrix class represents transformations and projections.
  40  *
  41  * The matrix is stored as a flat array and is Column Major, i.e. the storage order is as follows (numbers represent
  42  * indices of array):
  43  *
  44  * @code
  45  *
  46  * 0   4   8   12
  47  * 1   5   9   13
  48  * 2   6   10  14
  49  * 3   7   11  15
  50  *
  51  * @endcode
  52  *
  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.
  56  *
  57  * @SINCE_1_0.0
  58  */
  59 class DALI_CORE_API Matrix
  60 {
  61 public:
  62   friend DALI_CORE_API std::ostream& operator<<(std::ostream& o, const Matrix& matrix);
  63
  64   /**
  65    * @brief Constructor.
  66    *
  67    * Zero initializes the matrix.
  68    * @SINCE_1_0.0
  69    */
  70   Matrix();
  71
  72   /**
  73    * @brief Constructor.
  74    *
  75    * @SINCE_1_0.0
  76    * @param[in] initialize True for initialization by zero or otherwise
  77    */
  78   explicit Matrix(bool initialize);
  79
  80   /**
  81    * @brief Constructor.
  82    *
  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:
  85    *
  86    * @code
  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 ]
  88    * @endcode
  89    *
  90    * @SINCE_1_0.0
  91    * @param[in] array Pointer of 16 floats data
  92    */
  93   explicit Matrix(const float* array);
  94
  95   /**
  96    * @brief Constructs a matrix from quaternion.
  97    *
  98    * @SINCE_1_0.0
  99    * @param rotation Rotation as quaternion
 100    */
 101   explicit Matrix(const Quaternion& rotation);
 102
 103   /**
 104    * @brief Copy constructor.
 105    *
 106    * @SINCE_1_0.0
 107    * @param[in] matrix A reference to the copied matrix
 108    */
 109   Matrix(const Matrix& matrix);
 110
 111   /**
 112    * @brief Assignment operator.
 113    *
 114    * @SINCE_1_0.0
 115    * @param[in] matrix A reference to the copied matrix
 116    * @return A reference to this
 117    */
 118   Matrix& operator=(const Matrix& matrix);
 119
 120   /**
 121    * @brief Move constructor.
 122    *
 123    * @SINCE_1_9.21
 124    * @param[in] matrix A reference to the moved matrix
 125    */
 126   Matrix(Matrix&& matrix) noexcept;
 127
 128   /**
 129    * @brief Move assignment operator.
 130    *
 131    * @SINCE_1_9.21
 132    * @param[in] matrix A reference to the moved matrix
 133    * @return A reference to this
 134    */
 135   Matrix& operator=(Matrix&& matrix) noexcept;
 136
 137   /**
 138    * @brief The identity matrix.
 139    */
 140   static const Matrix IDENTITY;
 141
 142   /**
 143    * @brief Sets this matrix to be an identity matrix.
 144    * @SINCE_1_0.0
 145    */
 146   void SetIdentity();
 147
 148   /**
 149    * @brief Sets this matrix to be an identity matrix with scale.
 150    *
 151    * @SINCE_1_0.0
 152    * @param[in] scale Scale to set on top of identity matrix
 153    */
 154   void SetIdentityAndScale(const Vector3& scale);
 155
 156   /**
 157    * @brief Inverts a transform Matrix.
 158    *
 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().
 161    * @SINCE_1_0.0
 162    * @param[out] result The inverse of this matrix
 163    */
 164   void InvertTransform(Matrix& result) const;
 165
 166   /**
 167    * @brief Generic brute force Matrix Invert.
 168    *
 169    * Using the Matrix invert function for the specific type
 170    * of matrix you are dealing with is faster, more accurate.
 171    * @SINCE_1_0.0
 172    * @return True if successful
 173    */
 174   bool Invert();
 175
 176   /**
 177    * @brief Swaps the rows to columns.
 178    * @SINCE_1_0.0
 179    */
 180   void Transpose();
 181
 182   /**
 183    * @brief Returns the xAxis from a Transform matrix.
 184    *
 185    * @SINCE_1_0.0
 186    * @return The x axis
 187    */
 188   Vector3 GetXAxis() const;
 189
 190   /**
 191    * @brief Returns the yAxis from a Transform matrix.
 192    *
 193    * @SINCE_1_0.0
 194    * @return The y axis
 195    */
 196   Vector3 GetYAxis() const;
 197
 198   /**
 199    * @brief Returns the zAxis from a Transform matrix.
 200    *
 201    * @SINCE_1_0.0
 202    * @return The z axis
 203    */
 204   Vector3 GetZAxis() const;
 205
 206   /**
 207    * @brief Sets the x axis.
 208    *
 209    * This assumes the matrix is a transform matrix.
 210    * @SINCE_1_0.0
 211    * @param[in] axis The values to set the axis to
 212    */
 213   void SetXAxis(const Vector3& axis);
 214
 215   /**
 216    * @brief Sets the y axis.
 217    *
 218    * This assumes the matrix is a transform matrix.
 219    * @SINCE_1_0.0
 220    * @param[in] axis The values to set the axis to
 221    */
 222   void SetYAxis(const Vector3& axis);
 223
 224   /**
 225    * @brief Sets the z axis.
 226    *
 227    * This assumes the matrix is a transform matrix.
 228    * @SINCE_1_0.0
 229    * @param[in] axis The values to set the axis to
 230    */
 231   void SetZAxis(const Vector3& axis);
 232
 233   /**
 234    * @brief Gets the translation.
 235    *
 236    * This assumes the matrix is a transform matrix.
 237    * @SINCE_1_0.0
 238    * @return The translation
 239    * @note inlined for performance reasons (generates less code than a function call)
 240    */
 241   const Vector4& GetTranslation() const
 242   {
 243     return reinterpret_cast<const Vector4&>(mMatrix[12]);
 244   }
 245
 246   /**
 247    * @brief Gets the x,y and z components of the translation as a Vector3.
 248    *
 249    * This assumes the matrix is a transform matrix.
 250    * @SINCE_1_0.0
 251    * @return The translation
 252    * @note inlined for performance reasons (generates less code than a function call)
 253    */
 254   const Vector3& GetTranslation3() const
 255   {
 256     return reinterpret_cast<const Vector3&>(mMatrix[12]);
 257   }
 258
 259   /**
 260    * @brief Gets the x,y and z components of the scale as a Vector3.
 261    * Note that transform scale always has positive components.
 262    *
 263    * This assumes the matrix is a transform matrix.
 264    * @SINCE_2_2.17
 265    * @return The scale
 266    */
 267   Vector3 GetScale() const;
 268
 269   /**
 270    * @brief Sets the translation.
 271    *
 272    * This assumes the matrix is a transform matrix.
 273    * @SINCE_1_0.0
 274    * @param[in] translation The translation
 275    */
 276   void SetTranslation(const Vector4& translation);
 277
 278   /**
 279    * @brief Sets the x,y and z components of the translation from a Vector3.
 280    *
 281    * This assumes the matrix is a transform matrix.
 282    * @SINCE_1_0.0
 283    * @param[in] translation The translation
 284    */
 285   void SetTranslation(const Vector3& translation);
 286
 287   /**
 288    * @brief Makes the axes of the matrix orthogonal to each other and of unit length.
 289    *
 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
 292    * matrix.
 293    * @SINCE_1_0.0
 294    */
 295   void OrthoNormalize();
 296
 297   /**
 298    * @brief Returns the contents of the matrix as an array of 16 floats.
 299    *
 300    * The order of the values for a transform matrix is:
 301    *
 302    * @code
 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 ]
 304    * @endcode
 305    *
 306    * @SINCE_1_0.0
 307    * @return The matrix contents as an array of 16 floats
 308    * @note inlined for performance reasons (generates less code than a function call)
 309    */
 310   const float* AsFloat() const
 311   {
 312     return mMatrix;
 313   }
 314
 315   /**
 316    * @brief Returns the contents of the matrix as an array of 16 floats.
 317    *
 318    * The order of the values for a transform matrix is:
 319    *
 320    * @code
 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 ]
 322    * @endcode
 323    *
 324    * @SINCE_1_0.0
 325    * @return The matrix contents as an array of 16 floats
 326    * @note inlined for performance reasons (generates less code than a function call)
 327    */
 328   float* AsFloat()
 329   {
 330     return mMatrix;
 331   }
 332   /**
 333    * @brief Function to multiply two matrices and store the result onto third.
 334    *
 335    * Use this method in time critical path as it does not require temporaries.
 336    *
 337    * result = rhs * lhs
 338    *
 339    * @SINCE_1_0.0
 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
 343    */
 344   static void Multiply(Matrix& result, const Matrix& lhs, const Matrix& rhs);
 345
 346   /**
 347    * @brief Function to multiply a matrix and quaternion and store the result onto third.
 348    *
 349    * Use this method in time critical path as it does not require temporaries.
 350    * @SINCE_1_0.0
 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
 354    */
 355   static void Multiply(Matrix& result, const Matrix& lhs, const Quaternion& rhs);
 356
 357   /**
 358    * @brief Multiplication operator.
 359    *
 360    * Returned Matrix = This Matrix * rhs
 361    *
 362    * @note It makes some memory allocate & copy internally.
 363    * Use Matrix::Multiply API for time critical path.
 364    *
 365    * @SINCE_2_1.44
 366    * @param[in] rhs The Matrix to multiply this by
 367    * @return A Matrix containing the result
 368    */
 369   Matrix operator*(const Matrix& rhs) const;
 370
 371   /**
 372    * @brief Multiplication assignment operator.
 373    *
 374    * This Matrix *= rhs
 375    *
 376    * @note It makes some memory allocate & copy internally.
 377    *
 378    * @SINCE_2_1.46
 379    * @param[in] rhs The Matrix to multiply this by
 380    * @return Itself
 381    */
 382   Matrix& operator*=(const Matrix& rhs);
 383
 384   /**
 385    * @brief The multiplication operator.
 386    *
 387    * Returned Vector = This Matrix * rhs
 388    *
 389    * @SINCE_1_0.0
 390    * @param[in] rhs The Vector4 to multiply this by
 391    * @return A Vector4 containing the result
 392    */
 393   Vector4 operator*(const Vector4& rhs) const;
 394
 395   /**
 396    * @brief The equality operator.
 397    *
 398    * Utilizes appropriate machine epsilon values.
 399    *
 400    * @SINCE_1_0.0
 401    * @param[in] rhs The Matrix to compare this to
 402    * @return true if the matrices are equal
 403    */
 404   bool operator==(const Matrix& rhs) const;
 405
 406   /**
 407    * @brief The inequality operator.
 408    *
 409    * Utilizes appropriate machine epsilon values.
 410    * @SINCE_1_0.0
 411    * @param[in] rhs The Matrix to compare this to
 412    * @return true if the matrices are not equal.
 413    */
 414   bool operator!=(const Matrix& rhs) const;
 415
 416   /**
 417    * @brief Sets this matrix to contain the position, scale and rotation components.
 418    *
 419    * Performs scale, rotation, then translation
 420    * @SINCE_1_0.0
 421    * @param[in] scale Scale to apply
 422    * @param[in] rotation Rotation to apply
 423    * @param[in] translation Translation to apply
 424    */
 425   void SetTransformComponents(const Vector3&    scale,
 426                               const Quaternion& rotation,
 427                               const Vector3&    translation);
 428
 429   /**
 430    * @brief Sets this matrix to contain the inverse of the position, scale and rotation components.
 431    *
 432    * Performs translation, then rotation, then scale.
 433    * @SINCE_1_0.0
 434    * @param[in] scale Scale to apply
 435    * @param[in] rotation Rotation to apply
 436    * @param[in] translation Translation to apply
 437    */
 438   void SetInverseTransformComponents(const Vector3&    scale,
 439                                      const Quaternion& rotation,
 440                                      const Vector3&    translation);
 441
 442   /**
 443    * @brief Sets this matrix to contain the inverse of the orthonormal basis and position components.
 444    *
 445    * Performs translation, then rotation.
 446    * @SINCE_1_0.0
 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
 451    */
 452   void SetInverseTransformComponents(const Vector3& xAxis,
 453                                      const Vector3& yAxis,
 454                                      const Vector3& zAxis,
 455                                      const Vector3& translation);
 456
 457   /**
 458    * @brief Gets the position, scale and rotation components from the given transform matrix.
 459    *
 460    * @SINCE_1_0.0
 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.
 465    */
 466   void GetTransformComponents(Vector3&    position,
 467                               Quaternion& rotation,
 468                               Vector3&    scale) const;
 469
 470 private:
 471   float mMatrix[16]; ///< The elements of the matrix
 472 };
 473
 474 /**
 475  * @brief Prints a matrix.
 476  *
 477  * It is printed in memory order.
 478  * @SINCE_1_0.0
 479  * @param[in] o The output stream operator
 480  * @param[in] matrix The matrix to print
 481  * @return The output stream operator
 482  */
 483 DALI_CORE_API std::ostream& operator<<(std::ostream& o, const Matrix& matrix);
 484
 485 // Allow Matrix to be treated as a POD type
 486 template<>
 487 struct TypeTraits<Matrix> : public BasicTypes<Matrix>
 488 {
 489   enum
 490   {
 491     IS_TRIVIAL_TYPE = true
 492   };
 493 };
 494
 495 /**
 496  * @}
 497  */
 498 } // namespace Dali
 499
 500 #endif // DALI_MATRIX_H