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