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