dali/public-api/math/vector2.h

   1 #ifndef __DALI_VECTOR_2_H__
   2 #define __DALI_VECTOR_2_H__
   3
   4 /*
   5  * Copyright (c) 2015 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 // EXTERNAL INCLUDES
  22 #include <iosfwd>
  23
  24 // INTERNAL INCLUDES
  25 #include <dali/public-api/common/dali-common.h>
  26 #include <dali/public-api/common/type-traits.h>
  27
  28 namespace Dali
  29 {
  30 /**
  31  * @addtogroup dali_core_math
  32  * @{
  33  */
  34
  35 struct Vector3;
  36 struct Vector4;
  37
  38 /**
  39  * @brief A two dimensional vector.
  40  * @SINCE_1_0.0
  41  */
  42 struct DALI_IMPORT_API Vector2
  43 {
  44 // (x width) and (y height) must be consecutive in memory.
  45 // No other data must be added before (x width) member.
  46 // No virtual methods must be added to this struct.
  47
  48 public:
  49
  50   /**
  51    * @brief Constructor.
  52    * @SINCE_1_0.0
  53    */
  54   Vector2()
  55   : x(0.0f),
  56     y(0.0f)
  57   {
  58   }
  59
  60   /**
  61    * @brief Constructor.
  62    *
  63    * @SINCE_1_0.0
  64    * @param[in] x x or width component
  65    * @param[in] y y or height component
  66    */
  67   explicit Vector2(float x, float y)
  68   : x(x), y(y)
  69   {
  70   }
  71
  72   /**
  73    * @brief Conversion constructor from an array of two floats.
  74    *
  75    * @SINCE_1_0.0
  76    * @param[in] array Array of xy
  77    */
  78   explicit Vector2(const float* array)
  79   : x(array[0]),
  80     y(array[1])
  81   {
  82   }
  83
  84   /**
  85    * @brief Constructor.
  86    *
  87    * @SINCE_1_0.0
  88    * @param[in] vec3 Vector3 to create this vector from
  89    */
  90   explicit Vector2(const Vector3& vec3);
  91
  92   /**
  93    * @brief Constructor.
  94    *
  95    * @SINCE_1_0.0
  96    * @param[in] vec4 Vector4 to create this vector from
  97    */
  98   explicit Vector2(const Vector4& vec4);
  99
 100 // Constants
 101
 102   static const Vector2 ONE;               ///< (1.0f,1.0f)
 103   static const Vector2 XAXIS;             ///< Vector representing the X axis
 104   static const Vector2 YAXIS;             ///< Vector representing the Y axis
 105   static const Vector2 NEGATIVE_XAXIS;    ///< Vector representing the negative X axis
 106   static const Vector2 NEGATIVE_YAXIS;    ///< Vector representing the negative Y axis
 107   static const Vector2 ZERO;              ///< (0.0f, 0.0f)
 108
 109 // API
 110
 111   /**
 112    * @brief Assignment operator.
 113    *
 114    * @SINCE_1_0.0
 115    * @param[in] array Array of floats
 116    * @return Itself
 117    */
 118   Vector2& operator=(const float* array)
 119   {
 120     x = array[0];
 121     y = array[1];
 122
 123     return *this;
 124   }
 125
 126   /**
 127    * @brief Assignment operator.
 128    *
 129    * @SINCE_1_0.0
 130    * @param[in] rhs Vector to assign
 131    * @return Itself
 132    */
 133   Vector2& operator=(const Vector3& rhs);
 134
 135   /**
 136    * @brief Assignment operator.
 137    *
 138    * @SINCE_1_0.0
 139    * @param[in] rhs Vector to assign
 140    * @return Itself
 141    */
 142   Vector2& operator=(const Vector4& rhs);
 143
 144   /**
 145    * @brief Addition operator.
 146    *
 147    * @SINCE_1_0.0
 148    * @param[in] rhs Vector to add
 149    * @return A vector containing the result of the addition
 150    */
 151   Vector2 operator+(const Vector2& rhs) const
 152   {
 153     Vector2 temp(*this);
 154
 155     return temp += rhs;
 156   }
 157
 158   /**
 159    * @brief Addition assignment operator.
 160    *
 161    * @SINCE_1_0.0
 162    * @param[in] rhs Vector to add
 163    * @return Itself
 164    */
 165   Vector2& operator+=(const Vector2& rhs)
 166   {
 167     x += rhs.x;
 168     y += rhs.y;
 169
 170     return *this;
 171   }
 172
 173   /**
 174    * @brief Subtraction operator.
 175    *
 176    * @SINCE_1_0.0
 177    * @param[in] rhs The vector to subtract
 178    * @return A vector containing the result of the subtraction
 179    */
 180   Vector2 operator-(const Vector2& rhs) const
 181   {
 182     Vector2 temp(*this);
 183
 184     return temp -= rhs;
 185   }
 186
 187   /**
 188    * @brief Subtraction assignment operator.
 189    *
 190    * @SINCE_1_0.0
 191    * @param[in] rhs The vector to subtract
 192    * @return Itself
 193    */
 194   Vector2& operator-=(const Vector2& rhs)
 195   {
 196     x -= rhs.x;
 197     y -= rhs.y;
 198
 199     return *this;
 200   }
 201
 202   /**
 203    * @brief Multiplication operator.
 204    *
 205    * @SINCE_1_0.0
 206    * @param[in] rhs The vector to multiply
 207    * @return A vector containing the result of the multiplication
 208    */
 209   Vector2 operator*(const Vector2& rhs) const
 210   {
 211     return Vector2(x * rhs.x, y * rhs.y);
 212   }
 213
 214   /**
 215    * @brief Multiplication operator.
 216    *
 217    * @SINCE_1_0.0
 218    * @param[in] rhs The float value to scale the vector
 219    * @return A vector containing the result of the scaling
 220    */
 221   Vector2 operator*(float rhs) const
 222   {
 223     return Vector2(x * rhs, y * rhs);
 224   }
 225
 226   /**
 227    * @brief Multiplication assignment operator.
 228    *
 229    * @SINCE_1_0.0
 230    * @param[in] rhs The vector to multiply
 231    * @return Itself
 232    */
 233   Vector2& operator*=(const Vector2& rhs)
 234   {
 235     x *= rhs.x;
 236     y *= rhs.y;
 237
 238     return *this;
 239   }
 240
 241   /**
 242    * @brief Multiplication assignment operator.
 243    *
 244    * @SINCE_1_0.0
 245    * @param[in] rhs The float value to scale the vector
 246    * @return Itself
 247    */
 248   Vector2& operator*=(float rhs)
 249   {
 250     x *= rhs;
 251     y *= rhs;
 252
 253     return *this;
 254   }
 255
 256   /**
 257    * @brief Division operator.
 258    *
 259    * @SINCE_1_0.0
 260    * @param[in] rhs The vector to divide
 261    * @return A vector containing the result of the division
 262    */
 263   Vector2 operator/(const Vector2& rhs) const
 264   {
 265     return Vector2(x / rhs.x, y / rhs.y);
 266   }
 267
 268   /**
 269    * @brief Division operator.
 270    *
 271    * @SINCE_1_0.0
 272    * @param[in] rhs The float value to scale the vector by
 273    * @return A vector containing the result of the scaling
 274    */
 275   Vector2 operator/(float rhs) const
 276   {
 277     return Vector2(x / rhs, y / rhs);
 278   }
 279
 280
 281   /**
 282    * @brief Division assignment operator.
 283    *
 284    * @SINCE_1_0.0
 285    * @param[in] rhs The vector to divide
 286    * @return Itself
 287    */
 288   Vector2& operator/=(const Vector2& rhs)
 289   {
 290     x /= rhs.x;
 291     y /= rhs.y;
 292
 293     return *this;
 294   }
 295
 296   /**
 297    * @brief Division assignment operator.
 298    *
 299    * @SINCE_1_0.0
 300    * @param[in] rhs The float value to scale the vector by
 301    * @return Itself
 302    */
 303   Vector2& operator/=(float rhs)
 304   {
 305     x /= rhs;
 306     y /= rhs;
 307
 308     return *this;
 309   }
 310
 311   /**
 312    * @brief Unary negation operator.
 313    *
 314    * @SINCE_1_0.0
 315    * @return A vector containing the negation
 316    */
 317   Vector2 operator-() const
 318   {
 319     Vector2 temp(-x, -y);
 320
 321     return temp;
 322   }
 323
 324   /**
 325    * @brief Equality operator.
 326    *
 327    * Utilizes appropriate machine epsilon values.
 328    *
 329    * @SINCE_1_0.0
 330    * @param[in] rhs The vector to test against
 331    * @return true if the vectors are equal
 332    */
 333   bool operator==(const Vector2& rhs) const;
 334
 335   /**
 336    * @brief Inequality operator.
 337    *
 338    * Utilizes appropriate machine epsilon values.
 339    *
 340    * @SINCE_1_0.0
 341    * @param[in] rhs The vector to test against
 342    * @return true if the vectors are not equal
 343    */
 344   bool operator!=(const Vector2& rhs) const
 345   {
 346     return !(*this == rhs);
 347   }
 348
 349   /**
 350    * @brief Const array subscript operator overload.
 351    *
 352    * Asserts if index is out of range. Should be 0 or 1.
 353    * @SINCE_1_0.0
 354    * @param[in] index Subscript index
 355    * @return The float at the given index
 356    */
 357   const float& operator[](const unsigned int index) const
 358   {
 359     DALI_ASSERT_ALWAYS( index < 2 && "Vector element index out of bounds" );
 360
 361     return AsFloat()[index];
 362   }
 363
 364   /**
 365    * @brief Mutable array subscript operator overload.
 366    *
 367    * Asserts if index is out of range. Should be 0 or 1.
 368    * @SINCE_1_0.0
 369    * @param[in] index Subscript index
 370    * @return The float at the given index
 371    */
 372   float& operator[](const unsigned int index)
 373   {
 374     DALI_ASSERT_ALWAYS( index < 2 && "Vector element index out of bounds" );
 375
 376     return AsFloat()[index];
 377   }
 378
 379   /**
 380    * @brief Returns the length of the vector.
 381    *
 382    * @SINCE_1_0.0
 383    * @return The length of the vector
 384    */
 385   float Length() const;
 386
 387   /**
 388    * @brief Returns the length of the vector squared.
 389    *
 390    * This is more efficient than Length() for threshold
 391    * testing as it avoids the use of a square root.
 392    * @SINCE_1_0.0
 393    * @return The length of the vector squared
 394    */
 395   float LengthSquared() const;
 396
 397   /**
 398    * @brief Sets the vector to be unit length, whilst maintaining its direction.
 399    *
 400    * @SINCE_1_0.0
 401    */
 402   void Normalize();
 403
 404   /**
 405     * @brief Clamps the vector between minimum and maximum vectors.
 406     *
 407     * @SINCE_1_0.0
 408     * @param[in] min The minimum vector
 409     * @param[in] max The maximum vector
 410    */
 411   void Clamp( const Vector2& min, const Vector2& max );
 412
 413   /**
 414    * @brief Returns the contents of the vector as an array of 2 floats.
 415    *
 416    * The order of the values in this array are as follows:
 417    * 0: x (or width)
 418    * 1: y (or height)
 419    * @SINCE_1_0.0
 420    * @return The vector contents as an array of 2 floats
 421    * @note inlined for performance reasons (generates less code than a function call)
 422    */
 423   const float* AsFloat() const {return &x;}
 424
 425   /**
 426    * @brief Returns the contents of the vector as an array of 2 floats.
 427    *
 428    * The order of the values in this array are as follows:
 429    * 0: x (or width)
 430    * 1: y (or height)
 431    * @SINCE_1_0.0
 432    * @return The vector contents as an array of 2 floats
 433    * @note inlined for performance reasons (generates less code than a function call)
 434    */
 435   float* AsFloat() {return &x;}
 436
 437 public: // Data
 438
 439   // NOTE
 440   // (x width) and (y height) must be consecutive in memory.
 441   // No other data must be added before (x width) member.
 442   // No virtual methods must be added to this struct.
 443   union
 444   {
 445     float x;     ///< x component
 446     float width; ///< width
 447   };
 448
 449   union
 450   {
 451     float y;      ///< y component
 452     float height; ///< height
 453   };
 454
 455 };
 456
 457 /**
 458  * @brief Size is an alias of Dali::Vector2.
 459  * @SINCE_1_0.0
 460  */
 461 typedef Vector2 Size;
 462
 463 /**
 464  * @brief Print a Vector2.
 465  *
 466  * @SINCE_1_0.0
 467  * @param[in] o The output stream operator
 468  * @param[in] vector The vector to print
 469  * @return The output stream operator
 470  */
 471 DALI_IMPORT_API std::ostream& operator<< (std::ostream& o, const Vector2& vector);
 472
 473 /**
 474  * @brief Returns a vector with components set to the minimum of the corresponding component in a and b.
 475  *
 476  * If a=0,1 and b=1,0 returns a vector of 0,0.
 477  * @SINCE_1_0.0
 478  * @param[in] a A vector
 479  * @param[in] b A vector
 480  * @return A vector containing the minimum of each component from a and b
 481  */
 482 inline Vector2 Min( const Vector2& a, const Vector2& b )
 483 {
 484   return Vector2( a.x < b.x ? a.x : b.x , a.y < b.y ? a.y : b.y );
 485 }
 486
 487 /**
 488  * @brief Returns a vector with components set to the maximum of the corresponding component in a and b.
 489  *
 490  * If a=0,1 and b=1,0 returns a vector of 1,1.
 491  * @SINCE_1_0.0
 492  * @param[in] a A vector
 493  * @param[in] b A vector
 494  * @return A vector containing the maximum of each component from a and b
 495  */
 496 inline Vector2 Max( const Vector2& a, const Vector2& b )
 497 {
 498   return Vector2( a.x > b.x ? a.x : b.x , a.y > b.y ? a.y : b.y );
 499 }
 500
 501 /**
 502  * @brief Clamps each of vector v's components between minimum and maximum values.
 503  *
 504  * @SINCE_1_0.0
 505  * @param[in] v A vector
 506  * @param[in] min The minimum value
 507  * @param[in] max The maximum value
 508  * @return A vector containing the clamped components of v
 509  */
 510 DALI_IMPORT_API Vector2 Clamp( const Vector2& v, const float& min, const float& max );
 511
 512 // Allow Vector2 to be treated as a POD type
 513 template <> struct TypeTraits< Vector2 > : public BasicTypes< Vector2 > { enum { IS_TRIVIAL_TYPE = true }; };
 514
 515 /**
 516  * @}
 517  */
 518 } // namespace Dali
 519
 520 #endif // __DALI_VECTOR_2_H__