OGRE-Next: Ogre::Quaternion Class Reference

| OGRE-Next 3.0.0 Object-Oriented Graphics Rendering Engine

Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | Public Attributes | Static Public Attributes | List of all members
Ogre::Quaternion Class Reference
Core » Math

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

`#include <OgreQuaternion.h>`

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

## 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.
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.
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.
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.

## Public Attributes
Real | w
Real | x
Real | y
Real | z

## Static Public Attributes
static const Quaternion | IDENTITY
static const Real | msEpsilon
| Cutoff for sine near zero.
static const Quaternion | ZERO

## Detailed Description

Implementation of a Quaternion, i.e.

a rotation around an axis. For more information about Quaternions and the theory behind it, we recommend reading: http://www.ogre3d.org/tikiwiki/Quaternion+and+Rotation+Primer and http://www.cprogramming.com/tutorial/3d/quaternions.html and http://www.gamedev.net/page/resources/_/reference/programming/math-and-physics/quaternions/quaternion-powers-r1095

## Constructor & Destructor Documentation

## ◆ Quaternion() [1/7]

Ogre::Quaternion::Quaternion | ( |  | ) |
| inline

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

References w, x, y, and z.

Referenced by Dot(), equals(), Exp(), Intermediate(), Inverse(), Log(), nlerp(), operator!=(), operator*(), operator*(), operator*, operator+(), operator-(), operator-(), operator<<, operator==(), orientationEquals(), Slerp(), SlerpExtraSpins(), Squad(), swap(), and UnitInverse().

## ◆ Quaternion() [2/7]

Ogre::Quaternion::Quaternion | ( | Real | fW,
|  | Real | fX,
|  | Real | fY,
|  | Real | fZ )
| inline

Construct from an explicit list of values.

References w, x, y, and z.

## ◆ Quaternion() [3/7]

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

Construct a quaternion from a rotation matrix.

References FromRotationMatrix().

## ◆ Quaternion() [4/7]

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

Construct a quaternion from an angle/axis.

References FromAngleAxis().

## ◆ Quaternion() [5/7]

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

Construct a quaternion from 3 orthonormal local axes.

References FromAxes().

## ◆ Quaternion() [6/7]

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

Construct a quaternion from 3 orthonormal local axes.

References FromAxes().

## ◆ Quaternion() [7/7]

Ogre::Quaternion::Quaternion | ( | Real * | valptr | ) |
| inline

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

References w.

## Member Function Documentation

## ◆ Dot()

Real Ogre::Quaternion::Dot | ( | const Quaternion & | rkQ | ) | const

Returns the dot product of the quaternion.

References Quaternion().

Referenced by orientationEquals().

## ◆ equals()

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

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 Quaternion().

## ◆ Exp()

Quaternion Ogre::Quaternion::Exp | ( |  | ) | const

References Quaternion().

## ◆ 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 Quaternion(), Ogre::Vector3::getRotationTo(), and Ogre::Vector3::randomDeviant().

## ◆ FromAxes() [1/2]

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

References xAxis(), yAxis(), and zAxis().

## ◆ FromAxes() [2/2]

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

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

See also
  FromAxes

Referenced by Quaternion(), and Quaternion().

## ◆ FromRotationMatrix()

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

Referenced by Quaternion().

## ◆ getPitch()

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

Calculate the local pitch element of this quaternion.

Parameters

  reprojectAxis | By default the method returns the 'intuitive' result that is, if you projected the local Z of the quaternion onto the X and Y axes, the angle between them is returned. If set to true though, the result is the actual yaw that will be used to implement the quaternion, which is the shortest possible path to get to the same orientation and may involve less axial rotation. The co-domain of the returned value is from -180 to 180 degrees.

## ◆ getRoll()

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

Calculate the local roll element of this quaternion.

Parameters

  reprojectAxis | By default the method returns the 'intuitive' result that is, if you projected the local Y of the quaternion onto the X and Y axes, the angle between them is returned. If set to false though, the result is the actual yaw that will be used to implement the quaternion, which is the shortest possible path to get to the same orientation and may involve less axial rotation. The co-domain of the returned value is from -180 to 180 degrees.

## ◆ getYaw()

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

Calculate the local yaw element of this quaternion.

Parameters

  reprojectAxis | By default the method returns the 'intuitive' result that is, if you projected the local Y of the quaternion onto the X and Z axes, the angle between them is returned. If set to true though, the result is the actual yaw that will be used to implement the quaternion, which is the shortest possible path to get to the same orientation and may involve less axial rotation. The co-domain of the returned value is from -180 to 180 degrees.

## ◆ 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.

References Quaternion().

## ◆ Inverse()

Quaternion Ogre::Quaternion::Inverse | ( |  | ) | const

Apply to non-zero quaternion.

References Quaternion().

## ◆ isNaN()

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

Check whether this quaternion contains valid values.

References Ogre::Math::isNaN(), w, x, y, and z.

## ◆ Log()

Quaternion Ogre::Quaternion::Log | ( |  | ) | const

References Quaternion().

## ◆ 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.

References Quaternion().

## ◆ Norm()

Real Ogre::Quaternion::Norm | ( |  | ) | const

## ◆ normalise()

Real Ogre::Quaternion::normalise | ( |  | ) |

Normalises this quaternion, and returns the previous length.

Referenced by Ogre::Vector3::getRotationTo().

## ◆ operator!=()

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

References Quaternion(), and operator==().

## ◆ operator*() [1/3]

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

References Quaternion().

## ◆ operator*() [2/3]

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

Rotation of a vector by a quaternion.

## ◆ operator*() [3/3]

Quaternion Ogre::Quaternion::operator* | ( | Real | fScalar | ) | const

References Quaternion().

## ◆ operator+()

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

References Quaternion().

## ◆ operator-() [1/2]

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

References Quaternion().

## ◆ operator-() [2/2]

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

References Quaternion().

## ◆ operator==()

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

References Quaternion(), w, x, y, and z.

Referenced by operator!=().

## ◆ operator[]() [1/2]

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

Array accessor operator.

References w.

## ◆ operator[]() [2/2]

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

Array accessor operator.

References w.

## ◆ orientationEquals()

bool Ogre::Quaternion::orientationEquals | ( | const Quaternion & | other,
|  | Real | tolerance = Real( 1e-3 ) ) 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.

References Quaternion(), and Dot().

## ◆ ptr() [1/2]

Real * Ogre::Quaternion::ptr | ( |  | ) |
| inline

Pointer accessor for direct copying.

References w.

## ◆ ptr() [2/2]

const Real * Ogre::Quaternion::ptr | ( |  | ) | const
| inline

Pointer accessor for direct copying.

References w.

## ◆ 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.

References Quaternion().

## ◆ 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

References Quaternion().

## ◆ 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.

References Quaternion().

## ◆ swap()

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

Exchange the contents of this quaternion with another.

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

## ◆ ToAngleAxis() [1/2]

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

References ToAngleAxis().

## ◆ ToAngleAxis() [2/2]

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

Referenced by ToAngleAxis().

## ◆ ToAxes() [1/2]

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

References xAxis(), yAxis(), and zAxis().

## ◆ ToAxes() [2/2]

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

Gets the 3 orthonormal axes defining the quaternion.

See also
  FromAxes

## ◆ ToRotationMatrix()

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

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

## ◆ UnitInverse()

Quaternion Ogre::Quaternion::UnitInverse | ( |  | ) | const

Apply to unit-length quaternion.

References Quaternion().

## ◆ xAxis()

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

Returns the X orthonormal axis defining the quaternion.

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

Referenced by FromAxes(), Ogre::VertexBufferDownloadHelper::getNormal(), and ToAxes().

## ◆ yAxis()

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

Returns the Y orthonormal axis defining the quaternion.

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

Referenced by FromAxes(), and ToAxes().

## ◆ zAxis()

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

Returns the Z orthonormal axis defining the quaternion.

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

Referenced by FromAxes(), and ToAxes().

## Member Data Documentation

## ◆ IDENTITY

const Quaternion Ogre::Quaternion::IDENTITY
| static

Referenced by Ogre::Node::createChild(), Ogre::v1::OldBone::createChild(), Ogre::v1::OldNode::createChild(), Ogre::v1::OldNode::createChild(), Ogre::SceneNode::createChildSceneNode(), Ogre::TagPoint::createChildTagPoint(), Ogre::v1::MeshManager::createCurvedIllusionPlane(), Ogre::v1::OldSkeletonInstance::createTagPointOnBone(), Ogre::Vector3::getRotationTo(), and Ogre::StringConverter::parseQuaternion().

## ◆ msEpsilon

const Real Ogre::Quaternion::msEpsilon
| static

Cutoff for sine near zero.

## ◆ w

Real Ogre::Quaternion::w

Referenced by Quaternion(), Quaternion(), Quaternion(), Ogre::ArrayQuaternion::getAsQuaternion(), Ogre::VertexBufferDownloadHelper::getNormal(), Ogre::Vector3::getRotationTo(), isNaN(), operator==(), operator[](), operator[](), ptr(), ptr(), Ogre::ArrayQuaternion::setAll(), Ogre::ArrayQuaternion::setFromQuaternion(), and swap().

## ◆ x

Real Ogre::Quaternion::x

Referenced by Quaternion(), Quaternion(), Ogre::ArrayQuaternion::getAsQuaternion(), Ogre::VertexBufferDownloadHelper::getNormal(), Ogre::Vector3::getRotationTo(), isNaN(), operator==(), Ogre::ArrayQuaternion::setAll(), Ogre::ArrayQuaternion::setFromQuaternion(), and swap().

## ◆ y

Real Ogre::Quaternion::y

Referenced by Quaternion(), Quaternion(), Ogre::ArrayQuaternion::getAsQuaternion(), Ogre::VertexBufferDownloadHelper::getNormal(), Ogre::Vector3::getRotationTo(), isNaN(), operator==(), Ogre::ArrayQuaternion::setAll(), Ogre::ArrayQuaternion::setFromQuaternion(), and swap().

## ◆ z

Real Ogre::Quaternion::z

Referenced by Quaternion(), Quaternion(), Ogre::ArrayQuaternion::getAsQuaternion(), Ogre::VertexBufferDownloadHelper::getNormal(), Ogre::Vector3::getRotationTo(), isNaN(), operator==(), Ogre::ArrayQuaternion::setAll(), Ogre::ArrayQuaternion::setFromQuaternion(), and swap().

## ◆ ZERO

const Quaternion Ogre::Quaternion::ZERO
| static

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

- OgreQuaternion.h