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/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 DALI_CORE_API 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 Move constructor.
 106    *
 107    * @SINCE_1_9.21
 108    * @param[in] matrix A reference to the moved matrix
 109    */
 110   Matrix3( Matrix3&& matrix );
 111
 112   /**
 113    * @brief Move assignment operator.
 114    *
 115    * @SINCE_1_9.21
 116    * @param[in] matrix A reference to the moved matrix
 117    * @return A reference to this
 118    */
 119   Matrix3& operator=( Matrix3&& matrix );
 120
 121   /**
 122    * @brief Assignment Operator.
 123    * @SINCE_1_0.0
 124    * @param[in] matrix From which to copy values
 125    * @return Reference to this object
 126    */
 127   Matrix3& operator=( const Matrix3& matrix );
 128
 129   /**
 130    * @brief Assignment Operator.
 131    * @SINCE_1_0.0
 132    * @param[in] matrix A reference to the copied matrix
 133    * @return A reference to this
 134    */
 135   Matrix3& operator=( const Matrix& matrix );
 136
 137   /**
 138    * @brief The equality operator.
 139    *
 140    * Utilizes appropriate machine epsilon values.
 141    *
 142    * @SINCE_1_0.0
 143    * @param[in] rhs The Matrix to compare this to
 144    * @return True if the matrices are equal
 145    */
 146   bool operator==(const Matrix3 & rhs) const;
 147
 148   /**
 149    * @brief The inequality operator.
 150    *
 151    * Utilizes appropriate machine epsilon values.
 152    *
 153    * @SINCE_1_0.0
 154    * @param[in] rhs The Matrix to compare this to
 155    * @return true if the matrices are equal
 156    */
 157   bool operator!=(const Matrix3 & rhs) const;
 158
 159   /**
 160    * @brief Destructor.
 161    * @SINCE_1_0.0
 162    */
 163   ~Matrix3()
 164   {
 165   }
 166
 167   /**
 168    * @brief Sets the matrix to the identity matrix.
 169    * @SINCE_1_0.0
 170    */
 171   void SetIdentity();
 172
 173   /**
 174    * @brief Returns the contents of the matrix as an array of 9 floats.
 175    *
 176    * The order of the values for a matrix is:
 177    *
 178    * @code
 179    * [ xAxis.x, xAxis.y, xAxis.z, yAxis.x, yAxis.y, yAxis.z, zAxis.x, zAxis.y, zAxis.z ]
 180    * @endcode
 181    *
 182    * @SINCE_1_0.0
 183    * @return The matrix contents as an array of 9 floats
 184    */
 185   const float* AsFloat() const {return &mElements[0];}
 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() {return &mElements[0];}
 200
 201   /**
 202    * @brief Inverts the matrix.
 203    *
 204    * @SINCE_1_0.0
 205    * @return True if successful
 206    */
 207   bool Invert();
 208
 209   /**
 210    * @brief Swaps the rows to columns.
 211    * @SINCE_1_0.0
 212    * @return True if successful
 213    */
 214   bool Transpose();
 215
 216   /**
 217    * @brief Multiplies all elements of the matrix by the scale value.
 218    *
 219    * @SINCE_1_0.0
 220    * @param[in] scale The value by which to scale the whole matrix
 221    */
 222   void Scale(float scale);
 223
 224   /**
 225    * @brief Magnitude returns the average of the absolute values of the
 226    * elements * 3.
 227    *
 228    * (The Magnitude of the unit matrix is therefore 1)
 229    * @SINCE_1_0.0
 230    * @return The magnitude - always positive
 231    */
 232   float Magnitude() const;
 233
 234   /**
 235    * @brief If the matrix is invertible, then this method inverts, transposes
 236    * and scales the matrix such that the resultant element values
 237    * average 1.
 238    *
 239    * If the matrix is not invertible, then the matrix is left unchanged.
 240    *
 241    * @SINCE_1_0.0
 242    * @return @c true if the matrix is invertible, otherwise @c false
 243    */
 244   bool ScaledInverseTranspose();
 245
 246   /**
 247    * @brief Function to multiply two matrices and store the result onto third.
 248    *
 249    * Use this method in time critical path as it does not require temporaries
 250    *
 251    * result = rhs * lhs
 252    *
 253    * @SINCE_1_0.0
 254    * @param[out] result Result of the multiplication
 255    * @param[in] lhs Matrix, this can be same matrix as result
 256    * @param[in] rhs Matrix, this cannot be same matrix as result
 257    */
 258   static void Multiply( Matrix3& result, const Matrix3& lhs, const Matrix3& rhs );
 259
 260 private:
 261
 262   float mElements[9]; ///< The elements of the matrix
 263 };
 264
 265 /**
 266  * @brief Prints a 3x3 matrix.
 267  *
 268  * @SINCE_1_0.0
 269  * @param[in] o The output stream operator
 270  * @param[in] matrix The matrix to print
 271  * @return The output stream operator
 272  */
 273 DALI_CORE_API std::ostream& operator<< (std::ostream& o, const Matrix3& matrix);
 274
 275 // Allow Matrix3 to be treated as a POD type
 276 template <> struct TypeTraits< Matrix3 > : public BasicTypes< Matrix3 > { enum { IS_TRIVIAL_TYPE = true }; };
 277
 278 /**
 279  * @}
 280  */
 281 } // namespace Dali
 282
 283 #endif //DALI_MATRIX3_H