Line data    Source code

       1              : /**
       2              :  * @file Quaternion.h
       3              :  * @brief Quaternion representation for 3D rotations.
       4              :  *
       5              :  * Quaternions are used throughout the engine for all rotation operations.
       6              :  * The standard pipeline is: build with buildFromEuler or buildFromAxis,
       7              :  * compose rotations with operator*, then emit a column-major rotation
       8              :  * matrix with buildRotationMatrix for use with OpenGL.
       9              :  *
      10              :  * See: https://en.wikipedia.org/wiki/Quaternion
      11              :  */
      12              : #ifndef _QUATERNION_H_
      13              : #define _QUATERNION_H_
      14              : 
      15              : #include "Matrix.h"
      16              : #include "Vector.h"
      17              : 
      18              : class Quaternion {
      19              :   public:
      20              :     Quaternion();
      21              :     /** Builds from Euler angles stored in v (radians). */
      22              :     Quaternion(const Vector&);
      23              :     /** Builds from Euler angles x, y, z (radians). */
      24              :     Quaternion(const float&, const float&, const float&);
      25              :     /**
      26              :      * Builds from an axis-angle pair. axis must be a unit vector;
      27              :      * angle is in radians.
      28              :      */
      29              :     Quaternion(const Vector&, const float&);
      30              :     Quaternion(const float&, const float&, const float&, const float&);
      31              :     Quaternion(const Quaternion &);
      32          592 :     ~Quaternion() {}
      33              : 
      34              :     /** Scales to unit length. No-op if the quaternion has zero length. */
      35              :     void normalize();
      36              : 
      37              :     /** Sets this quaternion from Euler angles in radians (x=pitch, y=yaw, z=roll). */
      38              :     void buildFromEuler(const Vector&);
      39              :     /** Sets this quaternion from Euler angles in radians (x=pitch, y=yaw, z=roll). */
      40              :     void buildFromEuler(const float&, const float&, const float&);
      41              :     /**
      42              :      * Sets this quaternion from an axis-angle pair. axis must be a unit
      43              :      * vector; angle is in radians. Does not normalise the result.
      44              :      */
      45              :     void buildFromAxis(const Vector&, const float&);
      46              : 
      47              :     void loadMultIdentity();
      48              :     void loadAddIdentity();
      49              : 
      50              :     /**
      51              :      * Extracts Euler angles into v (radians). Uses a gimbal-lock fallback
      52              :      * when the rotation matrix element m.data[2] reaches ±1; in that case
      53              :      * v.z is forced to zero. Not a guaranteed roundtrip with buildFromEuler
      54              :      * for all inputs.
      55              :      */
      56              :     void getEulerAngles(Vector&);
      57              : 
      58              :     void buildRotationMatrix(Matrix&);
      59              : 
      60              :     /**
      61              :      * Spherical linear interpolation from sQ to eQ at parameter t.
      62              :      * t must be in [0, 1]; values outside that range leave this
      63              :      * quaternion unchanged.
      64              :      */
      65              :     void slerp(const Quaternion &, const float&, const Quaternion&);
      66              : 
      67              :     // accessor functions
      68           31 :     float getX() const { return(x); }
      69           28 :     float getY() const { return(y); }
      70           30 :     float getZ() const { return(z); }
      71           34 :     float getW() const { return(w); }
      72              : 
      73              :     // overloaded operators
      74              :     Quaternion operator+(const Quaternion&) const;
      75              :     /** Composes two quaternion rotations using the engine's multiplication convention. */
      76              :     Quaternion operator*(const Quaternion&) const;
      77              :     Quaternion&     operator=(const Quaternion&);
      78              : 
      79              :   private:
      80              :     float x, y, z, w;
      81              : };
      82              : 
      83              : #endif