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