dali/public-api/math/quaternion.h

   1 #ifndef DALI_QUATERNION_H
   2 #define DALI_QUATERNION_H
   3
   4 /*
   5  * Copyright (c) 2020 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/constants.h>
  26 #include <dali/public-api/common/dali-common.h>
  27 #include <dali/public-api/common/type-traits.h>
  28 #include <dali/public-api/math/radian.h>
  29 #include <dali/public-api/math/vector4.h>
  30
  31 namespace Dali
  32 {
  33 /**
  34  * @addtogroup dali_core_math
  35  * @{
  36  */
  37
  38 // Forward declaration
  39 class Matrix;
  40
  41 /**
  42  * @brief The Quaternion class encapsulates the mathematics of the quaternion.
  43  * @SINCE_1_0.0
  44  */
  45 class DALI_CORE_API Quaternion
  46 {
  47 public:
  48   /**
  49    * @brief Default Constructor.
  50    * @SINCE_1_0.0
  51    */
  52   Quaternion();
  53
  54   /**
  55    * @brief Constructs from a quaternion represented by floats.
  56    *
  57    * @SINCE_1_0.0
  58    * @param[in] cosThetaBy2
  59    * @param[in] iBySineTheta
  60    * @param[in] jBySineTheta
  61    * @param[in] kBySineTheta
  62    */
  63   Quaternion(float cosThetaBy2, float iBySineTheta, float jBySineTheta, float kBySineTheta);
  64
  65   /**
  66    * @brief Constructs from a quaternion represented by a vector.
  67    *
  68    * @SINCE_1_0.0
  69    * @param[in] vector x,y,z fields represent i,j,k coefficients, w represents cos(theta/2)
  70    */
  71   explicit Quaternion(const Vector4& vector);
  72
  73   /**
  74    * @brief Constructor from an axis and angle.
  75    *
  76    * @SINCE_1_0.0
  77    * @param[in] angle The angle around the axis
  78    * @param[in] axis  The vector of the axis
  79    */
  80   Quaternion(Radian angle, const Vector3& axis);
  81
  82   /**
  83    * @brief Constructs from Euler angles.
  84    *
  85    * @SINCE_1_0.0
  86    * @param[in] pitch
  87    * @param[in] yaw
  88    * @param[in] roll
  89    */
  90   Quaternion(Radian pitch, Radian yaw, Radian roll);
  91
  92   /**
  93    * @brief Constructs from a matrix.
  94    *
  95    * @SINCE_1_0.0
  96    * @param[in] matrix
  97    */
  98   explicit Quaternion(const Matrix& matrix);
  99
 100   /**
 101    * @brief Constructs from 3 orthonormal axes.
 102    *
 103    * @SINCE_1_0.0
 104    * @param[in] xAxis The X axis
 105    * @param[in] yAxis The Y axis
 106    * @param[in] zAxis The Z axis
 107    */
 108   explicit Quaternion(const Vector3& xAxis, const Vector3& yAxis, const Vector3& zAxis);
 109
 110   /**
 111    * @brief Constructs quaternion which describes minimum rotation to align v0 with v1.
 112    * @SINCE_1_0.0
 113    * @param[in] v0 First normalized vector
 114    * @param[in] v1 Second normalized vector
 115    * @pre v0 and v1 should be normalized
 116    *
 117    */
 118   explicit Quaternion(const Vector3& v0, const Vector3& v1);
 119
 120   /**
 121    * @brief Destructor, nonvirtual as this is not a base class.
 122    *
 123    * @SINCE_1_0.0
 124    */
 125   ~Quaternion();
 126
 127   // Constants
 128
 129   static const Quaternion IDENTITY; ///< (0.0f,0.0f,0.0f,1.0f)
 130
 131   /**
 132    * @brief Helper to check if this is an identity quaternion.
 133    *
 134    * @SINCE_1_0.0
 135    * @return True if this is identity quaternion
 136    */
 137   bool IsIdentity() const;
 138
 139   /**
 140    * @brief Converts the quaternion to an axis/angle pair.
 141    *
 142    * @SINCE_1_0.0
 143    * @param[out] axis
 144    * @param[out] angle Angle in radians
 145    * @return True if converted correctly
 146    */
 147   bool ToAxisAngle(Vector3& axis, Radian& angle) const;
 148
 149   /**
 150    * @brief Returns the quaternion as a vector.
 151    *
 152    * @SINCE_1_0.0
 153    * @return The vector representation of the quaternion
 154    */
 155   const Vector4& AsVector() const;
 156
 157   /**
 158    * @brief SetEuler sets the quaternion from the Euler angles applied in x, y, z order.
 159    *
 160    * @SINCE_1_0.0
 161    * @param[in] pitch
 162    * @param[in] yaw
 163    * @param[in] roll
 164    */
 165   void SetEuler(Radian pitch, Radian yaw, Radian roll);
 166
 167   /**
 168    * @brief Returns the Euler angles from a rotation Quaternion.
 169    *
 170    * @SINCE_1_0.0
 171    * @return A vector of Euler angles (x == pitch, y == yaw, z == roll)
 172    */
 173   Vector4 EulerAngles() const;
 174
 175   /**
 176    * @brief Addition operator.
 177    *
 178    * @SINCE_1_0.0
 179    * @param[in] other The quaternion to add
 180    * @return A quaternion containing the result of the addition
 181    */
 182   const Quaternion operator+(const Quaternion& other) const;
 183
 184   /**
 185    * @brief Subtraction operator.
 186    *
 187    * @SINCE_1_0.0
 188    * @param[in] other The quaternion to subtract
 189    * @return A quaternion containing the result of the subtract
 190    */
 191   const Quaternion operator-(const Quaternion& other) const;
 192
 193   /**
 194    * @brief Multiplication operator.
 195    *
 196    * @SINCE_1_0.0
 197    * @param[in] other The quaternion to multiply
 198    * @return A quaternion containing the result
 199    */
 200   const Quaternion operator*(const Quaternion& other) const;
 201
 202   /**
 203    * @brief Multiplication operator.
 204    *
 205    * @SINCE_1_0.0
 206    * @param[in] other The vector to multiply
 207    * @return A vector containing the result of the multiplication
 208    */
 209   Vector3 operator*(const Vector3& other) const;
 210
 211   /**
 212    * @brief Division operator.
 213    *
 214    * @SINCE_1_0.0
 215    * @param[in] other A quaternion to divide by
 216    * @return A quaternion containing the result
 217    */
 218   const Quaternion operator/(const Quaternion& other) const;
 219
 220   /**
 221    * @brief Scale operator.
 222    *
 223    * @SINCE_1_0.0
 224    * @param[in] scale A value to scale by
 225    * @return A quaternion containing the result
 226    */
 227   const Quaternion operator*(float scale) const;
 228
 229   /**
 230    * @brief Scale operator.
 231    *
 232    * @SINCE_1_0.0
 233    * @param[in] scale A value to scale by
 234    * @return A quaternion containing the result
 235    */
 236   const Quaternion operator/(float scale) const;
 237
 238   /**
 239    * @brief Unary Negation operator.
 240    *
 241    * @SINCE_1_0.0
 242    * @return A quaternion containing the negated result
 243    */
 244   Quaternion operator-() const;
 245
 246   /**
 247    * @brief Addition with Assignment operator.
 248    *
 249    * @SINCE_1_0.0
 250    * @param[in] other The quaternion to add
 251    * @return A reference to this
 252    */
 253   const Quaternion& operator+=(const Quaternion& other);
 254
 255   /**
 256    * @brief Subtraction with Assignment operator.
 257    *
 258    * @SINCE_1_0.0
 259    * @param[in] other The quaternion to subtract
 260    * @return A reference to this
 261    */
 262   const Quaternion& operator-=(const Quaternion& other);
 263
 264   /**
 265    * @brief Multiplication with Assignment operator.
 266    *
 267    * @SINCE_1_0.0
 268    * @param[in] other The quaternion to multiply
 269    * @return A reference to this
 270    */
 271   const Quaternion& operator*=(const Quaternion& other);
 272
 273   /**
 274    * @brief Scale with Assignment operator.
 275    *
 276    * @SINCE_1_0.0
 277    * @param[in] scale the value to scale by
 278    * @return A reference to this
 279    */
 280   const Quaternion& operator*=(float scale);
 281
 282   /**
 283    * @brief Scale with Assignment operator.
 284    *
 285    * @SINCE_1_0.0
 286    * @param[in] scale The value to scale by
 287    * @return A reference to this
 288    */
 289   const Quaternion& operator/=(float scale);
 290
 291   /**
 292    * @brief Equality operator.
 293    *
 294    * @SINCE_1_0.0
 295    * @param[in] rhs The quaternion to compare with
 296    * @return True if the quaternions are equal
 297    */
 298   bool operator==(const Quaternion& rhs) const;
 299
 300   /**
 301    * @brief Inequality operator.
 302    *
 303    * @SINCE_1_0.0
 304    * @param[in] rhs The quaternion to compare with
 305    * @return True if the quaternions are not equal
 306    */
 307   bool operator!=(const Quaternion& rhs) const;
 308
 309   /**
 310    * @brief Returns the length of the quaternion.
 311    *
 312    * @SINCE_1_0.0
 313    * @return The length of the quaternion
 314    */
 315   float Length() const;
 316
 317   /**
 318    * @brief Returns the squared length of the quaternion.
 319    *
 320    * @SINCE_1_0.0
 321    * @return The squared length of the quaternion
 322    */
 323   float LengthSquared() const;
 324
 325   /**
 326    * @brief Normalizes this to unit length.
 327    *
 328    * @SINCE_1_0.0
 329    */
 330   void Normalize();
 331
 332   /**
 333    * @brief Normalized.
 334    *
 335    * @SINCE_1_0.0
 336    * @return A normalized version of this quaternion
 337    */
 338   Quaternion Normalized() const;
 339
 340   /**
 341    * @brief Conjugates this quaternion.
 342    *
 343    * @SINCE_1_0.0
 344    */
 345   void Conjugate();
 346
 347   /**
 348    * @brief Inverts this quaternion.
 349    *
 350    * @SINCE_1_0.0
 351    */
 352   void Invert();
 353
 354   /**
 355    * @brief Performs the logarithm of a Quaternion = v*a where q = (cos(a),v*sin(a)).
 356    *
 357    * @SINCE_1_0.0
 358    * @return A quaternion representing the logarithm
 359    */
 360   Quaternion Log() const;
 361
 362   /**
 363    * @brief Performs an exponent e^Quaternion = Exp(v*a) = (cos(a),vsin(a)).
 364    *
 365    * @SINCE_1_0.0
 366    * @return A quaternion representing the exponent
 367    */
 368   Quaternion Exp() const;
 369
 370   /**
 371    * @brief Returns the dot product of two quaternions.
 372    *
 373    * @SINCE_1_0.0
 374    * @param[in] q1 The first quaternion
 375    * @param[in] q2 The second quaternion
 376    * @return The dot product of the two quaternions
 377    */
 378   static float Dot(const Quaternion& q1, const Quaternion& q2);
 379
 380   /**
 381    * @brief Linear Interpolation (using a straight line between the two quaternions).
 382    *
 383    * @SINCE_1_0.0
 384    * @param[in] q1 The start quaternion
 385    * @param[in] q2 The end quaternion
 386    * @param[in] t A progress value between 0 and 1
 387    * @return The interpolated quaternion
 388    */
 389   static Quaternion Lerp(const Quaternion& q1, const Quaternion& q2, float t);
 390
 391   /**
 392    * @brief Spherical Linear Interpolation (using the shortest arc of a great circle between
 393    * the two quaternions).
 394    *
 395    * @SINCE_1_0.0
 396    * @param[in] q1 The start quaternion
 397    * @param[in] q2 The end quaternion
 398    * @param[in] progress A progress value between 0 and 1
 399    * @return The interpolated quaternion
 400    */
 401   static Quaternion Slerp(const Quaternion& q1, const Quaternion& q2, float progress);
 402
 403   /**
 404    * @brief This version of Slerp, used by Squad, does not check for theta > 90.
 405    *
 406    * @SINCE_1_0.0
 407    * @param[in] q1 The start quaternion
 408    * @param[in] q2 The end quaternion
 409    * @param[in] t A progress value between 0 and 1
 410    * @return The interpolated quaternion
 411    */
 412   static Quaternion SlerpNoInvert(const Quaternion& q1, const Quaternion& q2, float t);
 413
 414   /**
 415    * @brief Spherical Cubic Interpolation.
 416    *
 417    * @SINCE_1_0.0
 418    * @param[in] start The start quaternion
 419    * @param[in] end The end quaternion
 420    * @param[in] ctrl1 The control quaternion for q1
 421    * @param[in] ctrl2 The control quaternion for q2
 422    * @param[in] t A progress value between 0 and 1
 423    * @return The interpolated quaternion
 424    */
 425   static Quaternion Squad(const Quaternion& start, const Quaternion& end, const Quaternion& ctrl1, const Quaternion& ctrl2, float t);
 426
 427   /**
 428    * @brief Returns the shortest angle between two quaternions in Radians.
 429    *
 430    * @SINCE_1_0.0
 431    * @param[in] q1 The first quaternion
 432    * @param[in] q2 The second quaternion
 433    * @return The angle between the two quaternions
 434    */
 435   static float AngleBetween(const Quaternion& q1, const Quaternion& q2);
 436
 437   /**
 438    * @brief Rotates v by this Quaternion (Quaternion must be unit).
 439    *
 440    * @SINCE_1_0.0
 441    * @param[in] vector A vector to rotate
 442    * @return The rotated vector
 443    */
 444   Vector4 Rotate(const Vector4& vector) const;
 445
 446   /**
 447    * @brief Rotates v by this Quaternion (Quaternion must be unit).
 448    *
 449    * @SINCE_1_0.0
 450    * @param[in] vector A vector to rotate
 451    * @return The rotated vector
 452    */
 453   Vector3 Rotate(const Vector3& vector) const;
 454
 455 private:
 456   /// @cond internal
 457   /**
 458    * @brief Sets the quaternion from 3 orthonormal axes.
 459    *
 460    * @SINCE_1_0.0
 461    * @param[in] xAxis The X axis
 462    * @param[in] yAxis The Y axis
 463    * @param[in] zAxis The Z axis
 464    */
 465   DALI_INTERNAL void SetFromAxes(const Vector3& xAxis, const Vector3& yAxis, const Vector3& zAxis);
 466   /// @endcond
 467
 468 public:
 469   Quaternion(const Quaternion&) = default;            ///< Default copy constructor
 470   Quaternion(Quaternion&&)      = default;            ///< Default move constructor
 471   Quaternion& operator=(const Quaternion&) = default; ///< Default copy assignment operator
 472   Quaternion& operator=(Quaternion&&) = default;      ///< Default move assignment operator
 473
 474 public:
 475   Vector4 mVector; ///< w component is s ( = cos(theta/2.0) )
 476 };
 477
 478 /**
 479  * @brief Prints a Quaternion.
 480  *
 481  * @SINCE_1_0.0
 482  * @param[in] o The output stream operator
 483  * @param[in] quaternion The quaternion to print
 484  * @return The output stream operator
 485  */
 486 DALI_CORE_API std::ostream& operator<<(std::ostream& o, const Quaternion& quaternion);
 487
 488 // Allow Quaternion to be treated as a POD type
 489 template<>
 490 struct TypeTraits<Quaternion> : public BasicTypes<Quaternion>
 491 {
 492   enum
 493   {
 494     IS_TRIVIAL_TYPE = true
 495   };
 496 };
 497
 498 /**
 499  * @}
 500  */
 501 } // namespace Dali
 502
 503 #endif // DALI_QUATERNION_H