dali/public-api/math/quaternion.h

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