dali/public-api/math/vector2.h

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