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 Another 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 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 matrix from which to copy values
 102    * @return reference to this object
 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    *   xAxis.x yAxis.x zAxis.x
 147    *   xAxis.y yAxis.y zAxis.y
 148    *   xAxis.z yAxis.z zAxis.z
 149    * @SINCE_1_0.0
 150    * @return the matrix contents as an array of 9 floats.
 151    */
 152   const float* AsFloat() const {return &mElements[0];}
 153
 154   /**
 155    * @brief Returns the contents of the matrix as an array of 9 floats.
 156    *
 157    * The order of the values for a matrix is:
 158    *   xAxis.x yAxis.x zAxis.x
 159    *   xAxis.y yAxis.y zAxis.y
 160    *   xAxis.z yAxis.z zAxis.z
 161    * @SINCE_1_0.0
 162    * @return the matrix contents as an array of 9 floats.
 163    */
 164   float* AsFloat() {return &mElements[0];}
 165
 166   /**
 167    * @brief Inverts the matrix.
 168    *
 169    * @SINCE_1_0.0
 170    * @return true if successful
 171    */
 172   bool Invert();
 173
 174   /**
 175    * @brief Swaps the rows to columns
 176    * @SINCE_1_0.0
 177    * @return true
 178    */
 179   bool Transpose();
 180
 181   /**
 182    * @brief Multiplies all elements of the matrix by the scale value.
 183    *
 184    * @SINCE_1_0.0
 185    * @param scale - the value by which to scale the whole matrix.
 186    *
 187    */
 188   void Scale(float scale);
 189
 190   /**
 191    * @brief Magnitude returns the average of the absolute values of the
 192    * elements * 3.
 193    *
 194    * (The Magnitude of the unit matrix is therefore 1)
 195    * @SINCE_1_0.0
 196    * @return the magnitude - always positive.
 197    */
 198   float Magnitude() const;
 199
 200   /**
 201    * @brief If the matrix is invertible, then this method inverts, transposes
 202    * and scales the matrix such that the resultant element values
 203    * average 1.
 204    *
 205    * If the matrix is not invertible, then the matrix is left unchanged.
 206    *
 207    * @SINCE_1_0.0
 208    * @return true if the matrix is invertible, otherwise false
 209    */
 210   bool ScaledInverseTranspose();
 211
 212   /**
 213    * @brief Function to multiply two matrices and store the result onto third.
 214    *
 215    * Use this method in time critical path as it does not require temporaries
 216    * @SINCE_1_0.0
 217    * @param result of the multiplication
 218    * @param lhs matrix, this can be same matrix as result
 219    * @param rhs matrix, this cannot be same matrix as result
 220    */
 221   static void Multiply( Matrix3& result, const Matrix3& lhs, const Matrix3& rhs );
 222
 223 private:
 224
 225   float mElements[9]; ///< The elements of the matrix
 226 };
 227
 228 /**
 229  * @brief Print a 3x3 matrix.
 230  *
 231  * @SINCE_1_0.0
 232  * @param [in] o The output stream operator.
 233  * @param [in] matrix The matrix to print.
 234  * @return The output stream operator.
 235  */
 236 DALI_IMPORT_API std::ostream& operator<< (std::ostream& o, const Matrix3& matrix);
 237
 238 // Allow Matrix3 to be treated as a POD type
 239 template <> struct TypeTraits< Matrix3 > : public BasicTypes< Matrix3 > { enum { IS_TRIVIAL_TYPE = true }; };
 240
 241 /**
 242  * @}
 243  */
 244 } // namespace Dali
 245
 246 #endif //__DALI_MATRIX3_H__