dali/public-api/math/matrix3.h

   1 #ifndef DALI_MATRIX3_H
   2 #define DALI_MATRIX3_H
   3
   4 /*
   5  * Copyright (c) 2022 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) noexcept;
 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) noexcept;
 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() = default;
 163
 164   /**
 165    * @brief Sets the matrix to the identity matrix.
 166    * @SINCE_1_0.0
 167    */
 168   void SetIdentity();
 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   const float* AsFloat() const
 183   {
 184     return &mElements[0];
 185   }
 186
 187   /**
 188    * @brief Returns the contents of the matrix as an array of 9 floats.
 189    *
 190    * The order of the values for a matrix is:
 191    *
 192    * @code
 193    * [ xAxis.x, xAxis.y, xAxis.z, yAxis.x, yAxis.y, yAxis.z, zAxis.x, zAxis.y, zAxis.z ]
 194    * @endcode
 195    *
 196    * @SINCE_1_0.0
 197    * @return The matrix contents as an array of 9 floats
 198    */
 199   float* AsFloat()
 200   {
 201     return &mElements[0];
 202   }
 203
 204   /**
 205    * @brief Inverts the matrix.
 206    *
 207    * @SINCE_1_0.0
 208    * @return True if successful
 209    */
 210   bool Invert();
 211
 212   /**
 213    * @brief Swaps the rows to columns.
 214    * @SINCE_1_0.0
 215    * @return True if successful
 216    */
 217   bool Transpose();
 218
 219   /**
 220    * @brief Multiplies all elements of the matrix by the scale value.
 221    *
 222    * @SINCE_1_0.0
 223    * @param[in] scale The value by which to scale the whole matrix
 224    */
 225   void Scale(float scale);
 226
 227   /**
 228    * @brief Magnitude returns the average of the absolute values of the
 229    * elements * 3.
 230    *
 231    * (The Magnitude of the unit matrix is therefore 1)
 232    * @SINCE_1_0.0
 233    * @return The magnitude - always positive
 234    */
 235   float Magnitude() const;
 236
 237   /**
 238    * @brief If the matrix is invertible, then this method inverts, transposes
 239    * and scales the matrix such that the resultant element values
 240    * average 1.
 241    *
 242    * If the matrix is not invertible, then the matrix is left unchanged.
 243    *
 244    * @SINCE_1_0.0
 245    * @return @c true if the matrix is invertible, otherwise @c false
 246    */
 247   bool ScaledInverseTranspose();
 248
 249   /**
 250    * @brief Function to multiply two matrices and store the result onto third.
 251    *
 252    * Use this method in time critical path as it does not require temporaries
 253    *
 254    * result = rhs * lhs
 255    *
 256    * @SINCE_1_0.0
 257    * @param[out] result Result of the multiplication
 258    * @param[in] lhs Matrix, this can be same matrix as result
 259    * @param[in] rhs Matrix, this cannot be same matrix as result
 260    */
 261   static void Multiply(Matrix3& result, const Matrix3& lhs, const Matrix3& rhs);
 262
 263   /**
 264    * @brief Multiplication operator.
 265    *
 266    * Returned Matrix = This Matrix * rhs
 267    *
 268    * @note It makes some memory allocate & copy internally.
 269    * Use Matrix3::Multiply API for time critical path.
 270    *
 271    * @SINCE_2_1.44
 272    * @param[in] rhs The Matrix to multiply this by
 273    * @return A Matrix containing the result
 274    */
 275   Matrix3 operator*(const Matrix3& rhs) const;
 276
 277   /**
 278    * @brief Multiplication assignment operator.
 279    *
 280    * This Matrix *= rhs
 281    *
 282    * @note It makes some memory allocate & copy internally.
 283    *
 284    * @SINCE_2_1.46
 285    * @param[in] rhs The Matrix to multiply this by
 286    * @return Itself
 287    */
 288   Matrix3& operator*=(const Matrix3& rhs);
 289
 290   /**
 291    * @brief The multiplication operator.
 292    *
 293    * Returned Vector = This Matrix * rhs
 294    *
 295    * @SINCE_2_1.34
 296    * @param[in] rhs The Vector3 to multiply this by
 297    * @return A Vector3 containing the result
 298    */
 299   Vector3 operator*(const Vector3& rhs) const;
 300
 301 private:
 302   float mElements[9]; ///< The elements of the matrix
 303 };
 304
 305 /**
 306  * @brief Prints a 3x3 matrix.
 307  *
 308  * @SINCE_1_0.0
 309  * @param[in] o The output stream operator
 310  * @param[in] matrix The matrix to print
 311  * @return The output stream operator
 312  */
 313 DALI_CORE_API std::ostream& operator<<(std::ostream& o, const Matrix3& matrix);
 314
 315 // Allow Matrix3 to be treated as a POD type
 316 template<>
 317 struct TypeTraits<Matrix3> : public BasicTypes<Matrix3>
 318 {
 319   enum
 320   {
 321     IS_TRIVIAL_TYPE = true
 322   };
 323 };
 324
 325 /**
 326  * @}
 327  */
 328 } // namespace Dali
 329
 330 #endif //DALI_MATRIX3_H