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