dali/public-api/math/matrix3.h

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