Quaternion Class Reference

Description

Represents a quaternion used for 3D rotations.

Methods

 Quaternion (BS_ZERO zero)
 
 Quaternion (BS_IDENTITY identity)
 
 Quaternion (float w, float x, float y, float z)
 
 Quaternion (const Matrix3 &rot)
 Construct a quaternion from a rotation matrix. More...
 
 Quaternion (const Vector3 &axis, const Radian &angle)
 Construct a quaternion from an angle/axis. More...
 
 Quaternion (const Vector3 &xaxis, const Vector3 &yaxis, const Vector3 &zaxis)
 Construct a quaternion from 3 orthonormal local axes. More...
 
 Quaternion (const Radian &xAngle, const Radian &yAngle, const Radian &zAngle)
 Construct a quaternion from euler angles, YXZ ordering. More...
 
 Quaternion (const Radian &xAngle, const Radian &yAngle, const Radian &zAngle, EulerAngleOrder order)
 Construct a quaternion from euler angles, custom ordering. More...
 
void swap (Quaternion &other)
 Exchange the contents of this quaternion with another. More...
 
float operator[] (const size_t i) const
 
float & operator[] (const size_t i)
 
void fromRotationMatrix (const Matrix3 &mat)
 Initializes the quaternion from a 3x3 rotation matrix. More...
 
void fromAxisAngle (const Vector3 &axis, const Radian &angle)
 Initializes the quaternion from an angle axis pair. More...
 
void fromAxes (const Vector3 &xAxis, const Vector3 &yAxis, const Vector3 &zAxis)
 Initializes the quaternion from orthonormal set of axes. More...
 
void fromEulerAngles (const Radian &xAngle, const Radian &yAngle, const Radian &zAngle)
 Creates a quaternion from the provided Pitch/Yaw/Roll angles. More...
 
void fromEulerAngles (const Radian &xAngle, const Radian &yAngle, const Radian &zAngle, EulerAngleOrder order)
 Creates a quaternion from the provided Pitch/Yaw/Roll angles. More...
 
void toRotationMatrix (Matrix3 &mat) const
 Converts a quaternion to a rotation matrix.
 
void toAxisAngle (Vector3 &axis, Radian &angle) const
 Converts a quaternion to an angle axis pair. More...
 
void toAxes (Vector3 &xAxis, Vector3 &yAxis, Vector3 &zAxis) const
 Converts a quaternion to an orthonormal set of axes. More...
 
bool toEulerAngles (Radian &xAngle, Radian &yAngle, Radian &zAngle) const
 Extracts Pitch/Yaw/Roll rotations from this quaternion. More...
 
Vector3 xAxis () const
 Gets the positive x-axis of the coordinate system transformed by this quaternion. More...
 
Vector3 yAxis () const
 Gets the positive y-axis of the coordinate system transformed by this quaternion. More...
 
Vector3 zAxis () const
 Gets the positive z-axis of the coordinate system transformed by this quaternion. More...
 
Quaternionoperator= (const Quaternion &rhs)
 
Quaternion operator+ (const Quaternion &rhs) const
 
Quaternion operator- (const Quaternion &rhs) const
 
Quaternion operator* (const Quaternion &rhs) const
 
Quaternion operator* (float rhs) const
 
Quaternion operator- () const
 
bool operator== (const Quaternion &rhs) const
 
bool operator!= (const Quaternion &rhs) const
 
Quaternionoperator+= (const Quaternion &rhs)
 
Quaternionoperator-= (const Quaternion &rhs)
 
Quaternionoperator*= (const Quaternion &rhs)
 
float dot (const Quaternion &other) const
 Calculates the dot product of this quaternion and another. More...
 
float normalize ()
 Normalizes this quaternion, and returns the previous length. More...
 
Quaternion inverse () const
 Gets the inverse. More...
 
Vector3 rotate (const Vector3 &vec) const
 Rotates the provided vector. More...
 
void lookRotation (const Vector3 &forwardDir)
 Orients the quaternion so its negative z axis points to the provided direction. More...
 
void lookRotation (const Vector3 &forwardDir, const Vector3 &upDir)
 Orients the quaternion so its negative z axis points to the provided direction. More...
 
bool isNaN () const
 Query if any of the components of the quaternion are not a number. More...
 

Static methods

static float dot (const Quaternion &lhs, const Quaternion &rhs)
 Calculates the dot product between two quaternions. More...
 
static Quaternion normalize (const Quaternion &q)
 Normalizes the provided quaternion. More...
 
static Quaternion slerp (float t, const Quaternion &p, const Quaternion &q, bool shortestPath=true)
 Performs spherical interpolation between two quaternions. More...
 
static Quaternion lerp (float t, const Quaternion &a, const Quaternion &b)
 Linearly interpolates between the two quaternions using t. More...
 
static Quaternion getRotationFromTo (const Vector3 &from, const Vector3 &dest, const Vector3 &fallbackAxis=Vector3::ZERO)
 Gets the shortest arc quaternion to rotate this vector to the destination vector. More...
 

Fields

float x
 
float y
 
float z
 
float w
 

Static fields

static const float EPSILON
 
static const Quaternion ZERO
 
static const Quaternion IDENTITY
 

Method documentation

float dot ( const Quaternion other) const

Calculates the dot product of this quaternion and another.

static float dot ( const Quaternion lhs,
const Quaternion rhs 
)
static

Calculates the dot product between two quaternions.

void fromAxes ( const Vector3 xAxis,
const Vector3 yAxis,
const Vector3 zAxis 
)

Initializes the quaternion from orthonormal set of axes.

Quaternion will represent a rotation from base axes to the specified set of axes.

Note
It's up to the caller to ensure the axes are orthonormal.
void fromAxisAngle ( const Vector3 axis,
const Radian angle 
)

Initializes the quaternion from an angle axis pair.

Quaternion will represent a rotation of "angle" radians around "axis".

void fromEulerAngles ( const Radian xAngle,
const Radian yAngle,
const Radian zAngle 
)

Creates a quaternion from the provided Pitch/Yaw/Roll angles.

Parameters
[in]xAngleRotation about x axis. (AKA Pitch)
[in]yAngleRotation about y axis. (AKA Yaw)
[in]zAngleRotation about z axis. (AKA Roll)
Note
Since different values will be produced depending in which order are the rotations applied, this method assumes they are applied in YXZ order. If you need a specific order, use the overloaded fromEulerAngles() method instead.
void fromEulerAngles ( const Radian xAngle,
const Radian yAngle,
const Radian zAngle,
EulerAngleOrder  order 
)

Creates a quaternion from the provided Pitch/Yaw/Roll angles.

Parameters
[in]xAngleRotation about x axis. (AKA Pitch)
[in]yAngleRotation about y axis. (AKA Yaw)
[in]zAngleRotation about z axis. (AKA Roll)
[in]orderThe order in which rotations will be extracted. Different values can be retrieved depending on the order.
void fromRotationMatrix ( const Matrix3 mat)

Initializes the quaternion from a 3x3 rotation matrix.

Note
It's up to the caller to ensure the matrix is orthonormal.
static Quaternion getRotationFromTo ( const Vector3 from,
const Vector3 dest,
const Vector3 fallbackAxis = Vector3::ZERO 
)
static

Gets the shortest arc quaternion to rotate this vector to the destination vector.

Quaternion inverse ( ) const

Gets the inverse.

Note
Quaternion must be non-zero.
bool isNaN ( ) const

Query if any of the components of the quaternion are not a number.

static Quaternion lerp ( float  t,
const Quaternion a,
const Quaternion b 
)
static

Linearly interpolates between the two quaternions using t.

t should be in [0, 1] range, where t = 0 corresponds to the left vector, while t = 1 corresponds to the right vector.

void lookRotation ( const Vector3 forwardDir)

Orients the quaternion so its negative z axis points to the provided direction.

Parameters
[in]forwardDirDirection to orient towards.
void lookRotation ( const Vector3 forwardDir,
const Vector3 upDir 
)

Orients the quaternion so its negative z axis points to the provided direction.

Parameters
[in]forwardDirDirection to orient towards.
[in]upDirConstrains y axis orientation to a plane this vector lies on. This rule might be broken if forward and up direction are nearly parallel.
float normalize ( )

Normalizes this quaternion, and returns the previous length.

static Quaternion normalize ( const Quaternion q)
static

Normalizes the provided quaternion.

Vector3 rotate ( const Vector3 vec) const

Rotates the provided vector.

static Quaternion slerp ( float  t,
const Quaternion p,
const Quaternion q,
bool  shortestPath = true 
)
static

Performs spherical interpolation between two quaternions.

Spherical interpolation neatly interpolates between two rotations without modifying the size of the vector it is applied to (unlike linear interpolation).

void swap ( Quaternion other)

Exchange the contents of this quaternion with another.

void toAxes ( Vector3 xAxis,
Vector3 yAxis,
Vector3 zAxis 
) const

Converts a quaternion to an orthonormal set of axes.

Parameters
[out]xAxisThe X axis.
[out]yAxisThe Y axis.
[out]zAxisThe Z axis.
void toAxisAngle ( Vector3 axis,
Radian angle 
) const

Converts a quaternion to an angle axis pair.

Parameters
[out]axisThe axis around the which rotation takes place.
[out]angleThe angle in radians determining amount of rotation around the axis.
bool toEulerAngles ( Radian xAngle,
Radian yAngle,
Radian zAngle 
) const

Extracts Pitch/Yaw/Roll rotations from this quaternion.

Parameters
[out]xAngleRotation about x axis. (AKA Pitch)
[out]yAngleRotation about y axis. (AKA Yaw)
[out]zAngleRotation about z axis. (AKA Roll)
Returns
True if unique solution was found, false otherwise.
Vector3 xAxis ( ) const

Gets the positive x-axis of the coordinate system transformed by this quaternion.

Vector3 yAxis ( ) const

Gets the positive y-axis of the coordinate system transformed by this quaternion.

Vector3 zAxis ( ) const

Gets the positive z-axis of the coordinate system transformed by this quaternion.

Constructor & Destructor Documentation

Quaternion ( const Matrix3 rot)
explicit

Construct a quaternion from a rotation matrix.

Quaternion ( const Vector3 axis,
const Radian angle 
)
explicit

Construct a quaternion from an angle/axis.

Quaternion ( const Vector3 xaxis,
const Vector3 yaxis,
const Vector3 zaxis 
)
explicit

Construct a quaternion from 3 orthonormal local axes.

Quaternion ( const Radian xAngle,
const Radian yAngle,
const Radian zAngle 
)
explicit

Construct a quaternion from euler angles, YXZ ordering.

See also
Quaternion::fromEulerAngles
Quaternion ( const Radian xAngle,
const Radian yAngle,
const Radian zAngle,
EulerAngleOrder  order 
)
explicit

Construct a quaternion from euler angles, custom ordering.

See also
Quaternion::fromEulerAngles