dali/public-api/math/matrix.h

   1 #ifndef DALI_MATRIX_H
   2 #define DALI_MATRIX_H
   3
   4 /*
   5  * Copyright (c) 2020 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
  63   friend DALI_CORE_API std::ostream& operator<< (std::ostream& o, const Matrix& matrix);
  64
  65   /**
  66    * @brief Constructor.
  67    *
  68    * Zero initializes the matrix.
  69    * @SINCE_1_0.0
  70    */
  71   Matrix();
  72
  73   /**
  74    * @brief Constructor.
  75    *
  76    * @SINCE_1_0.0
  77    * @param[in] initialize True for initialization by zero or otherwise
  78    */
  79   explicit Matrix( bool initialize );
  80
  81   /**
  82    * @brief Constructor.
  83    *
  84    * The matrix is initialized with the contents of 'array' which must contain 16 floats.
  85    * The order of the values for a transform matrix is:
  86    *
  87    * @code
  88    * [ 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 ]
  89    * @endcode
  90    *
  91    * @SINCE_1_0.0
  92    * @param[in] array Pointer of 16 floats data
  93    */
  94   explicit Matrix(const float* array);
  95
  96   /**
  97    * @brief Constructs a matrix from quaternion.
  98    *
  99    * @SINCE_1_0.0
 100    * @param rotation Rotation as quaternion
 101    */
 102   explicit Matrix( const Quaternion& rotation );
 103
 104   /**
 105    * @brief Copy constructor.
 106    *
 107    * @SINCE_1_0.0
 108    * @param[in] matrix A reference to the copied matrix
 109    */
 110   Matrix( const Matrix& matrix );
 111
 112   /**
 113    * @brief Assignment operator.
 114    *
 115    * @SINCE_1_0.0
 116    * @param[in] matrix A reference to the copied matrix
 117    * @return A reference to this
 118    */
 119   Matrix& operator=( const Matrix& matrix );
 120
 121   /**
 122    * @brief Move constructor.
 123    *
 124    * @SINCE_1_9.21
 125    * @param[in] matrix A reference to the moved matrix
 126    */
 127   Matrix( Matrix&& matrix );
 128
 129   /**
 130    * @brief Move assignment operator.
 131    *
 132    * @SINCE_1_9.21
 133    * @param[in] matrix A reference to the moved matrix
 134    * @return A reference to this
 135    */
 136   Matrix& operator=( Matrix&& matrix );
 137
 138   /**
 139    * @brief The identity matrix.
 140    */
 141   static const Matrix IDENTITY;
 142
 143   /**
 144    * @brief Sets this matrix to be an identity matrix.
 145    * @SINCE_1_0.0
 146    */
 147   void SetIdentity();
 148
 149   /**
 150    * @brief Sets this matrix to be an identity matrix with scale.
 151    *
 152    * @SINCE_1_0.0
 153    * @param[in] scale Scale to set on top of identity matrix
 154    */
 155   void SetIdentityAndScale( const Vector3& scale );
 156
 157   /**
 158    * @brief Inverts a transform Matrix.
 159    *
 160    * Any Matrix representing only a rotation and/or translation
 161    * can be inverted using this function. It is faster and more accurate then using Invert().
 162    * @SINCE_1_0.0
 163    * @param[out] result The inverse of this matrix
 164    */
 165   void InvertTransform(Matrix& result) const;
 166
 167   /**
 168    * @brief Generic brute force Matrix Invert.
 169    *
 170    * Using the Matrix invert function for the specific type
 171    * of matrix you are dealing with is faster, more accurate.
 172    * @SINCE_1_0.0
 173    * @return True if successful
 174    */
 175   bool Invert();
 176
 177   /**
 178    * @brief Swaps the rows to columns.
 179    * @SINCE_1_0.0
 180    */
 181   void Transpose();
 182
 183   /**
 184    * @brief Returns the xAxis from a Transform matrix.
 185    *
 186    * @SINCE_1_0.0
 187    * @return The x axis
 188    */
 189   Vector3 GetXAxis() const;
 190
 191   /**
 192    * @brief Returns the yAxis from a Transform matrix.
 193    *
 194    * @SINCE_1_0.0
 195    * @return The y axis
 196    */
 197   Vector3 GetYAxis() const;
 198
 199   /**
 200    * @brief Returns the zAxis from a Transform matrix.
 201    *
 202    * @SINCE_1_0.0
 203    * @return The z axis
 204    */
 205   Vector3 GetZAxis() const;
 206
 207   /**
 208    * @brief Sets the x axis.
 209    *
 210    * This assumes the matrix is a transform matrix.
 211    * @SINCE_1_0.0
 212    * @param[in] axis The values to set the axis to
 213    */
 214   void SetXAxis(const Vector3& axis);
 215
 216   /**
 217    * @brief Sets the y axis.
 218    *
 219    * This assumes the matrix is a transform matrix.
 220    * @SINCE_1_0.0
 221    * @param[in] axis The values to set the axis to
 222    */
 223   void SetYAxis(const Vector3& axis);
 224
 225   /**
 226    * @brief Sets the z axis.
 227    *
 228    * This assumes the matrix is a transform matrix.
 229    * @SINCE_1_0.0
 230    * @param[in] axis The values to set the axis to
 231    */
 232   void SetZAxis(const Vector3& axis);
 233
 234   /**
 235    * @brief Gets the translation.
 236    *
 237    * This assumes the matrix is a transform matrix.
 238    * @SINCE_1_0.0
 239    * @return The translation
 240    * @note inlined for performance reasons (generates less code than a function call)
 241    */
 242   const Vector4& GetTranslation() const { return reinterpret_cast<const Vector4&>(mMatrix[12]); }
 243
 244   /**
 245    * @brief Gets the x,y and z components of the translation as a Vector3.
 246    *
 247    * This assumes the matrix is a transform matrix.
 248    * @SINCE_1_0.0
 249    * @return The translation
 250    * @note inlined for performance reasons (generates less code than a function call)
 251    */
 252   const Vector3& GetTranslation3() const { return reinterpret_cast<const Vector3&>(mMatrix[12]); }
 253
 254   /**
 255    * @brief Sets the translation.
 256    *
 257    * This assumes the matrix is a transform matrix.
 258    * @SINCE_1_0.0
 259    * @param[in] translation The translation
 260    */
 261   void SetTranslation(const Vector4& translation);
 262
 263   /**
 264    * @brief Sets the x,y and z components of the translation from a Vector3.
 265    *
 266    * This assumes the matrix is a transform matrix.
 267    * @SINCE_1_0.0
 268    * @param[in] translation The translation
 269    */
 270   void SetTranslation(const Vector3& translation);
 271
 272   /**
 273    * @brief Makes the axes of the matrix orthogonal to each other and of unit length.
 274    *
 275    * This function is used to correct floating point errors which would otherwise accumulate
 276    * as operations are applied to the matrix. This function assumes the matrix is a transform
 277    * matrix.
 278    * @SINCE_1_0.0
 279    */
 280   void OrthoNormalize();
 281
 282   /**
 283    * @brief Returns the contents of the matrix as an array of 16 floats.
 284    *
 285    * The order of the values for a transform matrix is:
 286    *
 287    * @code
 288    * [ 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 ]
 289    * @endcode
 290    *
 291    * @SINCE_1_0.0
 292    * @return The matrix contents as an array of 16 floats
 293    * @note inlined for performance reasons (generates less code than a function call)
 294    */
 295   const float* AsFloat() const {return mMatrix;}
 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   float* AsFloat() {return mMatrix;}
 311
 312   /**
 313    * @brief Function to multiply two matrices and store the result onto third.
 314    *
 315    * Use this method in time critical path as it does not require temporaries.
 316    *
 317    * result = rhs * lhs
 318    *
 319    * @SINCE_1_0.0
 320    * @param[out] result Result of the multiplication
 321    * @param[in] lhs Matrix, this can be same matrix as result
 322    * @param[in] rhs Matrix, this cannot be same matrix as result
 323    */
 324   static void Multiply( Matrix& result, const Matrix& lhs, const Matrix& rhs );
 325
 326   /**
 327    * @brief Function to multiply a matrix and quaternion and store the result onto third.
 328    *
 329    * Use this method in time critical path as it does not require temporaries.
 330    * @SINCE_1_0.0
 331    * @param[out] result Result of the multiplication
 332    * @param[in] lhs Matrix, this can be same matrix as result
 333    * @param[in] rhs Quaternion
 334    */
 335   static void Multiply( Matrix& result, const Matrix& lhs, const Quaternion& rhs );
 336
 337   /**
 338    * @brief The multiplication operator.
 339    *
 340    * Returned Vector = This Matrix * rhs
 341    *
 342    * @SINCE_1_0.0
 343    * @param[in] rhs The Vector4 to multiply this by
 344    * @return A Vector4 containing the result
 345    */
 346   Vector4 operator*(const Vector4& rhs) const;
 347
 348   /**
 349    * @brief The equality operator.
 350    *
 351    * Utilizes appropriate machine epsilon values.
 352    *
 353    * @SINCE_1_0.0
 354    * @param[in] rhs The Matrix to compare this to
 355    * @return true if the matrices are equal
 356    */
 357   bool operator==(const Matrix & rhs) const;
 358
 359   /**
 360    * @brief The inequality operator.
 361    *
 362    * Utilizes appropriate machine epsilon values.
 363    * @SINCE_1_0.0
 364    * @param[in] rhs The Matrix to compare this to
 365    * @return true if the matrices are not equal.
 366    */
 367   bool operator!=(const Matrix & rhs) const;
 368
 369   /**
 370    * @brief Sets this matrix to contain the position, scale and rotation components.
 371    *
 372    * Performs scale, rotation, then translation
 373    * @SINCE_1_0.0
 374    * @param[in] scale Scale to apply
 375    * @param[in] rotation Rotation to apply
 376    * @param[in] translation Translation to apply
 377    */
 378   void SetTransformComponents(const Vector3& scale,
 379                               const Quaternion& rotation,
 380                               const Vector3& translation );
 381
 382   /**
 383    * @brief Sets this matrix to contain the inverse of the position, scale and rotation components.
 384    *
 385    * Performs translation, then rotation, then scale.
 386    * @SINCE_1_0.0
 387    * @param[in] scale Scale to apply
 388    * @param[in] rotation Rotation to apply
 389    * @param[in] translation Translation to apply
 390    */
 391   void SetInverseTransformComponents(const Vector3&    scale,
 392                                      const Quaternion& rotation,
 393                                      const Vector3&    translation );
 394
 395
 396   /**
 397    * @brief Sets this matrix to contain the inverse of the orthonormal basis and position components.
 398    *
 399    * Performs translation, then rotation.
 400    * @SINCE_1_0.0
 401    * @param[in] xAxis The X axis of the basis
 402    * @param[in] yAxis The Y axis of the basis
 403    * @param[in] zAxis The Z axis of the basis
 404    * @param[in] translation Translation to apply
 405    */
 406   void SetInverseTransformComponents(const Vector3&    xAxis,
 407                                      const Vector3&    yAxis,
 408                                      const Vector3&    zAxis,
 409                                      const Vector3&    translation );
 410
 411   /**
 412    * @brief Gets the position, scale and rotation components from the given transform matrix.
 413    *
 414    * @SINCE_1_0.0
 415    * @param[out] position Position to set
 416    * @param[out] rotation Rotation to set - only valid if the transform matrix has not been skewed or sheared
 417    * @param[out] scale Scale to set - only valid if the transform matrix has not been skewed or sheared
 418    * @pre This matrix must not contain skews or shears.
 419    */
 420   void GetTransformComponents(Vector3& position,
 421                               Quaternion& rotation,
 422                               Vector3& scale) const;
 423
 424 private:
 425
 426   float mMatrix[16]; ///< The elements of the matrix
 427 };
 428
 429 /**
 430  * @brief Prints a matrix.
 431  *
 432  * It is printed in memory order.
 433  * @SINCE_1_0.0
 434  * @param[in] o The output stream operator
 435  * @param[in] matrix The matrix to print
 436  * @return The output stream operator
 437  */
 438 DALI_CORE_API std::ostream& operator<< (std::ostream& o, const Matrix& matrix);
 439
 440 // Allow Matrix to be treated as a POD type
 441 template <> struct TypeTraits< Matrix > : public BasicTypes< Matrix > { enum { IS_TRIVIAL_TYPE = true }; };
 442
 443 /**
 444  * @}
 445  */
 446 } // namespace Dali
 447
 448 #endif // DALI_MATRIX_H