dali/public-api/math/quaternion.h

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