|  | overview |  | wiki |  | api reference |  | download

- Main Page
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Functions Variables Typedefs Enumerations Enumerator
Public Member Functions | Static Public Member Functions | Public Attributes
gameplay::Quaternion Class Reference

`#include <Quaternion.h>`

List of all members.

## Public Member Functions

| Quaternion ()
| Quaternion (float x, float y, float z, float w)
| Quaternion (float *array)
| Quaternion (const Matrix &m)
| Quaternion (const Vector3 &axis, float angle)
| Quaternion (const Quaternion &copy)
| ~Quaternion ()
bool | isIdentity () const
bool | isZero () const
void | conjugate ()
void | conjugate (Quaternion *dst) const
bool | inverse ()
bool | inverse (Quaternion *dst) const
void | multiply (const Quaternion &q)
void | normalize ()
void | normalize (Quaternion *dst) const
void | set (float x, float y, float z, float w)
void | set (float *array)
void | set (const Matrix &m)
void | set (const Vector3 &axis, float angle)
void | set (const Quaternion &q)
void | setIdentity ()
float | toAxisAngle (Vector3 *e) const
const Quaternion | operator* (const Quaternion &q) const
Quaternion & | operator*= (const Quaternion &q)

## Static Public Member Functions

static const Quaternion & | identity ()
static const Quaternion & | zero ()
static void | createFromRotationMatrix (const Matrix &m, Quaternion *dst)
static void | createFromAxisAngle (const Vector3 &axis, float angle, Quaternion *dst)
static void | multiply (const Quaternion &q1, const Quaternion &q2, Quaternion *dst)
static void | lerp (const Quaternion &q1, const Quaternion &q2, float t, Quaternion *dst)
static void | slerp (const Quaternion &q1, const Quaternion &q2, float t, Quaternion *dst)
static void | squad (const Quaternion &q1, const Quaternion &q2, const Quaternion &s1, const Quaternion &s2, float t, Quaternion *dst)

## Public Attributes

float | x
float | y
float | z
float | w

## Detailed Description

Defines a 4-element quaternion that represents the orientation of an object in space.

Quaternions are typically used as a replacement for euler angles and rotation matrices as a way to achieve smooth interpolation and avoid gimbal lock.

Note that this quaternion class does not automatically keep the quaternion normalized. Therefore, care must be taken to normalize the quaternion when necessary, by calling the normalize method. This class provides three methods for doing quaternion interpolation: lerp, slerp, and squad.

lerp (linear interpolation): the interpolation curve gives a straight line in quaternion space. It is simple and fast to compute. The only problem is that it does not provide constant angular velocity. Note that a constant velocity is not necessarily a requirement for a curve; slerp (spherical linear interpolation): the interpolation curve forms a great arc on the quaternion unit sphere. Slerp provides constant angular velocity; squad (spherical spline interpolation): interpolating between a series of rotations using slerp leads to the following problems:

- the curve is not smooth at the control points;
- the angular velocity is not constant;
- the angular velocity is not continuous at the control points.

Since squad is continuously differentiable, it remedies the first and third problems mentioned above. The slerp method provided here is intended for interpolation of principal rotations. It treats +q and -q as the same principal rotation and is at liberty to use the negative of either input. The resulting path is always the shorter arc.

The lerp method provided here interpolates strictly in quaternion space. Note that the resulting path may pass through the origin if interpolating between a quaternion and its exact negative.

As an example, consider the following quaternions:

q1 = (0.6, 0.8, 0.0, 0.0), q2 = (0.0, 0.6, 0.8, 0.0), q3 = (0.6, 0.0, 0.8, 0.0), and q4 = (-0.8, 0.0, -0.6, 0.0). For the point p = (1.0, 1.0, 1.0), the following figures show the trajectories of p using lerp, slerp, and squad.

## Constructor & Destructor Documentation

gameplay::Quaternion::Quaternion | ( |  | ) |

Constructs a quaternion initialized to (0, 0, 0, 1).

gameplay::Quaternion::Quaternion | ( | float | x,
|  | float | y,
|  | float | z,
|  | float | w
| ) |  |

Constructs a quaternion initialized to (0, 0, 0, 1).

Parameters:

  x | The x component of the quaternion.
  y | The y component of the quaternion.
  z | The z component of the quaternion.
  w | The w component of the quaternion.

gameplay::Quaternion::Quaternion | ( | float * | array | ) |

Constructs a new quaternion from the values in the specified array.

Parameters:

  array | The values for the new quaternion.

gameplay::Quaternion::Quaternion | ( | const Matrix & | m | ) |

Constructs a quaternion equal to the rotational part of the specified matrix.

Parameters:

  m | The matrix.

gameplay::Quaternion::Quaternion | ( | const Vector3 & | axis,
|  | float | angle
| ) |  |

Constructs a quaternion equal to the rotation from the specified axis and angle.

Parameters:

  axis | A vector describing the axis of rotation.
  angle | The angle of rotation (in radians).

gameplay::Quaternion::Quaternion | ( | const Quaternion & | copy | ) |

Constructs a new quaternion that is a copy of the specified one.

Parameters:

  copy | The quaternion to copy.

gameplay::Quaternion::~Quaternion | ( |  | ) |

Destructor.

## Member Function Documentation

void gameplay::Quaternion::conjugate | ( |  | ) |

Sets this quaternion to the conjugate of itself.

void gameplay::Quaternion::conjugate | ( | Quaternion * | dst | ) | const

Gets the conjugate of this quaternion in dst.

Parameters:

  dst | A quaternion to store the conjugate in.

static void gameplay::Quaternion::createFromAxisAngle | ( | const Vector3 & | axis,
|  | float | angle,
|  | Quaternion * | dst
| ) |  | `[static]`

Creates this quaternion equal to the rotation from the specified axis and angle and stores the result in dst.

Parameters:

  axis | A vector describing the axis of rotation.
  angle | The angle of rotation (in radians).
  dst | A quaternion to store the conjugate in.

static void gameplay::Quaternion::createFromRotationMatrix | ( | const Matrix & | m,
|  | Quaternion * | dst
| ) |  | `[static]`

Creates a quaternion equal to the rotational part of the specified matrix and stores the result in dst.

Parameters:

  m | The matrix.
  dst | A quaternion to store the conjugate in.

static const Quaternion& gameplay::Quaternion::identity | ( |  | ) | `[static]`

Returns the identity quaternion.

Returns:
  The identity quaternion.

bool gameplay::Quaternion::inverse | ( |  | ) |

Sets this quaternion to the inverse of itself.

Note that the inverse of a quaternion is equal to its conjugate when the quaternion is unit-length. For this reason, it is more efficient to use the conjugate method directly when you know your quaternion is already unit-length.

Returns:
  true if the inverse can be computed, false otherwise.

bool gameplay::Quaternion::inverse | ( | Quaternion * | dst | ) | const

Gets the inverse of this quaternion in dst.

Note that the inverse of a quaternion is equal to its conjugate when the quaternion is unit-length. For this reason, it is more efficient to use the conjugate method directly when you know your quaternion is already unit-length.

Parameters:

  dst | A quaternion to store the inverse in.

Returns:
  true if the inverse can be computed, false otherwise.

bool gameplay::Quaternion::isIdentity | ( |  | ) | const

Determines if this quaternion is equal to the identity quaternion.

Returns:
  true if it is the identity quaternion, false otherwise.

bool gameplay::Quaternion::isZero | ( |  | ) | const

Determines if this quaternion is all zeros.

Returns:
  true if this quaternion is all zeros, false otherwise.

static void gameplay::Quaternion::lerp | ( | const Quaternion & | q1,
|  | const Quaternion & | q2,
|  | float | t,
|  | Quaternion * | dst
| ) |  | `[static]`

Interpolates between two quaternions using linear interpolation.

The interpolation curve for linear interpolation between quaternions gives a straight line in quaternion space.

Parameters:

  q1 | The first quaternion.
  q2 | The second quaternion.
  t | The interpolation coefficient.
  dst | A quaternion to store the result in.

void gameplay::Quaternion::multiply | ( | const Quaternion & | q | ) |

Multiplies this quaternion by the specified one and stores the result in this quaternion.

Parameters:

  q | The quaternion to multiply.

static void gameplay::Quaternion::multiply | ( | const Quaternion & | q1,
|  | const Quaternion & | q2,
|  | Quaternion * | dst
| ) |  | `[static]`

Multiplies the specified quaternions and stores the result in dst.

Parameters:

  q1 | The first quaternion.
  q2 | The second quaternion.
  dst | A quaternion to store the result in.

void gameplay::Quaternion::normalize | ( |  | ) |

Normalizes this quaternion to have unit length.

If the quaternion already has unit length or if the length of the quaternion is zero, this method does nothing.

void gameplay::Quaternion::normalize | ( | Quaternion * | dst | ) | const

Normalizes this quaternion and stores the result in dst.

If the quaternion already has unit length or if the length of the quaternion is zero, this method simply copies this vector into dst.

Parameters:

  dst | A quaternion to store the result in.

const Quaternion gameplay::Quaternion::operator* | ( | const Quaternion & | q | ) | const`[inline]`

Calculates the quaternion product of this quaternion with the given quaternion.

Note: this does not modify this quaternion.

Parameters:

  q | The quaternion to multiply.

Returns:
  The quaternion product.

Quaternion& gameplay::Quaternion::operator*= | ( | const Quaternion & | q | ) | `[inline]`

Multiplies this quaternion with the given quaternion.

Parameters:

  q | The quaternion to multiply.

Returns:
  This quaternion, after the multiplication occurs.

void gameplay::Quaternion::set | ( | float | x,
|  | float | y,
|  | float | z,
|  | float | w
| ) |  |

Sets the elements of the quaternion to the specified values.

Parameters:

  x | The new x-value.
  y | The new y-value.
  z | The new z-value.
  w | The new w-value.

void gameplay::Quaternion::set | ( | float * | array | ) |

Sets the elements of the quaternion from the values in the specified array.

Parameters:

  array | An array containing the elements of the quaternion in the order x, y, z, w.

void gameplay::Quaternion::set | ( | const Matrix & | m | ) |

Sets the quaternion equal to the rotational part of the specified matrix.

Parameters:

  m | The matrix.

void gameplay::Quaternion::set | ( | const Vector3 & | axis,
|  | float | angle
| ) |  |

Sets the quaternion equal to the rotation from the specified axis and angle.

Parameters:

  axis | The axis of rotation.
  angle | The angle of rotation (in radians).

void gameplay::Quaternion::set | ( | const Quaternion & | q | ) |

Sets the elements of this quaternion to a copy of the specified quaternion.

Parameters:

  q | The quaternion to copy.

void gameplay::Quaternion::setIdentity | ( |  | ) |

Sets this quaternion to be equal to the identity quaternion.

static void gameplay::Quaternion::slerp | ( | const Quaternion & | q1,
|  | const Quaternion & | q2,
|  | float | t,
|  | Quaternion * | dst
| ) |  | `[static]`

Interpolates between two quaternions using spherical linear interpolation.

Spherical linear interpolation provides smooth transitions between different orientations and is often useful for animating models or cameras in 3D.

Note: For accurate interpolation, the input quaternions must be at (or close to) unit length. This method does not automatically normalize the input quaternions, so it is up to the caller to ensure they call normalize beforehand, if necessary.

Parameters:

  q1 | The first quaternion.
  q2 | The second quaternion.
  t | The interpolation coefficient.
  dst | A quaternion to store the result in.

static void gameplay::Quaternion::squad | ( | const Quaternion & | q1,
|  | const Quaternion & | q2,
|  | const Quaternion & | s1,
|  | const Quaternion & | s2,
|  | float | t,
|  | Quaternion * | dst
| ) |  | `[static]`

Interpolates over a series of quaternions using spherical spline interpolation.

Spherical spline interpolation provides smooth transitions between different orientations and is often useful for animating models or cameras in 3D.

Note: For accurate interpolation, the input quaternions must be unit. This method does not automatically normalize the input quaternions, so it is up to the caller to ensure they call normalize beforehand, if necessary.

Parameters:

  q1 | The first quaternion.
  q2 | The second quaternion.
  s1 | The first control point.
  s2 | The second control point.
  t | The interpolation coefficient.
  dst | A quaternion to store the result in.

float gameplay::Quaternion::toAxisAngle | ( | Vector3 * | e | ) | const

Converts this Quaternion4f to axis-angle notation. The axis is normalized.

Parameters:

  e | The Vector3f which stores the axis.

Returns:
  The angle (in radians).

static const Quaternion& gameplay::Quaternion::zero | ( |  | ) | `[static]`

Returns the quaternion with all zeros.

Returns:
  The quaternion.

## Member Data Documentation

float gameplay::Quaternion::w

The scalar component of the quaternion.

float gameplay::Quaternion::x

The x-value of the quaternion's vector component.

float gameplay::Quaternion::y

The y-value of the quaternion's vector component.

float gameplay::Quaternion::z

The z-value of the quaternion's vector component.

All Classes Functions Variables Typedefs Enumerations Enumerator