dali/public-api/math/vector3.h

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