X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali%2Fpublic-api%2Fmath%2Fvector4.h;h=a42c55a29b1ab0956a2c5c35e4b1e7426e7b5bd3;hb=646f736e77b085c86e982c0d1d4b895c2a431330;hp=6cfc206a09ed9d16d57fe2532c91d13a0801d7cd;hpb=5787f865cbe64c2b89e85852e3230dac1fdef6b1;p=platform%2Fcore%2Fuifw%2Fdali-core.git diff --git a/dali/public-api/math/vector4.h b/dali/public-api/math/vector4.h index 6cfc206..a42c55a 100644 --- a/dali/public-api/math/vector4.h +++ b/dali/public-api/math/vector4.h @@ -2,7 +2,7 @@ #define __DALI_VECTOR_4_H__ /* - * Copyright (c) 2014 Samsung Electronics Co., Ltd. + * Copyright (c) 2018 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. @@ -19,22 +19,30 @@ */ // EXTERNAL INCLUDES +#include // uint32_t #include // INTERNAL INCLUDES #include +#include namespace Dali { +/** + * @addtogroup dali_core_math + * @{ + */ + struct Vector2; struct Vector3; /** * @brief A four dimensional vector. * - * Components can be used as position or offset (x,y,z,w); color (r,g,b,a) or texture coords(s,t,p,q) + * Components can be used as position or offset (x,y,z,w); color (r,g,b,a) or texture coords(s,t,p,q). + * @SINCE_1_0.0 */ -struct DALI_IMPORT_API Vector4 +struct DALI_CORE_API Vector4 { // NOTE // xrs, ygt, zbp and waq must be consecutive in memory. @@ -45,6 +53,7 @@ struct DALI_IMPORT_API Vector4 /** * @brief Default constructor, initializes the vector to 0. + * @SINCE_1_0.0 */ Vector4() : x(0.0f), @@ -57,10 +66,11 @@ struct DALI_IMPORT_API Vector4 /** * @brief Conversion constructor from four floats. * - * @param [in] x (or r/s) component - * @param [in] y (or g/t) component - * @param [in] z (or b/p) component - * @param [in] w (or a/q) component + * @SINCE_1_0.0 + * @param[in] x x (or r/s) component + * @param[in] y y (or g/t) component + * @param[in] z z (or b/p) component + * @param[in] w w (or a/q) component */ explicit Vector4(float x, float y, float z, float w) : x(x), @@ -74,7 +84,8 @@ struct DALI_IMPORT_API Vector4 /** * @brief Conversion constructor from an array of four floats. * - * @param [in] array of either xyzw/rgba/stpq + * @SINCE_1_0.0 + * @param[in] array Array of either xyzw/rgba/stpq */ explicit Vector4(const float* array) : x(array[0]), @@ -87,14 +98,16 @@ struct DALI_IMPORT_API Vector4 /** * @brief Conversion constructor from Vector2. * - * @param [in] vec2 to copy from, z and w are initialized to 0 + * @SINCE_1_0.0 + * @param[in] vec2 Vector2 to copy from, z and w are initialized to 0 */ explicit Vector4( const Vector2& vec2 ); /** * @brief Conversion constructor from Vector3. * - * @param [in] vec3 to copy from, w is initialized to 0 + * @SINCE_1_0.0 + * @param[in] vec3 Vector3 to copy from, w is initialized to 0 */ explicit Vector4( const Vector3& vec3 ); @@ -110,8 +123,9 @@ struct DALI_IMPORT_API Vector4 /** * @brief Assignment operator. * - * @param [in] array of floats - * @return itself + * @SINCE_1_0.0 + * @param[in] array Array of floats + * @return Itself */ Vector4& operator=(const float* array) { @@ -126,25 +140,28 @@ struct DALI_IMPORT_API Vector4 /** * @brief Assignment operator. * - * Only sets x and y. z and w are left as they were - * @param [in] vec2 to assign from. - * @return itself + * Only sets x and y. z and w are left as they were. + * @SINCE_1_0.0 + * @param[in] vec2 A reference to assign from + * @return Itself */ Vector4& operator=(const Vector2& vec2 ); /** * @brief Assignment operator. * - * Only sets x and y and z. w is left as it was - * @param [in] vec3 to assign from - * @return itself + * Only sets x and y and z. w is left as it was. + * @SINCE_1_0.0 + * @param[in] vec3 A reference to assign from + * @return Itself */ Vector4& operator=(const Vector3& vec3 ); /** * @brief Addition operator. * - * @param[in] rhs vector to add. + * @SINCE_1_0.0 + * @param[in] rhs Vector to add * @return A vector containing the result of the addition */ Vector4 operator+(const Vector4 & rhs) const @@ -157,8 +174,9 @@ struct DALI_IMPORT_API Vector4 /** * @brief Addition assignment operator. * - * @param[in] rhs vector to add. - * @return itself + * @SINCE_1_0.0 + * @param[in] rhs Vector to add + * @return Itself */ Vector4& operator+=(const Vector4& rhs) { @@ -173,7 +191,8 @@ struct DALI_IMPORT_API Vector4 /** * @brief Subtraction operator. * - * @param[in] rhs the vector to subtract + * @SINCE_1_0.0 + * @param[in] rhs The vector to subtract * @return A vector containing the result of the subtraction */ Vector4 operator-(const Vector4& rhs) const @@ -188,8 +207,9 @@ struct DALI_IMPORT_API Vector4 /** * @brief Subtraction assignment operator. * - * @param[in] rhs the vector to subtract - * @return itself + * @SINCE_1_0.0 + * @param[in] rhs The vector to subtract + * @return Itself */ Vector4& operator-=(const Vector4& rhs) { @@ -204,7 +224,8 @@ struct DALI_IMPORT_API Vector4 /** * @brief Multiplication operator. * - * @param[in] rhs the vector to multiply + * @SINCE_1_0.0 + * @param[in] rhs The vector to multiply * @return A vector containing the result of the multiplication */ Vector4 operator*(const Vector4& rhs) const @@ -217,7 +238,8 @@ struct DALI_IMPORT_API Vector4 /** * @brief Multiplication operator. * - * @param[in] rhs the float value to scale the vector + * @SINCE_1_0.0 + * @param[in] rhs The float value to scale the vector * @return A vector containing the result of the scaling */ Vector4 operator*(float rhs) const @@ -228,8 +250,9 @@ struct DALI_IMPORT_API Vector4 /** * @brief Multiplication assignment operator. * - * @param[in] rhs the vector to multiply - * @return itself + * @SINCE_1_0.0 + * @param[in] rhs The vector to multiply + * @return Itself */ Vector4& operator*=(const Vector4& rhs) { @@ -244,8 +267,9 @@ struct DALI_IMPORT_API Vector4 /** * @brief Multiplication assignment operator. * - * @param[in] rhs the float value to scale the vector - * @return itself + * @SINCE_1_0.0 + * @param[in] rhs The float value to scale the vector + * @return Itself */ Vector4& operator*=(float rhs) { @@ -260,7 +284,8 @@ struct DALI_IMPORT_API Vector4 /** * @brief Division operator. * - * @param[in] rhs the vector to divide + * @SINCE_1_0.0 + * @param[in] rhs The vector to divide * @return A vector containing the result of the division */ Vector4 operator/(const Vector4 & rhs) const @@ -273,6 +298,7 @@ struct DALI_IMPORT_API Vector4 /** * @brief Division operator. * + * @SINCE_1_0.0 * @param[in] rhs The float value to scale the vector by * @return A vector containing the result of the scaling */ @@ -285,8 +311,9 @@ struct DALI_IMPORT_API Vector4 /** * @brief Division assignment operator. * - * @param[in] rhs the vector to divide - * @return itself + * @SINCE_1_0.0 + * @param[in] rhs The vector to divide + * @return Itself */ Vector4& operator/=(const Vector4& rhs) { @@ -301,8 +328,9 @@ struct DALI_IMPORT_API Vector4 /** * @brief Division assignment operator. * - * @param[in] rhs the float value to scale the vector by - * @return itself + * @SINCE_1_0.0 + * @param[in] rhs The float value to scale the vector by + * @return Itself */ Vector4& operator/=(float rhs) { @@ -318,7 +346,8 @@ struct DALI_IMPORT_API Vector4 /** * @brief Unary negation operator. * - * @return the negative value + * @SINCE_1_0.0 + * @return The negative value */ Vector4 operator-() const { @@ -330,20 +359,22 @@ struct DALI_IMPORT_API Vector4 /** * @brief Equality operator. * - * Utilises appropriate machine epsilon values. + * Utilizes appropriate machine epsilon values. * + * @SINCE_1_0.0 * @param[in] rhs The vector to test against - * @return true if the vectors are equal + * @return True if the vectors are equal */ bool operator==(const Vector4 &rhs) const; /** * @brief Inequality operator. * - * Utilises appropriate machine epsilon values. + * Utilizes appropriate machine epsilon values. * + * @SINCE_1_0.0 * @param[in] rhs The vector to test against - * @return true if the vectors are not equal + * @return True if the vectors are not equal */ bool operator!=(const Vector4 &rhs) const { @@ -353,11 +384,12 @@ struct DALI_IMPORT_API Vector4 /** * @brief Const array subscript operator overload. * - * Asserts if index is out of range. Should be 0, 1, 2 or 3 - * @param[in] index Subscript - * @return The float at the given index + * Asserts if index is out of range. Should be 0, 1, 2 or 3. + * @SINCE_1_0.0 + * @param[in] index Subscript index + * @return The float at the given index */ - const float& operator[](const unsigned int index) const + const float& operator[](const uint32_t index) const { DALI_ASSERT_ALWAYS( index < 4 && "Vector element index out of bounds" ); @@ -367,11 +399,12 @@ struct DALI_IMPORT_API Vector4 /** * @brief Mutable array subscript operator overload. * - * Asserts if index is out of range. Should be 0, 1, 2 or 3 + * Asserts if index is out of range. Should be 0, 1, 2 or 3. + * @SINCE_1_0.0 * @param[in] index Subscript index - * @return The float at the given index + * @return The float at the given index */ - float& operator[](const unsigned int index) + float& operator[](const uint32_t index) { DALI_ASSERT_ALWAYS( index < 4 && "Vector element index out of bounds" ); @@ -384,8 +417,9 @@ struct DALI_IMPORT_API Vector4 * The dot product is the length of one vector in the direction of another vector. * This is great for lighting, threshold testing the angle between two unit vectors, * calculating the distance between two points in a particular direction. - * @param [in] other the other vector - * @return the dot product + * @SINCE_1_0.0 + * @param[in] other The other vector + * @return The dot product */ float Dot(const Vector3& other) const; @@ -395,16 +429,18 @@ struct DALI_IMPORT_API Vector4 * The dot product is the length of one vector in the direction of another vector. * This is great for lighting, threshold testing the angle between two unit vectors, * calculating the distance between two points in a particular direction. - * @param [in] other the other vector - * @return the dot product + * @SINCE_1_0.0 + * @param[in] other The other vector + * @return The dot product */ float Dot(const Vector4& other) const; /** * @brief Returns the 4d dot product of this vector and another vector. * - * @param [in] other the other vector - * @return the dot product + * @SINCE_1_0.0 + * @param[in] other The other vector + * @return The dot product */ float Dot4(const Vector4& other) const; @@ -414,7 +450,8 @@ struct DALI_IMPORT_API Vector4 * The cross produce of two vectors is a vector which is perpendicular to the plane of the * two vectors. This is great for calculating normals and making matrices orthogonal. * - * @param [in] other the other vector + * @SINCE_1_0.0 + * @param[in] other The other vector * @return A vector containing the cross product */ Vector4 Cross(const Vector4& other) const; @@ -422,7 +459,8 @@ struct DALI_IMPORT_API Vector4 /** * @brief Returns the length of the vector. * - * @return the length. + * @SINCE_1_0.0 + * @return The length */ float Length() const; @@ -431,7 +469,8 @@ struct DALI_IMPORT_API Vector4 * * This is faster than using Length() when performing * threshold checks as it avoids use of the square root. - * @return the length of the vector squared. + * @SINCE_1_0.0 + * @return The length of the vector squared */ float LengthSquared() const; @@ -439,40 +478,54 @@ struct DALI_IMPORT_API Vector4 * @brief Normalizes the vector. * * Sets the vector to unit length whilst maintaining its direction. + * @SINCE_1_0.0 */ void Normalize(); /** * @brief Clamps the vector between minimum and maximum vectors. * - * @param [in] min the minimum vector - * @param [in] max the maximum vector + * @SINCE_1_0.0 + * @param[in] min The minimum vector + * @param[in] max The maximum vector */ void Clamp( const Vector4& min, const Vector4& max ); /** * @brief Returns the contents of the vector as an array of 4 floats. * + * @code + * * The order of the values in this array are as follows: * 0: x (or r, or s) * 1: y (or g, or t) * 2: z (or b, or p) * 3: w (or a, or q) + * + * @endcode + * + * @SINCE_1_0.0 + * @return The vector contents as an array of 4 floats * @note inlined for performance reasons (generates less code than a function call) - * @return the vector contents as an array of 4 floats. */ const float* AsFloat() const {return &x;} /** * @brief Returns the contents of the vector as an array of 4 floats. * + * @code + * * The order of the values in this array are as follows: * 0: x (or r, or s) * 1: y (or g, or t) * 2: z (or b, or p) * 3: w (or a, or q) + * + * @endcode + * + * @SINCE_1_0.0 + * @return The vector contents as an array of 4 floats * @note inlined for performance reasons (generates less code than a function call) - * @return the vector contents as an array of 4 floats. */ float* AsFloat() {return &x;} @@ -512,19 +565,21 @@ struct DALI_IMPORT_API Vector4 /** * @brief Print a Vector4. * - * @param [in] o The output stream operator. - * @param [in] vector The vector to print. - * @return The output stream operator. + * @SINCE_1_0.0 + * @param[in] o The output stream operator + * @param[in] vector The vector to print + * @return The output stream operator */ -DALI_IMPORT_API std::ostream& operator<<(std::ostream& o, const Vector4& vector); +DALI_CORE_API std::ostream& operator<<(std::ostream& o, const Vector4& vector); /** * @brief Returns a vector with components set to the minimum of the corresponding component in a and b. * - * If a=0,1,2,3 and b=4,0,1,2 returns a vector of 0,0,1,2 - * @param [in] a a vector - * @param [in] b a vector - * @return a vector containing the minimum of each component from a and b + * If a=0,1,2,3 and b=4,0,1,2 returns a vector of 0,0,1,2. + * @SINCE_1_0.0 + * @param[in] a A vector + * @param[in] b A vector + * @return A vector containing the minimum of each component from a and b */ inline Vector4 Min( const Vector4& a, const Vector4& b ) { @@ -537,10 +592,11 @@ inline Vector4 Min( const Vector4& a, const Vector4& b ) /** * @brief Returns a vector with components set to the maximum of the corresponding component in a and b. * - * If a=0,1,2,3 and b=4,0,1,2 returns a vector of 4,1,2,3 - * @param [in] a a vector - * @param [in] b a vector - * @return a vector containing the maximum of each component from a and b + * If a=0,1,2,3 and b=4,0,1,2 returns a vector of 4,1,2,3. + * @SINCE_1_0.0 + * @param[in] a A vector + * @param[in] b A vector + * @return A vector containing the maximum of each component from a and b */ inline Vector4 Max( const Vector4& a, const Vector4& b ) { @@ -553,13 +609,20 @@ inline Vector4 Max( const Vector4& a, const Vector4& b ) /** * @brief Clamps each of vector v's components between minimum and maximum values. * - * @param [in] v a vector - * @param [in] min the minimum value - * @param [in] max the maximum value - * @return a vector containing the clamped components of v + * @SINCE_1_0.0 + * @param[in] v A vector + * @param[in] min The minimum value + * @param[in] max The maximum value + * @return A vector containing the clamped components of v */ -DALI_IMPORT_API Vector4 Clamp( const Vector4& v, const float& min, const float& max ); +DALI_CORE_API Vector4 Clamp( const Vector4& v, const float& min, const float& max ); +// Allow Vector4 to be treated as a POD type +template <> struct TypeTraits< Vector4 > : public BasicTypes< Vector4 > { enum { IS_TRIVIAL_TYPE = true }; }; + +/** + * @} + */ } // namespace Dali #endif // __DALI_VECTOR_4_H__