dali/public-api/math/matrix3.h

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