dali/public-api/math/vector3.h

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