dali/public-api/math/vector3.h

   1 #ifndef DALI_VECTOR_3_H
   2 #define DALI_VECTOR_3_H
   3
   4 /*
   5  * Copyright (c) 2022 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 constexpr 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
 478   {
 479     return &x;
 480   }
 481
 482   /**
 483    * @brief Returns the contents of the vector as an array of 3 floats.
 484    *
 485    * The order of the values in this array are as follows:
 486    * 0: x (or width, or r)
 487    * 1: y (or height, or g)
 488    * 2: z (or depth, or b)
 489    * @SINCE_1_0.0
 490    * @return The vector contents as an array of 3 floats
 491    * @note inlined for performance reasons (generates less code than a function call)
 492    */
 493   float* AsFloat()
 494   {
 495     return &x;
 496   }
 497
 498   /**
 499    * @brief Returns the x & y components (or width & height, or r & g) as a Vector2.
 500    *
 501    * @SINCE_1_0.0
 502    * @return The partial vector contents as Vector2 (x,y)
 503    * @note inlined for performance reasons (generates less code than a function call)
 504    */
 505   const Vector2& GetVectorXY() const
 506   {
 507     return reinterpret_cast<const Vector2&>(x);
 508   }
 509
 510   /**
 511    * @brief Returns the x & y components (or width & height, or r & g) as a Vector2.
 512    *
 513    * @SINCE_1_0.0
 514    * @return The partial vector contents as Vector2 (x,y)
 515    * @note inlined for performance reasons (generates less code than a function call)
 516    */
 517   Vector2& GetVectorXY()
 518   {
 519     return reinterpret_cast<Vector2&>(x);
 520   }
 521
 522   /**
 523    * @brief Returns the y & z components (or height & depth, or g & b) as a Vector2.
 524    *
 525    * @SINCE_1_0.0
 526    * @return The partial vector contents as Vector2 (y,z)
 527    * @note inlined for performance reasons (generates less code than a function call)
 528    */
 529   const Vector2& GetVectorYZ() const
 530   {
 531     return reinterpret_cast<const Vector2&>(y);
 532   }
 533
 534   /**
 535    * @brief Returns the y & z components (or height & depth, or g & b) as a Vector2.
 536    *
 537    * @SINCE_1_0.0
 538    * @return The partial vector contents as Vector2 (y,z)
 539    * @note inlined for performance reasons (generates less code than a function call)
 540    */
 541   Vector2& GetVectorYZ()
 542   {
 543     return reinterpret_cast<Vector2&>(y);
 544   }
 545
 546   // Data
 547
 548   // NOTE
 549   // (x width r), (y height g), (z depth b) must be consecutive in memory.
 550   // No other data must be added before (x width r) member.
 551   // No virtual methods must be added to this struct.
 552   union
 553   {
 554     float x;     ///< x component
 555     float width; ///< width component
 556     float r;     ///< red component
 557   };
 558   union
 559   {
 560     float y;      ///< y component
 561     float height; ///< height component
 562     float g;      ///< green component
 563   };
 564   union
 565   {
 566     float z;     ///< z component
 567     float depth; ///< depth component
 568     float b;     ///< blue component
 569   };
 570
 571 public:
 572   Vector3(const Vector3&)     = default;            ///< Default copy constructor
 573   Vector3(Vector3&&) noexcept = default;            ///< Default move constructor
 574   Vector3& operator=(const Vector3&) = default;     ///< Default copy assignment operator
 575   Vector3& operator=(Vector3&&) noexcept = default; ///< Default move assignment operator
 576 };
 577
 578 /**
 579  * @brief Prints a Vector3.
 580  *
 581  * @SINCE_1_0.0
 582  * @param[in] o The output stream operator
 583  * @param[in] vector The vector to print
 584  * @return The output stream operator
 585  */
 586 DALI_CORE_API std::ostream& operator<<(std::ostream& o, const Vector3& vector);
 587
 588 /**
 589  * @brief Returns a vector with components set to the minimum of the corresponding component in a and b.
 590  *
 591  * If a=0,1,2 and b=2,1,0  returns a vector of 2,1,2.
 592  * @SINCE_1_0.0
 593  * @param[in] a A vector
 594  * @param[in] b A vector
 595  * @return A vector containing the minimum of each component from a and b
 596  */
 597 inline Vector3 Min(const Vector3& a, const Vector3& b)
 598 {
 599   return Vector3(a.x < b.x ? a.x : b.x,
 600                  a.y < b.y ? a.y : b.y,
 601                  a.z < b.z ? a.z : b.z);
 602 }
 603
 604 /**
 605  * @brief Returns a vector with components set to the maximum of the corresponding component in a and b.
 606  *
 607  * If a=0,1 and b=1,0  returns a vector of 1,1.
 608  * @SINCE_1_0.0
 609  * @param[in] a A vector
 610  * @param[in] b A vector
 611  * @return A vector containing the maximum of each component from a and b
 612  */
 613 inline Vector3 Max(const Vector3& a, const Vector3& b)
 614 {
 615   return Vector3(a.x > b.x ? a.x : b.x,
 616                  a.y > b.y ? a.y : b.y,
 617                  a.z > b.z ? a.z : b.z);
 618 }
 619
 620 /**
 621  * @brief Clamps each of vector v's components between minimum and maximum values.
 622  *
 623  * @SINCE_1_0.0
 624  * @param[in] v A vector
 625  * @param[in] min The minimum value
 626  * @param[in] max The maximum value
 627  * @return A vector containing the clamped components of v
 628  */
 629 DALI_CORE_API Vector3 Clamp(const Vector3& v, const float& min, const float& max);
 630
 631 // Allow Vector3 to be treated as a POD type
 632 template<>
 633 struct TypeTraits<Vector3> : public BasicTypes<Vector3>
 634 {
 635   enum
 636   {
 637     IS_TRIVIAL_TYPE = true
 638   };
 639 };
 640
 641 /**
 642  * @}
 643  */
 644 } // namespace Dali
 645
 646 #endif // DALI_VECTOR_3_H