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