X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali%2Fpublic-api%2Fmath%2Fvector3.h;h=1a98005ece954354237309dd0facafda70845443;hb=646f736e77b085c86e982c0d1d4b895c2a431330;hp=ba6e38f3c8386317eacf1de29f85dec8590ca48e;hpb=199d46a42f943543a9d43cc3166a0d8b7cf63fd4;p=platform%2Fcore%2Fuifw%2Fdali-core.git diff --git a/dali/public-api/math/vector3.h b/dali/public-api/math/vector3.h index ba6e38f..1a98005 100644 --- a/dali/public-api/math/vector3.h +++ b/dali/public-api/math/vector3.h @@ -2,7 +2,7 @@ #define __DALI_VECTOR_3_H__ /* - * Copyright (c) 2015 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,13 +19,19 @@ */ // EXTERNAL INCLUDES +#include // uint32_t #include // INTERNAL INCLUDES #include +#include namespace Dali { +/** + * @addtogroup dali_core_math + * @{ + */ struct Vector2; struct Vector4; @@ -33,13 +39,15 @@ class Quaternion; /** * @brief A three dimensional vector. + * @SINCE_1_0.0 */ -struct DALI_IMPORT_API Vector3 +struct DALI_CORE_API Vector3 { // Construction /** * @brief Constructor. + * @SINCE_1_0.0 */ // NOTE // (x width r), (y height g), (z depth b) must be consecutive in memory. @@ -55,9 +63,10 @@ struct DALI_IMPORT_API Vector3 /** * @brief Constructor. * - * @param [in] x (or width) component - * @param [in] y (or height) component - * @param [in] z (or depth) component + * @SINCE_1_0.0 + * @param[in] x (or width) component + * @param[in] y (or height) component + * @param[in] z (or depth) component */ explicit Vector3(float x, float y, float z) : x(x), @@ -69,7 +78,8 @@ struct DALI_IMPORT_API Vector3 /** * @brief Conversion constructor from an array of three floats. * - * @param [in] array of xyz + * @SINCE_1_0.0 + * @param[in] array Array of xyz */ explicit Vector3(const float* array) : x(array[0]), @@ -81,14 +91,16 @@ struct DALI_IMPORT_API Vector3 /** * @brief Constructor. * - * @param [in] vec2 Vector2 to create this vector from + * @SINCE_1_0.0 + * @param[in] vec2 Vector2 to create this vector from */ explicit Vector3( const Vector2& vec2 ); /** * @brief Constructor. * - * @param [in] vec4 Vector4 to create this vector from + * @SINCE_1_0.0 + * @param[in] vec4 Vector4 to create this vector from */ explicit Vector3( const Vector4& vec4 ); @@ -108,8 +120,9 @@ struct DALI_IMPORT_API Vector3 /** * @brief Assignment operator. * - * @param[in] array of floats - * @return itself + * @SINCE_1_0.0 + * @param[in] array Array of floats + * @return Itself */ Vector3& operator=(const float* array) { @@ -123,23 +136,26 @@ struct DALI_IMPORT_API Vector3 /** * @brief Assignment operator. * - * @param[in] rhs vector to assign. - * @return itself + * @SINCE_1_0.0 + * @param[in] rhs Vector to assign + * @return Itself */ Vector3& operator=(const Vector2& rhs); /** * @brief Assignment operator. * - * @param[in] rhs vector to assign. - * @return itself + * @SINCE_1_0.0 + * @param[in] rhs Vector to assign + * @return Itself */ Vector3& operator=(const Vector4& rhs); /** * @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 */ Vector3 operator+(const Vector3& rhs) const @@ -152,8 +168,9 @@ struct DALI_IMPORT_API Vector3 /** * @brief Addition assignment operator. * - * @param[in] rhs vector to add. - * @return itself + * @SINCE_1_0.0 + * @param[in] rhs Vector to add + * @return Itself */ Vector3& operator+=(const Vector3& rhs) { @@ -167,7 +184,8 @@ struct DALI_IMPORT_API Vector3 /** * @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 */ Vector3 operator-(const Vector3& rhs) const @@ -180,8 +198,9 @@ struct DALI_IMPORT_API Vector3 /** * @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 */ Vector3& operator-=(const Vector3& rhs) { @@ -195,7 +214,8 @@ struct DALI_IMPORT_API Vector3 /** * @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 */ Vector3 operator*(const Vector3& rhs) const @@ -208,7 +228,8 @@ struct DALI_IMPORT_API Vector3 /** * @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 */ Vector3 operator*(float rhs) const @@ -219,8 +240,9 @@ struct DALI_IMPORT_API Vector3 /** * @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 */ Vector3& operator*=(const Vector3& rhs) { @@ -234,8 +256,9 @@ struct DALI_IMPORT_API Vector3 /** * @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 */ Vector3& operator*=(float rhs) { @@ -249,15 +272,17 @@ struct DALI_IMPORT_API Vector3 /** * @brief Multiplication assignment operator. * - * @param[in] rhs the Quaternion value to multiply the vector by - * @return itself + * @SINCE_1_0.0 + * @param[in] rhs The Quaternion value to multiply the vector by + * @return Itself */ Vector3& operator*=(const Quaternion& rhs); /** * @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 */ Vector3 operator/(const Vector3& rhs) const @@ -270,6 +295,7 @@ struct DALI_IMPORT_API Vector3 /** * @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 */ @@ -281,8 +307,9 @@ struct DALI_IMPORT_API Vector3 /** * @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 */ Vector3& operator/=(const Vector3& rhs) { @@ -296,8 +323,9 @@ struct DALI_IMPORT_API Vector3 /** * @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 */ Vector3& operator/=(float rhs) { @@ -312,7 +340,8 @@ struct DALI_IMPORT_API Vector3 /** * @brief Unary negation operator. * - * @return A vector containg the negation + * @SINCE_1_0.0 + * @return A vector containing the negation */ Vector3 operator-() const { @@ -324,20 +353,22 @@ struct DALI_IMPORT_API Vector3 /** * @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 Vector3& 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 Vector3& rhs) const { @@ -347,11 +378,12 @@ struct DALI_IMPORT_API Vector3 /** * @brief Const array subscript operator overload. * - * Asserts if index is out of range. Should be 0, 1 or 2 - * @param[in] index Subscript - * @return The float at the given index. + * Asserts if index is out of range. Should be 0, 1 or 2. + * @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 < 3 && "Vector element index out of bounds" ); @@ -361,11 +393,12 @@ struct DALI_IMPORT_API Vector3 /** * @brief Mutable array subscript operator overload. * - * Asserts if index is out of range. Should be 0, 1 or 2 + * Asserts if index is out of range. Should be 0, 1 or 2. + * @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 < 3 && "Vector element index out of bounds" ); @@ -378,8 +411,9 @@ struct DALI_IMPORT_API Vector3 * 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; @@ -389,15 +423,17 @@ struct DALI_IMPORT_API Vector3 * 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 - * @return the cross product + * @SINCE_1_0.0 + * @param[in] other The other vector + * @return The cross product */ Vector3 Cross(const Vector3& other) const; /** * @brief Returns the length of the vector. * - * @return the length of the vector + * @SINCE_1_0.0 + * @return The length of the vector */ float Length() const; @@ -406,21 +442,24 @@ struct DALI_IMPORT_API Vector3 * * This is more efficient than Length() for threshold * testing as it avoids the use of a square root. - * @return the length of the vector squared. + * @SINCE_1_0.0 + * @return The length of the vector squared */ float LengthSquared() const; /** * @brief Sets the vector to be 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 Vector3& min, const Vector3& max ); @@ -431,8 +470,9 @@ struct DALI_IMPORT_API Vector3 * 0: x (or width, or r) * 1: y (or height, or g) * 2: z (or depth, or b) + * @SINCE_1_0.0 + * @return The vector contents as an array of 3 floats * @note inlined for performance reasons (generates less code than a function call) - * @return the vector contents as an array of 3 floats. */ const float* AsFloat() const {return &x;} @@ -443,40 +483,45 @@ struct DALI_IMPORT_API Vector3 * 0: x (or width, or r) * 1: y (or height, or g) * 2: z (or depth, or b) + * @SINCE_1_0.0 + * @return The vector contents as an array of 3 floats * @note inlined for performance reasons (generates less code than a function call) - * @return the vector contents as an array of 3 floats. */ float* AsFloat() {return &x;} /** * @brief Returns the x & y components (or width & height, or r & g) as a Vector2. * + * @SINCE_1_0.0 + * @return The partial vector contents as Vector2 (x,y) * @note inlined for performance reasons (generates less code than a function call) - * @return the partial vector contents as Vector2 (x,y) */ const Vector2& GetVectorXY() const {return reinterpret_cast(x);} /** * @brief Returns the x & y components (or width & height, or r & g) as a Vector2. * + * @SINCE_1_0.0 + * @return The partial vector contents as Vector2 (x,y) * @note inlined for performance reasons (generates less code than a function call) - * @return the partial vector contents as Vector2 (x,y) */ Vector2& GetVectorXY() {return reinterpret_cast(x);} /** * @brief Returns the y & z components (or height & depth, or g & b) as a Vector2. * + * @SINCE_1_0.0 + * @return The partial vector contents as Vector2 (y,z) * @note inlined for performance reasons (generates less code than a function call) - * @return the partial vector contents as Vector2 (y,z) */ const Vector2& GetVectorYZ() const {return reinterpret_cast(y);} /** * @brief Returns the y & z components (or height & depth, or g & b) as a Vector2. * + * @SINCE_1_0.0 + * @return The partial vector contents as Vector2 (y,z) * @note inlined for performance reasons (generates less code than a function call) - * @return the partial vector contents as Vector2 (y,z) */ Vector2& GetVectorYZ() {return reinterpret_cast(y);} @@ -507,21 +552,23 @@ struct DALI_IMPORT_API Vector3 }; /** - * @brief Print a Vector3. + * @brief Prints a Vector3. * - * @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 Vector3& vector); +DALI_CORE_API std::ostream& operator<< (std::ostream& o, const Vector3& vector); /** * @brief Returns a vector with components set to the minimum of the corresponding component in a and b. * * If a=0,1,2 and b=2,1,0 returns a vector of 2,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 + * @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 Vector3 Min( const Vector3& a, const Vector3& b ) { @@ -533,10 +580,11 @@ inline Vector3 Min( const Vector3& a, const Vector3& b ) /** * @brief Returns a vector with components set to the maximum of the corresponding component in a and b. * - * If a=0,1 and b=1,0 returns a vector of 1,1 - * @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 and b=1,0 returns a vector of 1,1. + * @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 Vector3 Max( const Vector3& a, const Vector3& b ) { @@ -548,61 +596,20 @@ inline Vector3 Max( const Vector3& a, const Vector3& 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 Vector3 Clamp( const Vector3& v, const float& min, const float& max ); +DALI_CORE_API Vector3 Clamp( const Vector3& v, const float& min, const float& max ); -/** - * @brief Scales an Actor, such that it fits within its Parent's Size Keeping the aspect ratio. - * - * f(target, source) = Vector3( min( target.X / source.X, min( target.Y / source.Y, target.Z / source.Z ) ) - * If any of the source dimensions is zero it will be ignored in the calculation - * - * @param [in] target size - * @param [in] source size - * @return target scaled inside source - */ -DALI_IMPORT_API Vector3 FitKeepAspectRatio( const Vector3& target, const Vector3& source ); +// Allow Vector3 to be treated as a POD type +template <> struct TypeTraits< Vector3 > : public BasicTypes< Vector3 > { enum { IS_TRIVIAL_TYPE = true }; }; /** - * @brief Scales an Actor, such that it fill its Parent's Size Keeping the aspect ratio. - * - * f(target, source) = Vector3( max( target.X / source.X, max( target.Y / source.Y, target.Z / source.Z ) ) - * If any of the source dimensions is zero it will be ignored in the calculation - * - * @param [in] target size - * @param [in] source size - * @return target scaled inside source + * @} */ -DALI_IMPORT_API Vector3 FillKeepAspectRatio( const Vector3& target, const Vector3& source ); - -/** - * @brief Scales an Actor, such that it fill its Parent's Size in the X and Y coordinates Keeping the aspect ratio. - * - * f(target, source) = Vector3( max( target.X / sizeX, target.Y / sizeY ) ) - * If any of the source dimensions is zero it will be ignored in the calculation - * - * @param [in] target size - * @param [in] source size - * @return target scaled inside source - */ -DALI_IMPORT_API Vector3 FillXYKeepAspectRatio( const Vector3& target, const Vector3& source ); - -/** - * @brief Shrinks source size inside the target size maintaining aspect ratio of source. - * - * If source is smaller than target it returns source - * @pre source width and height > 0 - * @param [in] target size - * @param [in] source size - * @return target scaled inside source - */ -DALI_IMPORT_API Vector3 ShrinkInsideKeepAspectRatio( const Vector3& target, const Vector3& source ); - - } // namespace Dali #endif // __DALI_VECTOR_3_H__