Merge "Update Math's public header comments" into devel/master
[platform/core/uifw/dali-core.git] / 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__