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