capi/dali/public-api/math/matrix.h

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