-#ifndef __DALI_MATRIX_H__
-#define __DALI_MATRIX_H__
+#ifndef DALI_MATRIX_H
+#define DALI_MATRIX_H
/*
- * Copyright (c) 2014 Samsung Electronics Co., Ltd.
+ * Copyright (c) 2023 Samsung Electronics Co., Ltd.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
*/
// EXTERNAL INCLUDES
-#include <ostream>
+#include <iosfwd>
// INTERNAL INCLUDES
#include <dali/public-api/common/dali-common.h>
+#include <dali/public-api/common/type-traits.h>
#include <dali/public-api/math/vector4.h>
namespace Dali
{
+/**
+ * @addtogroup dali_core_math
+ * @{
+ */
+
class Quaternion;
/**
* @brief The Matrix class represents transformations and projections.
- * It is agnostic w.r.t. row/column major notation - it operates on a flat array.
- * 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.
+ *
+ * The matrix is stored as a flat array and is Column Major, i.e. the storage order is as follows (numbers represent
+ * indices of array):
+ *
+ * @code
+ *
+ * 0 4 8 12
+ * 1 5 9 13
+ * 2 6 10 14
+ * 3 7 11 15
+ *
+ * @endcode
+ *
+ * Each axis is contiguous in memory, so the x-axis corresponds to elements 0, 1, 2 and 3, the y-axis corresponds to
+ * elements 4, 5, 6, 7, the z-axis corresponds to elements 12, 13, 14 and 15, and the translation vector corresponds to
+ * elements 12, 13 and 14.
+ *
+ * @SINCE_1_0.0
*/
-class DALI_IMPORT_API Matrix
+class DALI_CORE_API Matrix
{
public:
-
- friend std::ostream& operator<< (std::ostream& o, const Matrix& matrix);
+ friend DALI_CORE_API std::ostream& operator<<(std::ostream& o, const Matrix& matrix);
/**
* @brief Constructor.
*
- * Zero initialises the matrix
+ * Zero initializes the matrix.
+ * @SINCE_1_0.0
*/
Matrix();
/**
* @brief Constructor.
*
- * @param initialize to zero or leave uninitialized
+ * @SINCE_1_0.0
+ * @param[in] initialize True for initialization by zero or otherwise
*/
- explicit Matrix( bool initialize );
+ explicit Matrix(bool initialize);
/**
- * @brief Constructor
+ * @brief Constructor.
*
- * The matrix is initialised with the contents of 'array' which must contain 16 floats.
+ * The matrix is initialized with the contents of 'array' which must contain 16 floats.
* The order of the values for a transform matrix is:
*
- * 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
+ * @code
+ * [ 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 ]
+ * @endcode
*
- * @param [in] array 16 floats
+ * @SINCE_1_0.0
+ * @param[in] array Pointer of 16 floats data
*/
explicit Matrix(const float* array);
/**
* @brief Constructs a matrix from quaternion.
*
- * @param rotation as quaternion
+ * @SINCE_1_0.0
+ * @param rotation Rotation as quaternion
*/
- explicit Matrix( const Quaternion& rotation );
+ explicit Matrix(const Quaternion& rotation);
/**
* @brief Copy constructor.
*
- * @param [in] matrix to copy values from
+ * @SINCE_1_0.0
+ * @param[in] matrix A reference to the copied matrix
*/
- Matrix( const Matrix& matrix );
+ Matrix(const Matrix& matrix);
/**
* @brief Assignment operator.
*
- * @param [in] matrix to copy values from
- * @return a reference to this
+ * @SINCE_1_0.0
+ * @param[in] matrix A reference to the copied matrix
+ * @return A reference to this
*/
- Matrix& operator=( const Matrix& matrix );
+ Matrix& operator=(const Matrix& matrix);
+
+ /**
+ * @brief Move constructor.
+ *
+ * @SINCE_1_9.21
+ * @param[in] matrix A reference to the moved matrix
+ */
+ Matrix(Matrix&& matrix) noexcept;
+
+ /**
+ * @brief Move assignment operator.
+ *
+ * @SINCE_1_9.21
+ * @param[in] matrix A reference to the moved matrix
+ * @return A reference to this
+ */
+ Matrix& operator=(Matrix&& matrix) noexcept;
/**
* @brief The identity matrix.
/**
* @brief Sets this matrix to be an identity matrix.
+ * @SINCE_1_0.0
*/
void SetIdentity();
/**
* @brief Sets this matrix to be an identity matrix with scale.
*
- * @param scale to set on top of identity matrix
+ * @SINCE_1_0.0
+ * @param[in] scale Scale to set on top of identity matrix
*/
- void SetIdentityAndScale( const Vector3& scale );
+ void SetIdentityAndScale(const Vector3& scale);
/**
- * @brief Invert a transform Matrix.
+ * @brief Inverts a transform Matrix.
*
* Any Matrix representing only a rotation and/or translation
* can be inverted using this function. It is faster and more accurate then using Invert().
- * @param [out] result returns the inverse of this matrix
+ * @SINCE_1_0.0
+ * @param[out] result The inverse of this matrix
*/
void InvertTransform(Matrix& result) const;
*
* Using the Matrix invert function for the specific type
* of matrix you are dealing with is faster, more accurate.
- * @return true if successful
+ * @SINCE_1_0.0
+ * @return True if successful
*/
bool Invert();
/**
* @brief Swaps the rows to columns.
+ * @SINCE_1_0.0
*/
void Transpose();
/**
* @brief Returns the xAxis from a Transform matrix.
*
- * @return the x axis
+ * @SINCE_1_0.0
+ * @return The x axis
*/
Vector3 GetXAxis() const;
/**
* @brief Returns the yAxis from a Transform matrix.
*
- * @return the y axis
+ * @SINCE_1_0.0
+ * @return The y axis
*/
Vector3 GetYAxis() const;
/**
* @brief Returns the zAxis from a Transform matrix.
*
- * @return the z axis
+ * @SINCE_1_0.0
+ * @return The z axis
*/
Vector3 GetZAxis() const;
* @brief Sets the x axis.
*
* This assumes the matrix is a transform matrix.
- * @param [in] axis the values to set the axis to
+ * @SINCE_1_0.0
+ * @param[in] axis The values to set the axis to
*/
void SetXAxis(const Vector3& axis);
* @brief Sets the y axis.
*
* This assumes the matrix is a transform matrix.
- * @param [in] axis the values to set the axis to
+ * @SINCE_1_0.0
+ * @param[in] axis The values to set the axis to
*/
void SetYAxis(const Vector3& axis);
* @brief Sets the z axis.
*
* This assumes the matrix is a transform matrix.
- * @param [in] axis the values to set the axis to
+ * @SINCE_1_0.0
+ * @param[in] axis The values to set the axis to
*/
void SetZAxis(const Vector3& axis);
* @brief Gets the translation.
*
* This assumes the matrix is a transform matrix.
+ * @SINCE_1_0.0
+ * @return The translation
* @note inlined for performance reasons (generates less code than a function call)
- * @return the translation
*/
- const Vector4& GetTranslation() const { return reinterpret_cast<const Vector4&>(mMatrix[12]); }
+ const Vector4& GetTranslation() const
+ {
+ return reinterpret_cast<const Vector4&>(mMatrix[12]);
+ }
/**
* @brief Gets the x,y and z components of the translation as a Vector3.
*
* This assumes the matrix is a transform matrix.
+ * @SINCE_1_0.0
+ * @return The translation
* @note inlined for performance reasons (generates less code than a function call)
- * @return the translation
*/
- const Vector3& GetTranslation3() const { return reinterpret_cast<const Vector3&>(mMatrix[12]); }
+ const Vector3& GetTranslation3() const
+ {
+ return reinterpret_cast<const Vector3&>(mMatrix[12]);
+ }
+
+ /**
+ * @brief Gets the x,y and z components of the scale as a Vector3.
+ * Note that transform scale always has positive components.
+ *
+ * This assumes the matrix is a transform matrix.
+ * @SINCE_2_2.17
+ * @return The scale
+ */
+ Vector3 GetScale() const;
/**
* @brief Sets the translation.
*
* This assumes the matrix is a transform matrix.
- * @param [in] translation the translation
+ * @SINCE_1_0.0
+ * @param[in] translation The translation
*/
void SetTranslation(const Vector4& translation);
* @brief Sets the x,y and z components of the translation from a Vector3.
*
* This assumes the matrix is a transform matrix.
- * @param [in] translation the translation
+ * @SINCE_1_0.0
+ * @param[in] translation The translation
*/
void SetTranslation(const Vector3& translation);
* This function is used to correct floating point errors which would otherwise accumulate
* as operations are applied to the matrix. This function assumes the matrix is a transform
* matrix.
+ * @SINCE_1_0.0
*/
void OrthoNormalize();
* @brief Returns the contents of the matrix as an array of 16 floats.
*
* The order of the values for a transform matrix is:
- * 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
+ *
+ * @code
+ * [ 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 ]
+ * @endcode
+ *
+ * @SINCE_1_0.0
+ * @return The matrix contents as an array of 16 floats
* @note inlined for performance reasons (generates less code than a function call)
- * @return the matrix contents as an array of 16 floats.
*/
- const float* AsFloat() const {return mMatrix;}
+ const float* AsFloat() const
+ {
+ return mMatrix;
+ }
/**
* @brief Returns the contents of the matrix as an array of 16 floats.
*
* The order of the values for a transform matrix is:
*
- * 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
+ * @code
+ * [ 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 ]
+ * @endcode
+ *
+ * @SINCE_1_0.0
+ * @return The matrix contents as an array of 16 floats
* @note inlined for performance reasons (generates less code than a function call)
- * @return the matrix contents as an array of 16 floats.
*/
- float* AsFloat() {return mMatrix;}
-
+ float* AsFloat()
+ {
+ return mMatrix;
+ }
/**
* @brief Function to multiply two matrices and store the result onto third.
*
- * Use this method in time critical path as it does not require temporaries
- * @param result of the multiplication
- * @param lhs matrix, this can be same matrix as result
- * @param rhs matrix, this cannot be same matrix as result
+ * Use this method in time critical path as it does not require temporaries.
+ *
+ * result = rhs * lhs
+ *
+ * @SINCE_1_0.0
+ * @param[out] result Result of the multiplication
+ * @param[in] lhs Matrix, this can be same matrix as result
+ * @param[in] rhs Matrix, this cannot be same matrix as result
*/
- static void Multiply( Matrix& result, const Matrix& lhs, const Matrix& rhs );
+ static void Multiply(Matrix& result, const Matrix& lhs, const Matrix& rhs);
/**
* @brief Function to multiply a matrix and quaternion and store the result onto third.
*
- * Use this method in time critical path as it does not require temporaries
- * @param result of the multiplication
- * @param lhs matrix, this can be same matrix as result
- * @param rhs quaternion
+ * Use this method in time critical path as it does not require temporaries.
+ * @SINCE_1_0.0
+ * @param[out] result Result of the multiplication
+ * @param[in] lhs Matrix, this can be same matrix as result
+ * @param[in] rhs Quaternion
*/
- static void Multiply( Matrix& result, const Matrix& lhs, const Quaternion& rhs );
+ static void Multiply(Matrix& result, const Matrix& lhs, const Quaternion& rhs);
+
+ /**
+ * @brief Multiplication operator.
+ *
+ * Returned Matrix = This Matrix * rhs
+ *
+ * @note It makes some memory allocate & copy internally.
+ * Use Matrix::Multiply API for time critical path.
+ *
+ * @SINCE_2_1.44
+ * @param[in] rhs The Matrix to multiply this by
+ * @return A Matrix containing the result
+ */
+ Matrix operator*(const Matrix& rhs) const;
+
+ /**
+ * @brief Multiplication assignment operator.
+ *
+ * This Matrix *= rhs
+ *
+ * @note It makes some memory allocate & copy internally.
+ *
+ * @SINCE_2_1.46
+ * @param[in] rhs The Matrix to multiply this by
+ * @return Itself
+ */
+ Matrix& operator*=(const Matrix& rhs);
/**
* @brief The multiplication operator.
*
- * @param [in] rhs the Matrix to multiply this by
- * @return A matrix containing the result
+ * Returned Vector = This Matrix * rhs
+ *
+ * @SINCE_1_0.0
+ * @param[in] rhs The Vector4 to multiply this by
+ * @return A Vector4 containing the result
*/
Vector4 operator*(const Vector4& rhs) const;
/**
* @brief The equality operator.
*
- * Utilises appropriate machine epsilon values.
+ * Utilizes appropriate machine epsilon values.
*
- * @param [in] rhs the Matrix to compare this to
+ * @SINCE_1_0.0
+ * @param[in] rhs The Matrix to compare this to
* @return true if the matrices are equal
*/
- bool operator==(const Matrix & rhs) const;
+ bool operator==(const Matrix& rhs) const;
/**
* @brief The inequality operator.
*
- * Utilises appropriate machine epsilon values.
- * @param [in] rhs the Matrix to compare this to
+ * Utilizes appropriate machine epsilon values.
+ * @SINCE_1_0.0
+ * @param[in] rhs The Matrix to compare this to
* @return true if the matrices are not equal.
*/
- bool operator!=(const Matrix & rhs) const;
+ bool operator!=(const Matrix& rhs) const;
/**
* @brief Sets this matrix to contain the position, scale and rotation components.
*
* Performs scale, rotation, then translation
- * @param[in] scale to apply
- * @param[in] rotation to apply
- * @param[in] translation to apply
+ * @SINCE_1_0.0
+ * @param[in] scale Scale to apply
+ * @param[in] rotation Rotation to apply
+ * @param[in] translation Translation to apply
*/
- void SetTransformComponents(const Vector3& scale,
+ void SetTransformComponents(const Vector3& scale,
const Quaternion& rotation,
- const Vector3& translation );
+ const Vector3& translation);
/**
* @brief Sets this matrix to contain the inverse of the position, scale and rotation components.
*
* Performs translation, then rotation, then scale.
- * @param[in] scale to apply
- * @param[in] rotation to apply
- * @param[in] translation to apply
+ * @SINCE_1_0.0
+ * @param[in] scale Scale to apply
+ * @param[in] rotation Rotation to apply
+ * @param[in] translation Translation to apply
*/
void SetInverseTransformComponents(const Vector3& scale,
const Quaternion& rotation,
- const Vector3& translation );
-
+ const Vector3& translation);
/**
* @brief Sets this matrix to contain the inverse of the orthonormal basis and position components.
*
* Performs translation, then rotation.
+ * @SINCE_1_0.0
* @param[in] xAxis The X axis of the basis
* @param[in] yAxis The Y axis of the basis
* @param[in] zAxis The Z axis of the basis
- * @param[in] translation to apply
+ * @param[in] translation Translation to apply
*/
- void SetInverseTransformComponents(const Vector3& xAxis,
- const Vector3& yAxis,
- const Vector3& zAxis,
- const Vector3& translation );
+ void SetInverseTransformComponents(const Vector3& xAxis,
+ const Vector3& yAxis,
+ const Vector3& zAxis,
+ const Vector3& translation);
/**
* @brief Gets the position, scale and rotation components from the given transform matrix.
*
+ * @SINCE_1_0.0
+ * @param[out] position Position to set
+ * @param[out] rotation Rotation to set - only valid if the transform matrix has not been skewed or sheared
+ * @param[out] scale Scale to set - only valid if the transform matrix has not been skewed or sheared
* @pre This matrix must not contain skews or shears.
- * @param[out] position to set
- * @param[out] rotation to set - only valid if the transform matrix has not been skewed or sheared
- * @param[out] scale to set - only valid if the transform matrix has not been skewed or sheared
*/
- void GetTransformComponents(Vector3& position,
+ void GetTransformComponents(Vector3& position,
Quaternion& rotation,
- Vector3& scale) const;
+ Vector3& scale) const;
private:
-
float mMatrix[16]; ///< The elements of the matrix
};
/**
- * @brief Print a matrix.
+ * @brief Prints a matrix.
*
- * It is printed in memory order, i.e. each printed row is contiguous in memory.
- * @param [in] o The output stream operator.
- * @param [in] matrix The matrix to print.
- * @return The output stream operator.
+ * It is printed in memory order.
+ * @SINCE_1_0.0
+ * @param[in] o The output stream operator
+ * @param[in] matrix The matrix to print
+ * @return The output stream operator
*/
-DALI_IMPORT_API std::ostream& operator<< (std::ostream& o, const Matrix& matrix);
+DALI_CORE_API std::ostream& operator<<(std::ostream& o, const Matrix& matrix);
+
+// Allow Matrix to be treated as a POD type
+template<>
+struct TypeTraits<Matrix> : public BasicTypes<Matrix>
+{
+ enum
+ {
+ IS_TRIVIAL_TYPE = true
+ };
+};
+/**
+ * @}
+ */
} // namespace Dali
-#endif // __DALI_MATRIX_H__
+#endif // DALI_MATRIX_H
projects / platform / core / uifw / dali-core.git / blobdiff