X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali%2Fpublic-api%2Fmath%2Fvector2.h;h=2d7df3368eb3837cc8e9832c3161dde3904eb9e0;hb=646f736e77b085c86e982c0d1d4b895c2a431330;hp=dd1e7ab1e4a5404296d5af0feec509f10536a564;hpb=f8a75318dd2950c20fb8c6c9a6523fdb0e106030;p=platform%2Fcore%2Fuifw%2Fdali-core.git

diff --git a/dali/public-api/math/vector2.h b/dali/public-api/math/vector2.h
index dd1e7ab..2d7df33 100644
--- a/dali/public-api/math/vector2.h
+++ b/dali/public-api/math/vector2.h
@@ -2,7 +2,7 @@
 #define __DALI_VECTOR_2_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,21 +19,28 @@
  */
 
 // EXTERNAL INCLUDES
+#include <cstdint> // uint32_t
 #include <iosfwd>
 
 // INTERNAL INCLUDES
 #include <dali/public-api/common/dali-common.h>
+#include <dali/public-api/common/type-traits.h>
 
 namespace Dali
 {
+/**
+ * @addtogroup dali_core_math
+ * @{
+ */
 
 struct Vector3;
 struct Vector4;
 
 /**
  * @brief A two dimensional vector.
+ * @SINCE_1_0.0
  */
-struct DALI_IMPORT_API Vector2
+struct DALI_CORE_API Vector2
 {
 // (x width) and (y height) must be consecutive in memory.
 // No other data must be added before (x width) member.
@@ -43,6 +50,7 @@ public:
 
   /**
    * @brief Constructor.
+   * @SINCE_1_0.0
    */
   Vector2()
   : x(0.0f),
@@ -53,6 +61,7 @@ public:
   /**
    * @brief Constructor.
    *
+   * @SINCE_1_0.0
    * @param[in] x x or width component
    * @param[in] y y or height component
    */
@@ -64,7 +73,8 @@ public:
   /**
    * @brief Conversion constructor from an array of two floats.
    *
-   * @param [in] array of xy
+   * @SINCE_1_0.0
+   * @param[in] array Array of xy
    */
   explicit Vector2(const float* array)
   : x(array[0]),
@@ -75,14 +85,16 @@ public:
   /**
    * @brief Constructor.
    *
-   * @param [in] vec3 Vector3 to create this vector from
+   * @SINCE_1_0.0
+   * @param[in] vec3 Vector3 to create this vector from
    */
   explicit Vector2(const Vector3& vec3);
 
   /**
    * @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 Vector2(const Vector4& vec4);
 
@@ -100,8 +112,9 @@ public:
   /**
    * @brief Assignment operator.
    *
-   * @param[in] array of floats
-   * @return itself
+   * @SINCE_1_0.0
+   * @param[in] array Array of floats
+   * @return Itself
    */
   Vector2& operator=(const float* array)
   {
@@ -114,23 +127,26 @@ public:
   /**
    * @brief Assignment operator.
    *
-   * @param[in] rhs vector to assign.
-   * @return itself
+   * @SINCE_1_0.0
+   * @param[in] rhs Vector to assign
+   * @return Itself
    */
   Vector2& operator=(const Vector3& rhs);
 
   /**
    * @brief Assignment operator.
    *
-   * @param[in] rhs vector to assign.
-   * @return itself
+   * @SINCE_1_0.0
+   * @param[in] rhs Vector to assign
+   * @return Itself
    */
   Vector2& 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
    */
   Vector2 operator+(const Vector2& rhs) const
@@ -143,8 +159,9 @@ public:
   /**
    * @brief Addition assignment operator.
    *
-   * @param[in] rhs vector to add.
-   * @return itself
+   * @SINCE_1_0.0
+   * @param[in] rhs Vector to add
+   * @return Itself
    */
   Vector2& operator+=(const Vector2& rhs)
   {
@@ -157,7 +174,8 @@ public:
   /**
    * @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
    */
   Vector2 operator-(const Vector2& rhs) const
@@ -170,8 +188,9 @@ public:
   /**
    * @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
    */
   Vector2& operator-=(const Vector2& rhs)
   {
@@ -184,7 +203,8 @@ public:
   /**
    * @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
    */
   Vector2 operator*(const Vector2& rhs) const
@@ -195,7 +215,8 @@ public:
   /**
    * @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
    */
   Vector2 operator*(float rhs) const
@@ -206,8 +227,9 @@ public:
   /**
    * @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
    */
   Vector2& operator*=(const Vector2& rhs)
   {
@@ -220,8 +242,9 @@ public:
   /**
    * @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
    */
   Vector2& operator*=(float rhs)
   {
@@ -234,7 +257,8 @@ public:
   /**
    * @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
    */
   Vector2 operator/(const Vector2& rhs) const
@@ -245,6 +269,7 @@ public:
   /**
    * @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
    */
@@ -257,8 +282,9 @@ public:
   /**
    * @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
    */
   Vector2& operator/=(const Vector2& rhs)
   {
@@ -271,8 +297,9 @@ public:
   /**
    * @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
    */
   Vector2& operator/=(float rhs)
   {
@@ -285,7 +312,8 @@ public:
   /**
    * @brief Unary negation operator.
    *
-   * @return A vector containg the negation
+   * @SINCE_1_0.0
+   * @return A vector containing the negation
    */
   Vector2 operator-() const
   {
@@ -297,8 +325,9 @@ public:
   /**
    * @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
    */
@@ -307,8 +336,9 @@ public:
   /**
    * @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
    */
@@ -320,11 +350,12 @@ public:
   /**
    * @brief Const array subscript operator overload.
    *
-   * Asserts if index is out of range. Should be 0 or 1
-   * @param[in] index Subscript
-   * @return    The float at the given index
+   * Asserts if index is out of range. Should be 0 or 1.
+   * @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 < 2 && "Vector element index out of bounds" );
 
@@ -334,11 +365,12 @@ public:
   /**
    * @brief Mutable array subscript operator overload.
    *
-   * Asserts if index is out of range. Should be 0 or 1
+   * Asserts if index is out of range. Should be 0 or 1.
+   * @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 < 2 && "Vector element index out of bounds" );
 
@@ -348,7 +380,8 @@ public:
   /**
    * @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;
 
@@ -357,21 +390,24 @@ public:
    *
    * 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 Vector2& min, const Vector2& max );
 
@@ -381,8 +417,9 @@ public:
    * The order of the values in this array are as follows:
    * 0: x (or width)
    * 1: y (or height)
+   * @SINCE_1_0.0
+   * @return The vector contents as an array of 2 floats
    * @note inlined for performance reasons (generates less code than a function call)
-   * @return the vector contents as an array of 2 floats.
    */
   const float* AsFloat() const {return &x;}
 
@@ -392,8 +429,9 @@ public:
    * The order of the values in this array are as follows:
    * 0: x (or width)
    * 1: y (or height)
+   * @SINCE_1_0.0
+   * @return The vector contents as an array of 2 floats
    * @note inlined for performance reasons (generates less code than a function call)
-   * @return the vector contents as an array of 2 floats.
    */
   float* AsFloat() {return &x;}
 
@@ -418,26 +456,29 @@ public: // Data
 };
 
 /**
- * @brief Size is an alias of Dali::Vector2
+ * @brief Size is an alias of Dali::Vector2.
+ * @SINCE_1_0.0
  */
 typedef Vector2 Size;
 
 /**
  * @brief Print a Vector2.
  *
- * @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 Vector2& vector);
+DALI_CORE_API std::ostream& operator<< (std::ostream& o, const Vector2& vector);
 
 /**
  * @brief Returns a vector with components set to the minimum of the corresponding component in a and b.
  *
- * If a=0,1 and b=1,0  returns a vector of 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
+ * If a=0,1 and b=1,0 returns a vector of 0,0.
+ * @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 Vector2 Min( const Vector2& a, const Vector2& b )
 {
@@ -447,10 +488,11 @@ inline Vector2 Min( const Vector2& a, const Vector2& 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 Vector2 Max( const Vector2& a, const Vector2& b )
 {
@@ -460,51 +502,20 @@ inline Vector2 Max( const Vector2& a, const Vector2& 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 Vector2 Clamp( const Vector2& v, const float& min, const float& max );
+DALI_CORE_API Vector2 Clamp( const Vector2& v, const float& min, const float& max );
 
-/**
- * @brief Fits source size inside the target size maintaining aspect ratio.
- *
- * @pre source width and height > 0
- * @param [in] target size
- * @param [in] source size
- * @return target scaled inside source
- */
-DALI_IMPORT_API Size FitInside( const Size& target, const Size& source );
+// Allow Vector2 to be treated as a POD type
+template <> struct TypeTraits< Vector2 > : public BasicTypes< Vector2 > { enum { IS_TRIVIAL_TYPE = true }; };
 
 /**
- * @brief Fits or scales to fill.
- *
- * a) If target width and height are non-zero
- *    Fits source size into target aspect ratio
- *    If source is bigger, simply returns target.
- *    Does not scale larger than source
- * b) If target width or height is zero
- *    maintains the aspect ratio of source (as target has no aspect ratio)
- *    returns target width and scaled height or target height and scaled width
- * This algorithm is usefull when you want for example a square thumbnail of a rectangular image data
- * @param [in] target size
- * @param [in] source size
- * @return target scaled inside source
- */
-DALI_IMPORT_API Size FitScaleToFill( const Size& target, const Size& 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 Size ShrinkInside( const Size& target, const Size& source );
-
 } // namespace Dali
 
 #endif // __DALI_VECTOR_2_H__