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