dali/public-api/math/vector3.h

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