1 #ifndef __DALI_MATRIX_H__
2 #define __DALI_MATRIX_H__
5 * Copyright (c) 2018 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.
41 * The matrix is stored as a flat array and is Column Major, i.e. the storage order is as follows (numbers represent
53 * Each axis is contiguous in memory, so the x-axis corresponds to elements 0, 1, 2 and 3, the y-axis corresponds to
54 * elements 4, 5, 6, 7, the z-axis corresponds to elements 12, 13, 14 and 15, and the translation vector corresponds to
55 * elements 12, 13 and 14.
59 class DALI_CORE_API Matrix
63 friend DALI_CORE_API std::ostream& operator<< (std::ostream& o, const Matrix& matrix);
68 * Zero initializes the matrix.
77 * @param[in] initialize True for initialization by zero or otherwise
79 explicit Matrix( bool initialize );
84 * The matrix is initialized with the contents of 'array' which must contain 16 floats.
85 * The order of the values for a transform matrix is:
88 * [ xAxis.x, xAxis.y, xAxis.z, 0.0f, yAxis.x, yAxis.y, yAxis.z, 0.0f, zAxis.x, zAxis.y, zAxis.z, 0.0f, trans.x, trans.y, trans.z, 1.0f ]
92 * @param[in] array Pointer of 16 floats data
94 explicit Matrix(const float* array);
97 * @brief Constructs a matrix from quaternion.
100 * @param rotation Rotation as quaternion
102 explicit Matrix( const Quaternion& rotation );
105 * @brief Copy constructor.
108 * @param[in] matrix A reference to the copied matrix
110 Matrix( const Matrix& matrix );
113 * @brief Assignment operator.
116 * @param[in] matrix A reference to the copied matrix
117 * @return A reference to this
119 Matrix& operator=( const Matrix& matrix );
122 * @brief The identity matrix.
124 static const Matrix IDENTITY;
127 * @brief Sets this matrix to be an identity matrix.
133 * @brief Sets this matrix to be an identity matrix with scale.
136 * @param[in] scale Scale to set on top of identity matrix
138 void SetIdentityAndScale( const Vector3& scale );
141 * @brief Inverts a transform Matrix.
143 * Any Matrix representing only a rotation and/or translation
144 * can be inverted using this function. It is faster and more accurate then using Invert().
146 * @param[out] result The inverse of this matrix
148 void InvertTransform(Matrix& result) const;
151 * @brief Generic brute force Matrix Invert.
153 * Using the Matrix invert function for the specific type
154 * of matrix you are dealing with is faster, more accurate.
156 * @return True if successful
161 * @brief Swaps the rows to columns.
167 * @brief Returns the xAxis from a Transform matrix.
172 Vector3 GetXAxis() const;
175 * @brief Returns the yAxis from a Transform matrix.
180 Vector3 GetYAxis() const;
183 * @brief Returns the zAxis from a Transform matrix.
188 Vector3 GetZAxis() const;
191 * @brief Sets the x axis.
193 * This assumes the matrix is a transform matrix.
195 * @param[in] axis The values to set the axis to
197 void SetXAxis(const Vector3& axis);
200 * @brief Sets the y axis.
202 * This assumes the matrix is a transform matrix.
204 * @param[in] axis The values to set the axis to
206 void SetYAxis(const Vector3& axis);
209 * @brief Sets the z axis.
211 * This assumes the matrix is a transform matrix.
213 * @param[in] axis The values to set the axis to
215 void SetZAxis(const Vector3& axis);
218 * @brief Gets the translation.
220 * This assumes the matrix is a transform matrix.
222 * @return The translation
223 * @note inlined for performance reasons (generates less code than a function call)
225 const Vector4& GetTranslation() const { return reinterpret_cast<const Vector4&>(mMatrix[12]); }
228 * @brief Gets the x,y and z components of the translation as a Vector3.
230 * This assumes the matrix is a transform matrix.
232 * @return The translation
233 * @note inlined for performance reasons (generates less code than a function call)
235 const Vector3& GetTranslation3() const { return reinterpret_cast<const Vector3&>(mMatrix[12]); }
238 * @brief Sets the translation.
240 * This assumes the matrix is a transform matrix.
242 * @param[in] translation The translation
244 void SetTranslation(const Vector4& translation);
247 * @brief Sets the x,y and z components of the translation from a Vector3.
249 * This assumes the matrix is a transform matrix.
251 * @param[in] translation The translation
253 void SetTranslation(const Vector3& translation);
256 * @brief Makes the axes of the matrix orthogonal to each other and of unit length.
258 * This function is used to correct floating point errors which would otherwise accumulate
259 * as operations are applied to the matrix. This function assumes the matrix is a transform
263 void OrthoNormalize();
266 * @brief Returns the contents of the matrix as an array of 16 floats.
268 * The order of the values for a transform matrix is:
271 * [ xAxis.x, xAxis.y, xAxis.z, 0.0f, yAxis.x, yAxis.y, yAxis.z, 0.0f, zAxis.x, zAxis.y, zAxis.z, 0.0f, trans.x, trans.y, trans.z, 1.0f ]
275 * @return The matrix contents as an array of 16 floats
276 * @note inlined for performance reasons (generates less code than a function call)
278 const float* AsFloat() const {return mMatrix;}
281 * @brief Returns the contents of the matrix as an array of 16 floats.
283 * The order of the values for a transform matrix is:
286 * [ xAxis.x, xAxis.y, xAxis.z, 0.0f, yAxis.x, yAxis.y, yAxis.z, 0.0f, zAxis.x, zAxis.y, zAxis.z, 0.0f, trans.x, trans.y, trans.z, 1.0f ]
290 * @return The matrix contents as an array of 16 floats
291 * @note inlined for performance reasons (generates less code than a function call)
293 float* AsFloat() {return mMatrix;}
296 * @brief Function to multiply two matrices and store the result onto third.
298 * Use this method in time critical path as it does not require temporaries.
303 * @param[out] result Result of the multiplication
304 * @param[in] lhs Matrix, this can be same matrix as result
305 * @param[in] rhs Matrix, this cannot be same matrix as result
307 static void Multiply( Matrix& result, const Matrix& lhs, const Matrix& rhs );
310 * @brief Function to multiply a matrix and quaternion and store the result onto third.
312 * Use this method in time critical path as it does not require temporaries.
314 * @param[out] result Result of the multiplication
315 * @param[in] lhs Matrix, this can be same matrix as result
316 * @param[in] rhs Quaternion
318 static void Multiply( Matrix& result, const Matrix& lhs, const Quaternion& rhs );
321 * @brief The multiplication operator.
323 * Returned Vector = This Matrix * rhs
326 * @param[in] rhs The Vector4 to multiply this by
327 * @return A Vector4 containing the result
329 Vector4 operator*(const Vector4& rhs) const;
332 * @brief The equality operator.
334 * Utilizes appropriate machine epsilon values.
337 * @param[in] rhs The Matrix to compare this to
338 * @return true if the matrices are equal
340 bool operator==(const Matrix & rhs) const;
343 * @brief The inequality operator.
345 * Utilizes appropriate machine epsilon values.
347 * @param[in] rhs The Matrix to compare this to
348 * @return true if the matrices are not equal.
350 bool operator!=(const Matrix & rhs) const;
353 * @brief Sets this matrix to contain the position, scale and rotation components.
355 * Performs scale, rotation, then translation
357 * @param[in] scale Scale to apply
358 * @param[in] rotation Rotation to apply
359 * @param[in] translation Translation to apply
361 void SetTransformComponents(const Vector3& scale,
362 const Quaternion& rotation,
363 const Vector3& translation );
366 * @brief Sets this matrix to contain the inverse of the position, scale and rotation components.
368 * Performs translation, then rotation, then scale.
370 * @param[in] scale Scale to apply
371 * @param[in] rotation Rotation to apply
372 * @param[in] translation Translation to apply
374 void SetInverseTransformComponents(const Vector3& scale,
375 const Quaternion& rotation,
376 const Vector3& translation );
380 * @brief Sets this matrix to contain the inverse of the orthonormal basis and position components.
382 * Performs translation, then rotation.
384 * @param[in] xAxis The X axis of the basis
385 * @param[in] yAxis The Y axis of the basis
386 * @param[in] zAxis The Z axis of the basis
387 * @param[in] translation Translation to apply
389 void SetInverseTransformComponents(const Vector3& xAxis,
390 const Vector3& yAxis,
391 const Vector3& zAxis,
392 const Vector3& translation );
395 * @brief Gets the position, scale and rotation components from the given transform matrix.
398 * @param[out] position Position to set
399 * @param[out] rotation Rotation to set - only valid if the transform matrix has not been skewed or sheared
400 * @param[out] scale Scale to set - only valid if the transform matrix has not been skewed or sheared
401 * @pre This matrix must not contain skews or shears.
403 void GetTransformComponents(Vector3& position,
404 Quaternion& rotation,
405 Vector3& scale) const;
409 float mMatrix[16]; ///< The elements of the matrix
413 * @brief Prints a matrix.
415 * It is printed in memory order.
417 * @param[in] o The output stream operator
418 * @param[in] matrix The matrix to print
419 * @return The output stream operator
421 DALI_CORE_API std::ostream& operator<< (std::ostream& o, const Matrix& matrix);
423 // Allow Matrix to be treated as a POD type
424 template <> struct TypeTraits< Matrix > : public BasicTypes< Matrix > { enum { IS_TRIVIAL_TYPE = true }; };
431 #endif // __DALI_MATRIX_H__