1 #ifndef __DALI_MATRIX_H__
2 #define __DALI_MATRIX_H__
5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
7 // Licensed under the Flora License, Version 1.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
11 // http://floralicense.org/license/
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.
21 * @addtogroup CAPI_DALI_MATH_MODULE
29 #include <dali/public-api/math/vector4.h>
31 namespace Dali DALI_IMPORT_API
36 * @brief The Matrix class represents transformations and projections.
37 * It is agnostic w.r.t. row/column major notation - it operates on a flat array.
38 * Each axis is contiguous in memory, so the x axis corresponds to elements 0, 1, 2 and 3, the y axis dorresponds to elements 4, 5, 6, 7, etc.
40 class DALI_IMPORT_API Matrix
44 friend std::ostream& operator<< (std::ostream& o, const Matrix& matrix);
49 * Zero initialises the matrix
56 * @param initialize to zero or leave uninitialized
58 explicit Matrix( bool initialize );
63 * The matrix is initialised with the contents of 'array' which must contain 16 floats.
64 * The order of the values for a transform matrix is:
66 * xAxis.x xAxis.y xAxis.z 0.0f
67 * yAxis.x yAxis.y yAxis.z 0.0f
68 * zAxis.x zAxis.y zAxis.z 0.0f
69 * trans.x trans.y trans.z 1.0f
71 * @param [in] array 16 floats
73 explicit Matrix(const float* array);
76 * @brief Constructs a matrix from quaternion.
78 * @param rotation as quaternion
80 explicit Matrix( const Quaternion& rotation );
83 * @brief Copy constructor.
85 * @param [in] matrix to copy values from
87 Matrix( const Matrix& matrix );
90 * @brief Assignment operator.
92 * @param [in] matrix to copy values from
93 * @return a reference to this
95 Matrix& operator=( const Matrix& matrix );
98 * @brief The identity matrix.
100 static const Matrix IDENTITY;
103 * @brief Sets this matrix to be an identity matrix.
108 * @brief Sets this matrix to be an identity matrix with scale.
110 * @param scale to set on top of identity matrix
112 void SetIdentityAndScale( const Vector3& scale );
115 * @brief Invert a transform Matrix.
117 * Any Matrix representing only a rotation and/or translation
118 * can be inverted using this function. It is faster and more accurate then using Invert().
119 * @param [out] result returns the inverse of this matrix
121 void InvertTransform(Matrix& result) const;
124 * @brief Generic brute force Matrix Invert.
126 * Using the Matrix invert function for the specific type
127 * of matrix you are dealing with is faster, more accurate.
128 * @return true if successful
133 * @brief Swaps the rows to columns.
138 * @brief Returns the xAxis from a Transform matrix.
142 Vector3 GetXAxis() const;
145 * @brief Returns the yAxis from a Transform matrix.
149 Vector3 GetYAxis() const;
152 * @brief Returns the zAxis from a Transform matrix.
156 Vector3 GetZAxis() const;
159 * @brief Sets the x axis.
161 * This assumes the matrix is a transform matrix.
162 * @param [in] axis the values to set the axis to
164 void SetXAxis(const Vector3& axis);
167 * @brief Sets the y axis.
169 * This assumes the matrix is a transform matrix.
170 * @param [in] axis the values to set the axis to
172 void SetYAxis(const Vector3& axis);
175 * @brief Sets the z axis.
177 * This assumes the matrix is a transform matrix.
178 * @param [in] axis the values to set the axis to
180 void SetZAxis(const Vector3& axis);
183 * @brief Gets the translation.
185 * This assumes the matrix is a transform matrix.
186 * @note inlined for performance reasons (generates less code than a function call)
187 * @return the translation
189 const Vector4& GetTranslation() const { return reinterpret_cast<const Vector4&>(mMatrix[12]); }
192 * @brief Gets the x,y and z components of the translation as a Vector3.
194 * This assumes the matrix is a transform matrix.
195 * @note inlined for performance reasons (generates less code than a function call)
196 * @return the translation
198 const Vector3& GetTranslation3() const { return reinterpret_cast<const Vector3&>(mMatrix[12]); }
201 * @brief Sets the translation.
203 * This assumes the matrix is a transform matrix.
204 * @param [in] translation the translation
206 void SetTranslation(const Vector4& translation);
209 * @brief Sets the x,y and z components of the translation from a Vector3.
211 * This assumes the matrix is a transform matrix.
212 * @param [in] translation the translation
214 void SetTranslation(const Vector3& translation);
217 * @brief Makes the axes of the matrix orthogonal to each other and of unit length.
219 * This function is used to correct floating point errors which would otherwise accumulate
220 * as operations are applied to the matrix. This function assumes the matrix is a transform
223 void OrthoNormalize();
226 * @brief Returns the contents of the matrix as an array of 16 floats.
228 * The order of the values for a transform matrix is:
229 * xAxis.x xAxis.y xAxis.z 0.0f
230 * yAxis.x yAxis.y yAxis.z 0.0f
231 * zAxis.x zAxis.y zAxis.z 0.0f
232 * trans.x trans.y trans.z 1.0f
233 * @note inlined for performance reasons (generates less code than a function call)
234 * @return the matrix contents as an array of 16 floats.
236 const float* AsFloat() const {return mMatrix;}
239 * @brief Returns the contents of the matrix as an array of 16 floats.
241 * The order of the values for a transform matrix is:
243 * xAxis.x xAxis.y xAxis.z 0.0f
244 * yAxis.x yAxis.y yAxis.z 0.0f
245 * zAxis.x zAxis.y zAxis.z 0.0f
246 * trans.x trans.y trans.z 1.0f
247 * @note inlined for performance reasons (generates less code than a function call)
248 * @return the matrix contents as an array of 16 floats.
250 float* AsFloat() {return mMatrix;}
253 * @brief Function to multiply two matrices and store the result onto third.
255 * Use this method in time critical path as it does not require temporaries
256 * @param result of the multiplication
257 * @param lhs matrix, this can be same matrix as result
258 * @param rhs matrix, this cannot be same matrix as result
260 static void Multiply( Matrix& result, const Matrix& lhs, const Matrix& rhs );
263 * @brief Function to multiply a matrix and quaternion and store the result onto third.
265 * Use this method in time critical path as it does not require temporaries
266 * @param result of the multiplication
267 * @param lhs matrix, this can be same matrix as result
268 * @param rhs quaternion
270 static void Multiply( Matrix& result, const Matrix& lhs, const Quaternion& rhs );
273 * @brief The multiplication operator.
275 * @param [in] rhs the Matrix to multiply this by
276 * @return A matrix containing the result
278 Vector4 operator*(const Vector4& rhs) const;
281 * @brief The equality operator.
283 * Utilises appropriate machine epsilon values.
285 * @param [in] rhs the Matrix to compare this to
286 * @return true if the matrices are equal
288 bool operator==(const Matrix & rhs) const;
291 * @brief The inequality operator.
293 * Utilises appropriate machine epsilon values.
294 * @param [in] rhs the Matrix to compare this to
295 * @return true if the matrices are not equal.
297 bool operator!=(const Matrix & rhs) const;
300 * @brief Sets this matrix to contain the position, scale and rotation components.
302 * Performs scale, rotation, then translation
303 * @param[in] scale to apply
304 * @param[in] rotation to apply
305 * @param[in] translation to apply
307 void SetTransformComponents(const Vector3& scale,
308 const Quaternion& rotation,
309 const Vector3& translation );
312 * @brief Sets this matrix to contain the inverse of the position, scale and rotation components.
314 * Performs translation, then rotation, then scale.
315 * @param[in] scale to apply
316 * @param[in] rotation to apply
317 * @param[in] translation to apply
319 void SetInverseTransformComponents(const Vector3& scale,
320 const Quaternion& rotation,
321 const Vector3& translation );
325 * @brief Sets this matrix to contain the inverse of the orthonormal basis and position components.
327 * Performs translation, then rotation.
328 * @param[in] xAxis The X axis of the basis
329 * @param[in] yAxis The Y axis of the basis
330 * @param[in] zAxis The Z axis of the basis
331 * @param[in] translation to apply
333 void SetInverseTransformComponents(const Vector3& xAxis,
334 const Vector3& yAxis,
335 const Vector3& zAxis,
336 const Vector3& translation );
339 * @brief Gets the position, scale and rotation components from the given transform matrix.
341 * @pre This matrix must not contain skews or shears.
342 * @param[out] position to set
343 * @param[out] rotation to set - only valid if the transform matrix has not been skewed or sheared
344 * @param[out] scale to set - only valid if the transform matrix has not been skewed or sheared
346 void GetTransformComponents(Vector3& position,
347 Quaternion& rotation,
348 Vector3& scale) const;
352 float mMatrix[16]; ///< The elements of the matrix
356 * @brief Print a matrix.
358 * It is printed in memory order, i.e. each printed row is contiguous in memory.
359 * @param [in] o The output stream operator.
360 * @param [in] matrix The matrix to print.
361 * @return The output stream operator.
363 DALI_IMPORT_API std::ostream& operator<< (std::ostream& o, const Matrix& matrix);
370 #endif // __DALI_MATRIX_H__