OGRE  1.12.13
Object-Oriented Graphics Rendering Engine
Ogre::Quaternion Class Reference

Implementation of a Quaternion, i.e. More...

#include <OgreQuaternion.h>

Public Member Functions

 Quaternion ()
 Default constructor, initializes to identity rotation (aka 0°) More...
 
 Quaternion (const Matrix3 &rot)
 Construct a quaternion from a rotation matrix. More...
 
 Quaternion (const Ogre::Quaternion &rhs)
 Copy constructor. More...
 
 Quaternion (const Radian &rfAngle, const Vector3 &rkAxis)
 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 Vector3 *akAxis)
 Construct a quaternion from 3 orthonormal local axes. More...
 
 Quaternion (float *valptr)
 Construct a quaternion from 4 manual w/x/y/z values. More...
 
 Quaternion (float fW, float fX, float fY, float fZ)
 Construct from an explicit list of values. More...
 
float Dot (const Quaternion &rkQ) const
 Returns the dot product of the quaternion. More...
 
bool equals (const Quaternion &rhs, const Radian &tolerance) const
 Equality with tolerance (tolerance is max angle difference) More...
 
Quaternion Exp () const
 Apply to unit-length quaternion. More...
 
void FromAngleAxis (const Radian &rfAngle, const Vector3 &rkAxis)
 Setups the quaternion using the supplied vector, and "roll" around that vector by the specified radians. More...
 
void FromAxes (const Vector3 &xAxis, const Vector3 &yAxis, const Vector3 &zAxis)
 
void FromAxes (const Vector3 *akAxis)
 Constructs the quaternion using 3 axes, the axes are assumed to be orthonormal. More...
 
void FromRotationMatrix (const Matrix3 &kRot)
 
Radian getPitch (bool reprojectAxis=true) const
 Calculate the local pitch element of this quaternion. More...
 
Radian getRoll (bool reprojectAxis=true) const
 Calculate the local roll element of this quaternion. More...
 
Radian getYaw (bool reprojectAxis=true) const
 Calculate the local yaw element of this quaternion. More...
 
Quaternion Inverse () const
 
bool isNaN () const
 Check whether this quaternion contains valid values. More...
 
Quaternion Log () const
 
float Norm () const
 Returns the normal length of this quaternion. More...
 
float normalise (void)
 Normalises this quaternion, and returns the previous length. More...
 
bool operator!= (const Quaternion &rhs) const
 
Quaternion operator* (const Quaternion &rkQ) const
 
Vector3 operator* (const Vector3 &rkVector) const
 Rotation of a vector by a quaternion. More...
 
Quaternion operator* (float s) const
 
Quaternion operator+ (const Quaternion &rkQ) const
 
Quaternion operator- () const
 
Quaternion operator- (const Quaternion &rkQ) const
 
Quaternionoperator= (const Quaternion &rkQ)
 
bool operator== (const Quaternion &rhs) const
 
float & operator[] (const size_t i)
 Array accessor operator. More...
 
float operator[] (const size_t i) const
 Array accessor operator. More...
 
bool orientationEquals (const Quaternion &other, float tolerance=1e-3f) const
 Compare two quaternions which are assumed to be used as orientations. More...
 
float * ptr ()
 Pointer accessor for direct copying. More...
 
const float * ptr () const
 Pointer accessor for direct copying. More...
 
void swap (Quaternion &other)
 Exchange the contents of this quaternion with another. More...
 
void ToAngleAxis (Degree &dAngle, Vector3 &rkAxis) const
 
void ToAngleAxis (Radian &rfAngle, Vector3 &rkAxis) const
 
void ToAxes (Vector3 &xAxis, Vector3 &yAxis, Vector3 &zAxis) const
 
void ToAxes (Vector3 *akAxis) const
 Gets the 3 orthonormal axes defining the quaternion. More...
 
void ToRotationMatrix (Matrix3 &kRot) const
 
Quaternion UnitInverse () const
 Apply to non-zero quaternion. More...
 
Vector3 xAxis (void) const
 Returns the X orthonormal axis defining the quaternion. More...
 
Vector3 yAxis (void) const
 Returns the Y orthonormal axis defining the quaternion. More...
 
Vector3 zAxis (void) const
 Returns the Z orthonormal axis defining the quaternion. More...
 

Static Public Member Functions

static void Intermediate (const Quaternion &rkQ0, const Quaternion &rkQ1, const Quaternion &rkQ2, Quaternion &rka, Quaternion &rkB)
 Setup for spherical quadratic interpolation. More...
 
static Quaternion nlerp (Real fT, const Quaternion &rkP, const Quaternion &rkQ, bool shortestPath=false)
 Performs Normalised linear interpolation between two quaternions, and returns the result. More...
 
static Quaternion Slerp (Real fT, const Quaternion &rkP, const Quaternion &rkQ, bool shortestPath=false)
 Performs Spherical linear interpolation between two quaternions, and returns the result. More...
 
static Quaternion SlerpExtraSpins (Real fT, const Quaternion &rkP, const Quaternion &rkQ, int iExtraSpins)
 
static Quaternion Squad (Real fT, const Quaternion &rkP, const Quaternion &rkA, const Quaternion &rkB, const Quaternion &rkQ, bool shortestPath=false)
 Spherical quadratic interpolation. More...
 

Public Attributes

float w
 
float x
 
float y
 
float z
 

Static Public Attributes

static const Quaternion IDENTITY
 
static const float msEpsilon
 Cutoff for sine near zero. More...
 
static const Quaternion ZERO
 

Detailed Description

Constructor & Destructor Documentation

◆ Quaternion() [1/8]

Ogre::Quaternion::Quaternion ( )
inline

Default constructor, initializes to identity rotation (aka 0°)

◆ Quaternion() [2/8]

Ogre::Quaternion::Quaternion ( const Ogre::Quaternion rhs)
inline

Copy constructor.

◆ Quaternion() [3/8]

Ogre::Quaternion::Quaternion ( float  fW,
float  fX,
float  fY,
float  fZ 
)
inline

Construct from an explicit list of values.

◆ Quaternion() [4/8]

Ogre::Quaternion::Quaternion ( const Matrix3 rot)
inline

Construct a quaternion from a rotation matrix.

◆ Quaternion() [5/8]

Ogre::Quaternion::Quaternion ( const Radian rfAngle,
const Vector3 rkAxis 
)
inline

Construct a quaternion from an angle/axis.

◆ Quaternion() [6/8]

Ogre::Quaternion::Quaternion ( const Vector3 xaxis,
const Vector3 yaxis,
const Vector3 zaxis 
)
inline

Construct a quaternion from 3 orthonormal local axes.

◆ Quaternion() [7/8]

Ogre::Quaternion::Quaternion ( const Vector3 akAxis)
inline

Construct a quaternion from 3 orthonormal local axes.

◆ Quaternion() [8/8]

Ogre::Quaternion::Quaternion ( float *  valptr)
inline

Construct a quaternion from 4 manual w/x/y/z values.

Member Function Documentation

◆ swap()

void Ogre::Quaternion::swap ( Quaternion other)
inline

Exchange the contents of this quaternion with another.

References std::swap(), w, x, y, and z.

◆ operator[]() [1/2]

float Ogre::Quaternion::operator[] ( const size_t  i) const
inline

Array accessor operator.

◆ operator[]() [2/2]

float& Ogre::Quaternion::operator[] ( const size_t  i)
inline

Array accessor operator.

◆ ptr() [1/2]

float* Ogre::Quaternion::ptr ( )
inline

Pointer accessor for direct copying.

◆ ptr() [2/2]

const float* Ogre::Quaternion::ptr ( ) const
inline

Pointer accessor for direct copying.

◆ FromRotationMatrix()

void Ogre::Quaternion::FromRotationMatrix ( const Matrix3 kRot)

◆ ToRotationMatrix()

void Ogre::Quaternion::ToRotationMatrix ( Matrix3 kRot) const

Referenced by Ogre::Matrix4::Matrix4().

◆ FromAngleAxis()

void Ogre::Quaternion::FromAngleAxis ( const Radian rfAngle,
const Vector3 rkAxis 
)

Setups the quaternion using the supplied vector, and "roll" around that vector by the specified radians.

Referenced by Ogre::VectorBase< 3, Real >::randomDeviant().

◆ ToAngleAxis() [1/2]

void Ogre::Quaternion::ToAngleAxis ( Radian rfAngle,
Vector3 rkAxis 
) const

◆ ToAngleAxis() [2/2]

void Ogre::Quaternion::ToAngleAxis ( Degree dAngle,
Vector3 rkAxis 
) const
inline

◆ FromAxes() [1/2]

void Ogre::Quaternion::FromAxes ( const Vector3 akAxis)

Constructs the quaternion using 3 axes, the axes are assumed to be orthonormal.

See also
FromAxes

◆ FromAxes() [2/2]

void Ogre::Quaternion::FromAxes ( const Vector3 xAxis,
const Vector3 yAxis,
const Vector3 zAxis 
)

◆ ToAxes() [1/2]

void Ogre::Quaternion::ToAxes ( Vector3 akAxis) const

Gets the 3 orthonormal axes defining the quaternion.

See also
FromAxes

◆ ToAxes() [2/2]

void Ogre::Quaternion::ToAxes ( Vector3 xAxis,
Vector3 yAxis,
Vector3 zAxis 
) const

◆ xAxis()

Vector3 Ogre::Quaternion::xAxis ( void  ) const

Returns the X orthonormal axis defining the quaternion.

Same as doing xAxis = Vector3::UNIT_X * this. Also called the local X-axis

◆ yAxis()

Vector3 Ogre::Quaternion::yAxis ( void  ) const

Returns the Y orthonormal axis defining the quaternion.

Same as doing yAxis = Vector3::UNIT_Y * this. Also called the local Y-axis

◆ zAxis()

Vector3 Ogre::Quaternion::zAxis ( void  ) const

Returns the Z orthonormal axis defining the quaternion.

Same as doing zAxis = Vector3::UNIT_Z * this. Also called the local Z-axis

◆ operator=()

Quaternion& Ogre::Quaternion::operator= ( const Quaternion rkQ)
inline

References w, x, y, and z.

◆ operator+()

Quaternion Ogre::Quaternion::operator+ ( const Quaternion rkQ) const

◆ operator-() [1/2]

Quaternion Ogre::Quaternion::operator- ( const Quaternion rkQ) const

◆ operator*() [1/3]

Quaternion Ogre::Quaternion::operator* ( const Quaternion rkQ) const

◆ operator*() [2/3]

Quaternion Ogre::Quaternion::operator* ( float  s) const
inline

◆ operator-() [2/2]

Quaternion Ogre::Quaternion::operator- ( ) const
inline

◆ operator==()

bool Ogre::Quaternion::operator== ( const Quaternion rhs) const
inline

References w, x, y, and z.

◆ operator!=()

bool Ogre::Quaternion::operator!= ( const Quaternion rhs) const
inline

References Ogre::operator==().

◆ Dot()

float Ogre::Quaternion::Dot ( const Quaternion rkQ) const
inline

Returns the dot product of the quaternion.

References w, x, y, and z.

◆ Norm()

float Ogre::Quaternion::Norm ( ) const
inline

Returns the normal length of this quaternion.

◆ normalise()

float Ogre::Quaternion::normalise ( void  )
inline

Normalises this quaternion, and returns the previous length.

Referenced by Ogre::VectorBase< 3, Real >::getRotationTo().

◆ Inverse()

Quaternion Ogre::Quaternion::Inverse ( ) const

◆ UnitInverse()

Quaternion Ogre::Quaternion::UnitInverse ( ) const

Apply to non-zero quaternion.

◆ Exp()

Quaternion Ogre::Quaternion::Exp ( ) const

Apply to unit-length quaternion.

◆ Log()

Quaternion Ogre::Quaternion::Log ( ) const

◆ operator*() [3/3]

Vector3 Ogre::Quaternion::operator* ( const Vector3 rkVector) const

Rotation of a vector by a quaternion.

◆ getRoll()

Radian Ogre::Quaternion::getRoll ( bool  reprojectAxis = true) const

Calculate the local roll element of this quaternion.

Parameters
reprojectAxisBy default the method returns the 'intuitive' result that is, if you projected the local X of the quaternion onto the XY plane, the angle between it and global X is returned. The co-domain of the returned value is from -180 to 180 degrees. If set to false though, the result is the rotation around Z axis that could be used to implement the quaternion using some non-intuitive order of rotations. This behavior is preserved for backward compatibility, to decompose quaternion into yaw, pitch and roll use q.ToRotationMatrix().ToEulerAnglesYXZ(yaw, pitch, roll) instead.

◆ getPitch()

Radian Ogre::Quaternion::getPitch ( bool  reprojectAxis = true) const

Calculate the local pitch element of this quaternion.

Parameters
reprojectAxisBy default the method returns the 'intuitive' result that is, if you projected the local Y of the quaternion onto the YZ plane, the angle between it and global Y is returned. The co-domain of the returned value is from -180 to 180 degrees. If set to false though, the result is the rotation around X axis that could be used to implement the quaternion using some non-intuitive order of rotations. This behavior is preserved for backward compatibility, to decompose quaternion into yaw, pitch and roll use q.ToRotationMatrix().ToEulerAnglesYXZ(yaw, pitch, roll) instead.

◆ getYaw()

Radian Ogre::Quaternion::getYaw ( bool  reprojectAxis = true) const

Calculate the local yaw element of this quaternion.

Parameters
reprojectAxisBy default the method returns the 'intuitive' result that is, if you projected the local Z of the quaternion onto the ZX plane, the angle between it and global Z is returned. The co-domain of the returned value is from -180 to 180 degrees. If set to false though, the result is the rotation around Y axis that could be used to implement the quaternion using some non-intuitive order of rotations. This behavior is preserved for backward compatibility, to decompose quaternion into yaw, pitch and roll use q.ToRotationMatrix().ToEulerAnglesYXZ(yaw, pitch, roll) instead.

◆ equals()

bool Ogre::Quaternion::equals ( const Quaternion rhs,
const Radian tolerance 
) const
inline

Equality with tolerance (tolerance is max angle difference)

Remarks
Both equals() and orientationEquals() measure the exact same thing. One measures the difference by angle, the other by a different, non-linear metric.

References Ogre::Math::Abs(), Ogre::Math::ACos(), and Ogre::Radian::valueRadians().

◆ orientationEquals()

bool Ogre::Quaternion::orientationEquals ( const Quaternion other,
float  tolerance = 1e-3f 
) const
inline

Compare two quaternions which are assumed to be used as orientations.

Remarks
Both equals() and orientationEquals() measure the exact same thing. One measures the difference by angle, the other by a different, non-linear metric.
Returns
true if the two orientations are the same or very close, relative to the given tolerance. Slerp ( 0.75f, A, B ) != Slerp ( 0.25f, B, A ); therefore be careful if your code relies in the order of the operands. This is specially important in IK animation.

◆ Slerp()

static Quaternion Ogre::Quaternion::Slerp ( Real  fT,
const Quaternion rkP,
const Quaternion rkQ,
bool  shortestPath = false 
)
static

Performs Spherical linear interpolation between two quaternions, and returns the result.

Slerp ( 0.0f, A, B ) = A Slerp ( 1.0f, A, B ) = B

Returns
Interpolated quaternion
Remarks
Slerp has the proprieties of performing the interpolation at constant velocity, and being torque-minimal (unless shortestPath=false). However, it's NOT commutative, which means Slerp ( 0.75f, A, B ) != Slerp ( 0.25f, B, A ); therefore be careful if your code relies in the order of the operands. This is specially important in IK animation.

◆ SlerpExtraSpins()

static Quaternion Ogre::Quaternion::SlerpExtraSpins ( Real  fT,
const Quaternion rkP,
const Quaternion rkQ,
int  iExtraSpins 
)
static
See also
Slerp. It adds extra "spins" (i.e. rotates several times) specified by parameter 'iExtraSpins' while interpolating before arriving to the final values

◆ Intermediate()

static void Ogre::Quaternion::Intermediate ( const Quaternion rkQ0,
const Quaternion rkQ1,
const Quaternion rkQ2,
Quaternion rka,
Quaternion rkB 
)
static

Setup for spherical quadratic interpolation.

◆ Squad()

static Quaternion Ogre::Quaternion::Squad ( Real  fT,
const Quaternion rkP,
const Quaternion rkA,
const Quaternion rkB,
const Quaternion rkQ,
bool  shortestPath = false 
)
static

Spherical quadratic interpolation.

◆ nlerp()

static Quaternion Ogre::Quaternion::nlerp ( Real  fT,
const Quaternion rkP,
const Quaternion rkQ,
bool  shortestPath = false 
)
static

Performs Normalised linear interpolation between two quaternions, and returns the result.

nlerp ( 0.0f, A, B ) = A nlerp ( 1.0f, A, B ) = B

Remarks
Nlerp is faster than Slerp. Nlerp has the proprieties of being commutative (
See also
Slerp; commutativity is desired in certain places, like IK animation), and being torque-minimal (unless shortestPath=false). However, it's performing the interpolation at non-constant velocity; sometimes this is desired, sometimes it is not. Having a non-constant velocity can produce a more natural rotation feeling without the need of tweaking the weights; however if your scene relies on the timing of the rotation or assumes it will point at a specific angle at a specific weight value, Slerp is a better choice.

◆ isNaN()

bool Ogre::Quaternion::isNaN ( ) const
inline

Check whether this quaternion contains valid values.

References Ogre::Math::isNaN().

Member Data Documentation

◆ msEpsilon

const float Ogre::Quaternion::msEpsilon
static

Cutoff for sine near zero.

◆ ZERO

const Quaternion Ogre::Quaternion::ZERO
static

◆ IDENTITY

const Quaternion Ogre::Quaternion::IDENTITY
static

◆ w

float Ogre::Quaternion::w

Referenced by Dot(), operator=(), operator==(), and swap().

◆ x

float Ogre::Quaternion::x

Referenced by Dot(), operator=(), operator==(), and swap().

◆ y

float Ogre::Quaternion::y

Referenced by Dot(), operator=(), operator==(), and swap().

◆ z

float Ogre::Quaternion::z

Referenced by Dot(), operator=(), operator==(), and swap().


The documentation for this class was generated from the following file: