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