1 #ifndef __DALI_MATRIX_H__
2 #define __DALI_MATRIX_H__
5 * Copyright (c) 2015 Samsung Electronics Co., Ltd.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
25 #include <dali/public-api/common/dali-common.h>
26 #include <dali/public-api/common/type-traits.h>
27 #include <dali/public-api/math/vector4.h>
32 * @addtogroup dali_core_math
39 * @brief The Matrix class represents transformations and projections.
40 * It is agnostic w.r.t. row/column major notation - it operates on a flat array.
41 * 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.
43 class DALI_IMPORT_API Matrix
47 friend std::ostream& operator<< (std::ostream& o, const Matrix& matrix);
52 * Zero initialises the matrix
59 * @param initialize to zero or leave uninitialized
61 explicit Matrix( bool initialize );
66 * The matrix is initialised with the contents of 'array' which must contain 16 floats.
67 * The order of the values for a transform matrix is:
69 * xAxis.x xAxis.y xAxis.z 0.0f
70 * yAxis.x yAxis.y yAxis.z 0.0f
71 * zAxis.x zAxis.y zAxis.z 0.0f
72 * trans.x trans.y trans.z 1.0f
74 * @param [in] array 16 floats
76 explicit Matrix(const float* array);
79 * @brief Constructs a matrix from quaternion.
81 * @param rotation as quaternion
83 explicit Matrix( const Quaternion& rotation );
86 * @brief Copy constructor.
88 * @param [in] matrix to copy values from
90 Matrix( const Matrix& matrix );
93 * @brief Assignment operator.
95 * @param [in] matrix to copy values from
96 * @return a reference to this
98 Matrix& operator=( const Matrix& matrix );
101 * @brief The identity matrix.
103 static const Matrix IDENTITY;
106 * @brief Sets this matrix to be an identity matrix.
111 * @brief Sets this matrix to be an identity matrix with scale.
113 * @param scale to set on top of identity matrix
115 void SetIdentityAndScale( const Vector3& scale );
118 * @brief Invert a transform Matrix.
120 * Any Matrix representing only a rotation and/or translation
121 * can be inverted using this function. It is faster and more accurate then using Invert().
122 * @param [out] result returns the inverse of this matrix
124 void InvertTransform(Matrix& result) const;
127 * @brief Generic brute force Matrix Invert.
129 * Using the Matrix invert function for the specific type
130 * of matrix you are dealing with is faster, more accurate.
131 * @return true if successful
136 * @brief Swaps the rows to columns.
141 * @brief Returns the xAxis from a Transform matrix.
145 Vector3 GetXAxis() const;
148 * @brief Returns the yAxis from a Transform matrix.
152 Vector3 GetYAxis() const;
155 * @brief Returns the zAxis from a Transform matrix.
159 Vector3 GetZAxis() const;
162 * @brief Sets the x axis.
164 * This assumes the matrix is a transform matrix.
165 * @param [in] axis the values to set the axis to
167 void SetXAxis(const Vector3& axis);
170 * @brief Sets the y axis.
172 * This assumes the matrix is a transform matrix.
173 * @param [in] axis the values to set the axis to
175 void SetYAxis(const Vector3& axis);
178 * @brief Sets the z axis.
180 * This assumes the matrix is a transform matrix.
181 * @param [in] axis the values to set the axis to
183 void SetZAxis(const Vector3& axis);
186 * @brief Gets the translation.
188 * This assumes the matrix is a transform matrix.
189 * @note inlined for performance reasons (generates less code than a function call)
190 * @return the translation
192 const Vector4& GetTranslation() const { return reinterpret_cast<const Vector4&>(mMatrix[12]); }
195 * @brief Gets the x,y and z components of the translation as a Vector3.
197 * This assumes the matrix is a transform matrix.
198 * @note inlined for performance reasons (generates less code than a function call)
199 * @return the translation
201 const Vector3& GetTranslation3() const { return reinterpret_cast<const Vector3&>(mMatrix[12]); }
204 * @brief Sets the translation.
206 * This assumes the matrix is a transform matrix.
207 * @param [in] translation the translation
209 void SetTranslation(const Vector4& translation);
212 * @brief Sets the x,y and z components of the translation from a Vector3.
214 * This assumes the matrix is a transform matrix.
215 * @param [in] translation the translation
217 void SetTranslation(const Vector3& translation);
220 * @brief Makes the axes of the matrix orthogonal to each other and of unit length.
222 * This function is used to correct floating point errors which would otherwise accumulate
223 * as operations are applied to the matrix. This function assumes the matrix is a transform
226 void OrthoNormalize();
229 * @brief Returns the contents of the matrix as an array of 16 floats.
231 * The order of the values for a transform matrix is:
232 * xAxis.x xAxis.y xAxis.z 0.0f
233 * yAxis.x yAxis.y yAxis.z 0.0f
234 * zAxis.x zAxis.y zAxis.z 0.0f
235 * trans.x trans.y trans.z 1.0f
236 * @note inlined for performance reasons (generates less code than a function call)
237 * @return the matrix contents as an array of 16 floats.
239 const float* AsFloat() const {return mMatrix;}
242 * @brief Returns the contents of the matrix as an array of 16 floats.
244 * The order of the values for a transform matrix is:
246 * xAxis.x xAxis.y xAxis.z 0.0f
247 * yAxis.x yAxis.y yAxis.z 0.0f
248 * zAxis.x zAxis.y zAxis.z 0.0f
249 * trans.x trans.y trans.z 1.0f
250 * @note inlined for performance reasons (generates less code than a function call)
251 * @return the matrix contents as an array of 16 floats.
253 float* AsFloat() {return mMatrix;}
256 * @brief Function to multiply two matrices and store the result onto third.
258 * Use this method in time critical path as it does not require temporaries
259 * @param result of the multiplication
260 * @param lhs matrix, this can be same matrix as result
261 * @param rhs matrix, this cannot be same matrix as result
263 static void Multiply( Matrix& result, const Matrix& lhs, const Matrix& rhs );
266 * @brief Function to multiply a matrix and quaternion and store the result onto third.
268 * Use this method in time critical path as it does not require temporaries
269 * @param result of the multiplication
270 * @param lhs matrix, this can be same matrix as result
271 * @param rhs quaternion
273 static void Multiply( Matrix& result, const Matrix& lhs, const Quaternion& rhs );
276 * @brief The multiplication operator.
278 * @param [in] rhs the Matrix to multiply this by
279 * @return A matrix containing the result
281 Vector4 operator*(const Vector4& rhs) const;
284 * @brief The equality operator.
286 * Utilises appropriate machine epsilon values.
288 * @param [in] rhs the Matrix to compare this to
289 * @return true if the matrices are equal
291 bool operator==(const Matrix & rhs) const;
294 * @brief The inequality operator.
296 * Utilises appropriate machine epsilon values.
297 * @param [in] rhs the Matrix to compare this to
298 * @return true if the matrices are not equal.
300 bool operator!=(const Matrix & rhs) const;
303 * @brief Sets this matrix to contain the position, scale and rotation components.
305 * Performs scale, rotation, then translation
306 * @param[in] scale to apply
307 * @param[in] rotation to apply
308 * @param[in] translation to apply
310 void SetTransformComponents(const Vector3& scale,
311 const Quaternion& rotation,
312 const Vector3& translation );
315 * @brief Sets this matrix to contain the inverse of the position, scale and rotation components.
317 * Performs translation, then rotation, then scale.
318 * @param[in] scale to apply
319 * @param[in] rotation to apply
320 * @param[in] translation to apply
322 void SetInverseTransformComponents(const Vector3& scale,
323 const Quaternion& rotation,
324 const Vector3& translation );
328 * @brief Sets this matrix to contain the inverse of the orthonormal basis and position components.
330 * Performs translation, then rotation.
331 * @param[in] xAxis The X axis of the basis
332 * @param[in] yAxis The Y axis of the basis
333 * @param[in] zAxis The Z axis of the basis
334 * @param[in] translation to apply
336 void SetInverseTransformComponents(const Vector3& xAxis,
337 const Vector3& yAxis,
338 const Vector3& zAxis,
339 const Vector3& translation );
342 * @brief Gets the position, scale and rotation components from the given transform matrix.
344 * @pre This matrix must not contain skews or shears.
345 * @param[out] position to set
346 * @param[out] rotation to set - only valid if the transform matrix has not been skewed or sheared
347 * @param[out] scale to set - only valid if the transform matrix has not been skewed or sheared
349 void GetTransformComponents(Vector3& position,
350 Quaternion& rotation,
351 Vector3& scale) const;
355 float mMatrix[16]; ///< The elements of the matrix
359 * @brief Print a matrix.
361 * It is printed in memory order, i.e. each printed row is contiguous in memory.
362 * @param [in] o The output stream operator.
363 * @param [in] matrix The matrix to print.
364 * @return The output stream operator.
366 DALI_IMPORT_API std::ostream& operator<< (std::ostream& o, const Matrix& matrix);
368 // Allow Matrix to be treated as a POD type
369 template <> struct TypeTraits< Matrix > : public BasicTypes< Matrix > { enum { IS_TRIVIAL_TYPE = true }; };
376 #endif // __DALI_MATRIX_H__