X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali%2Fpublic-api%2Fmath%2Fmatrix.h;h=332163db1d8bde3206a6e1c54b4a0df59e8e176e;hb=8a73b1bfdc359a52a3cf1b104b4e42902866705e;hp=ab96e049c3e4ee814e590fce3ad40bcd77e19ce2;hpb=b5463fd098d5dda692d0753600012990d39f22b4;p=platform%2Fcore%2Fuifw%2Fdali-core.git diff --git a/dali/public-api/math/matrix.h b/dali/public-api/math/matrix.h index ab96e04..332163d 100644 --- a/dali/public-api/math/matrix.h +++ b/dali/public-api/math/matrix.h @@ -1,8 +1,8 @@ -#ifndef __DALI_MATRIX_H__ -#define __DALI_MATRIX_H__ +#ifndef DALI_MATRIX_H +#define DALI_MATRIX_H /* - * Copyright (c) 2015 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. @@ -28,69 +28,111 @@ 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. @@ -99,22 +141,25 @@ public: /** * @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; @@ -123,33 +168,38 @@ public: * * 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; @@ -157,7 +207,8 @@ public: * @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); @@ -165,7 +216,8 @@ public: * @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); @@ -173,7 +225,8 @@ public: * @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); @@ -181,25 +234,44 @@ public: * @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(mMatrix[12]); } + const Vector4& GetTranslation() const + { + return reinterpret_cast(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(mMatrix[12]); } + const Vector3& GetTranslation3() const + { + return reinterpret_cast(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); @@ -207,7 +279,8 @@ public: * @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); @@ -217,6 +290,7 @@ public: * 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(); @@ -224,145 +298,203 @@ public: * @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); + + /** + * @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 */ - static void Multiply( Matrix& result, const Matrix& lhs, const Quaternion& rhs ); + 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 }; }; +template<> +struct TypeTraits : public BasicTypes +{ + enum + { + IS_TRIVIAL_TYPE = true + }; +}; +/** + * @} + */ } // namespace Dali -#endif // __DALI_MATRIX_H__ +#endif // DALI_MATRIX_H