dali/public-api/math/matrix.h

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