dali/public-api/math/matrix3.h

   1 #ifndef __DALI_MATRIX3_H__
   2 #define __DALI_MATRIX3_H__
   3
   4 /*
   5  * Copyright (c) 2018 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/vector3.h>
  23 #include <dali/public-api/math/matrix.h>
  24 #include <dali/public-api/common/type-traits.h>
  25
  26 namespace Dali
  27 {
  28 /**
  29  * @addtogroup dali_core_math
  30  * @{
  31  */
  32
  33 class Matrix;
  34 struct Vector2;
  35
  36 /**
  37  * @brief A 3x3 matrix.
  38  *
  39  * The matrix is stored as a flat array and is Column Major, i.e. the storage order is as follows (numbers represent
  40  * indices of array):
  41  *
  42  * @code
  43  *
  44  * 0  3  6
  45  * 1  4  7
  46  * 2  5  8
  47  *
  48  * @endcode
  49  *
  50  * Each axis is contiguous in memory, so the x-axis corresponds to elements 0, 1 and 2, the y-axis corresponds to
  51  * elements 3, 4 and 5, and the z-axis corresponds to elements 6, 7 and 8.
  52  *
  53  * @SINCE_1_0.0
  54  */
  55 class DALI_CORE_API Matrix3
  56 {
  57 public:
  58
  59   friend std::ostream& operator<< (std::ostream& o, const Matrix3& matrix);
  60
  61   /**
  62    * @brief The identity matrix.
  63    */
  64   static const Matrix3 IDENTITY;
  65
  66   /**
  67    * @brief Constructor.
  68    * @SINCE_1_0.0
  69    */
  70   Matrix3();
  71
  72   /**
  73    * @brief Copy Constructor.
  74    *
  75    * @SINCE_1_0.0
  76    * @param[in] m A reference to the copied 3x3 matrix
  77    */
  78   Matrix3(const Matrix3& m);
  79
  80   /**
  81    * @brief Constructor.
  82    *
  83    * @SINCE_1_0.0
  84    * @param[in] m A 4x4 matrix. The translation and shear components are ignored
  85    */
  86   Matrix3(const Matrix& m);
  87
  88   /**
  89    * @brief Constructor.
  90    *
  91    * @SINCE_1_0.0
  92    * @param[in] s00 First element
  93    * @param[in] s01 Second element
  94    * @param[in] s02 Third element
  95    * @param[in] s10 Fourth element
  96    * @param[in] s11 Fifth element
  97    * @param[in] s12 Sixth element
  98    * @param[in] s20 Seventh element
  99    * @param[in] s21 Eighth element
 100    * @param[in] s22 Ninth element
 101    */
 102   Matrix3(float s00, float s01, float s02, float s10, float s11, float s12, float s20, float s21, float s22);
 103
 104   /**
 105    * @brief Assignment Operator.
 106    * @SINCE_1_0.0
 107    * @param[in] matrix From which to copy values
 108    * @return Reference to this object
 109    */
 110   Matrix3& operator=( const Matrix3& matrix );
 111
 112   /**
 113    * @brief Assignment Operator.
 114    * @SINCE_1_0.0
 115    * @param[in] matrix A reference to the copied matrix
 116    * @return A reference to this
 117    */
 118   Matrix3& operator=( const Matrix& matrix );
 119
 120   /**
 121    * @brief The equality operator.
 122    *
 123    * Utilizes appropriate machine epsilon values.
 124    *
 125    * @SINCE_1_0.0
 126    * @param[in] rhs The Matrix to compare this to
 127    * @return True if the matrices are equal
 128    */
 129   bool operator==(const Matrix3 & rhs) const;
 130
 131   /**
 132    * @brief The inequality operator.
 133    *
 134    * Utilizes appropriate machine epsilon values.
 135    *
 136    * @SINCE_1_0.0
 137    * @param[in] rhs The Matrix to compare this to
 138    * @return true if the matrices are equal
 139    */
 140   bool operator!=(const Matrix3 & rhs) const;
 141
 142   /**
 143    * @brief Destructor.
 144    * @SINCE_1_0.0
 145    */
 146   ~Matrix3()
 147   {
 148   }
 149
 150   /**
 151    * @brief Sets the matrix to the identity matrix.
 152    * @SINCE_1_0.0
 153    */
 154   void SetIdentity();
 155
 156   /**
 157    * @brief Returns the contents of the matrix as an array of 9 floats.
 158    *
 159    * The order of the values for a matrix is:
 160    *
 161    * @code
 162    * [ xAxis.x, xAxis.y, xAxis.z, yAxis.x, yAxis.y, yAxis.z, zAxis.x, zAxis.y, zAxis.z ]
 163    * @endcode
 164    *
 165    * @SINCE_1_0.0
 166    * @return The matrix contents as an array of 9 floats
 167    */
 168   const float* AsFloat() const {return &mElements[0];}
 169
 170   /**
 171    * @brief Returns the contents of the matrix as an array of 9 floats.
 172    *
 173    * The order of the values for a matrix is:
 174    *
 175    * @code
 176    * [ xAxis.x, xAxis.y, xAxis.z, yAxis.x, yAxis.y, yAxis.z, zAxis.x, zAxis.y, zAxis.z ]
 177    * @endcode
 178    *
 179    * @SINCE_1_0.0
 180    * @return The matrix contents as an array of 9 floats
 181    */
 182   float* AsFloat() {return &mElements[0];}
 183
 184   /**
 185    * @brief Inverts the matrix.
 186    *
 187    * @SINCE_1_0.0
 188    * @return True if successful
 189    */
 190   bool Invert();
 191
 192   /**
 193    * @brief Swaps the rows to columns.
 194    * @SINCE_1_0.0
 195    * @return True if successful
 196    */
 197   bool Transpose();
 198
 199   /**
 200    * @brief Multiplies all elements of the matrix by the scale value.
 201    *
 202    * @SINCE_1_0.0
 203    * @param[in] scale The value by which to scale the whole matrix
 204    */
 205   void Scale(float scale);
 206
 207   /**
 208    * @brief Magnitude returns the average of the absolute values of the
 209    * elements * 3.
 210    *
 211    * (The Magnitude of the unit matrix is therefore 1)
 212    * @SINCE_1_0.0
 213    * @return The magnitude - always positive
 214    */
 215   float Magnitude() const;
 216
 217   /**
 218    * @brief If the matrix is invertible, then this method inverts, transposes
 219    * and scales the matrix such that the resultant element values
 220    * average 1.
 221    *
 222    * If the matrix is not invertible, then the matrix is left unchanged.
 223    *
 224    * @SINCE_1_0.0
 225    * @return @c true if the matrix is invertible, otherwise @c false
 226    */
 227   bool ScaledInverseTranspose();
 228
 229   /**
 230    * @brief Function to multiply two matrices and store the result onto third.
 231    *
 232    * Use this method in time critical path as it does not require temporaries
 233    *
 234    * result = rhs * lhs
 235    *
 236    * @SINCE_1_0.0
 237    * @param[out] result Result of the multiplication
 238    * @param[in] lhs Matrix, this can be same matrix as result
 239    * @param[in] rhs Matrix, this cannot be same matrix as result
 240    */
 241   static void Multiply( Matrix3& result, const Matrix3& lhs, const Matrix3& rhs );
 242
 243 private:
 244
 245   float mElements[9]; ///< The elements of the matrix
 246 };
 247
 248 /**
 249  * @brief Prints a 3x3 matrix.
 250  *
 251  * @SINCE_1_0.0
 252  * @param[in] o The output stream operator
 253  * @param[in] matrix The matrix to print
 254  * @return The output stream operator
 255  */
 256 DALI_CORE_API std::ostream& operator<< (std::ostream& o, const Matrix3& matrix);
 257
 258 // Allow Matrix3 to be treated as a POD type
 259 template <> struct TypeTraits< Matrix3 > : public BasicTypes< Matrix3 > { enum { IS_TRIVIAL_TYPE = true }; };
 260
 261 /**
 262  * @}
 263  */
 264 } // namespace Dali
 265
 266 #endif //__DALI_MATRIX3_H__