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

#include <OgreQuaternion.h>

Public Member Functions
	Quaternion ()
	Default constructor, initializes to identity rotation (aka 0°) More...

	Quaternion (Real fW, Real fX, Real fY, Real fZ)
	Construct from an explicit list of values. More...

	Quaternion (const Matrix3 &rot)
	Construct a quaternion from a rotation matrix. 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 (Real *valptr)
	Construct a quaternion from 4 manual w/x/y/z values. More...

Real	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 *akAxis)
	Constructs the quaternion using 3 axes, the axes are assumed to be orthonormal. More...

void	FromAxes (const Vector3 &xAxis, const Vector3 &yAxis, const Vector3 &zAxis)

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

Real	Norm () const
	Returns the normal length of this quaternion. More...

Real	normalise (void)
	Normalises this quaternion, and returns the previous length. More...

bool	operator!= (const Quaternion &rhs) const

Quaternion	operator* (const Quaternion &rkQ) const

Quaternion	operator* (Real fScalar) const

Vector3	operator* (const Vector3 &rkVector) const
	Rotation of a vector by a quaternion. More...

Quaternion	operator+ (const Quaternion &rkQ) const

Quaternion	operator- (const Quaternion &rkQ) const

Quaternion	operator- () const

Quaternion &	operator= (const Quaternion &rkQ)

bool	operator== (const Quaternion &rhs) const

Real	operator[] (const size_t i) const
	Array accessor operator. More...

Real &	operator[] (const size_t i)
	Array accessor operator. More...

bool	orientationEquals (const Quaternion &other, Real tolerance=1e-3) const
	Compare two quaternions which are assumed to be used as orientations. More...

Real *	ptr ()
	Pointer accessor for direct copying. More...

const Real *	ptr () const
	Pointer accessor for direct copying. More...

void	swap (Quaternion &other)
	Exchange the contents of this quaternion with another. More...

void	ToAngleAxis (Radian &rfAngle, Vector3 &rkAxis) const

void	ToAngleAxis (Degree &dAngle, Vector3 &rkAxis) const

void	ToAxes (Vector3 *akAxis) const
	Gets the 3 orthonormal axes defining the quaternion. More...

void	ToAxes (Vector3 &xAxis, Vector3 &yAxis, Vector3 &zAxis) const

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
Real	w

Real	x

Real	y

Real	z

Static Public Attributes
static const Quaternion	IDENTITY

static const Real	msEpsilon
	Cutoff for sine near zero. More...

static const Quaternion	ZERO

Friends
_OgreExport friend Quaternion	operator* (Real fScalar, const Quaternion &rkQ)

_OgreExport friend std::ostream &	operator<< (std::ostream &o, const Quaternion &q)
	Function for writing to a stream. More...

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°)

◆ Quaternion() [2/7]

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

inline

Construct from an explicit list of values.

◆ Quaternion() [3/7]

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

inline

Construct a quaternion from a rotation matrix.

◆ Quaternion() [4/7]

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

inline

Construct a quaternion from an angle/axis.

◆ Quaternion() [5/7]

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

inline

Construct a quaternion from 3 orthonormal local axes.

◆ Quaternion() [6/7]

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

inline

Construct a quaternion from 3 orthonormal local axes.

◆ Quaternion() [7/7]

Ogre::Quaternion::Quaternion ( Real * 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]

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

inline

Array accessor operator.

◆ operator[]() [2/2]

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

inline

Array accessor operator.

◆ ptr() [1/2]

Real* Ogre::Quaternion::ptr ( )

inline

Pointer accessor for direct copying.

◆ ptr() [2/2]

const Real* 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::Vector3::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 Ogre::operator*(), 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* ( Real fScalar ) const

◆ operator-() [2/2]

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

◆ 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*(), and Ogre::operator==().

◆ Dot()

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

Returns the dot product of the quaternion.

◆ Norm()

Real Ogre::Quaternion::Norm ( ) const

Returns the normal length of this quaternion.

◆ normalise()

Real Ogre::Quaternion::normalise ( void )

Normalises this quaternion, and returns the previous length.

Referenced by Ogre::Vector3::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

reprojectAxis By 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

reprojectAxis By 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

reprojectAxis By 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

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.

◆ orientationEquals()

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

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

Friends And Related Function Documentation

◆ operator*

_OgreExport friend Quaternion operator*	(	Real	fScalar,
		const Quaternion &	rkQ
	)

friend

◆ operator<<

_OgreExport friend std::ostream& operator<<	(	std::ostream &	o,
		const Quaternion &	q
	)

friend

Function for writing to a stream.

Outputs "Quaternion(w, x, y, z)" with w,x,y,z being the member values of the quaternion.

Member Data Documentation

◆ msEpsilon

const Real Ogre::Quaternion::msEpsilon

static

Cutoff for sine near zero.

◆ ZERO

const Quaternion Ogre::Quaternion::ZERO

static

◆ IDENTITY

const Quaternion Ogre::Quaternion::IDENTITY

static

Referenced by Ogre::Entity::getCurrentLodIndex(), Ogre::Node::getInheritScale(), Ogre::StaticGeometry::getName(), Ogre::InstancedGeometry::getName(), Ogre::SceneNode::getShowBoundingBox(), Ogre::SceneManager::getSkyBoxGenParameters(), Ogre::SceneManager::getSkyPlaneGenParameters(), and Ogre::StringConverter::parseAngle().

◆ w

Real Ogre::Quaternion::w

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

◆ x

Real Ogre::Quaternion::x

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

◆ y

Real Ogre::Quaternion::y

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

◆ z

Real Ogre::Quaternion::z

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

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

OgreQuaternion.h

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Quaternion() [1/7]

◆ Quaternion() [2/7]

◆ Quaternion() [3/7]

◆ Quaternion() [4/7]

◆ Quaternion() [5/7]

◆ Quaternion() [6/7]

◆ Quaternion() [7/7]

Member Function Documentation

◆ swap()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ ptr() [1/2]

◆ ptr() [2/2]

◆ FromRotationMatrix()

◆ ToRotationMatrix()

◆ FromAngleAxis()

◆ ToAngleAxis() [1/2]

◆ ToAngleAxis() [2/2]

◆ FromAxes() [1/2]

◆ FromAxes() [2/2]

◆ ToAxes() [1/2]

◆ ToAxes() [2/2]

◆ xAxis()

◆ yAxis()

◆ zAxis()

◆ operator=()

◆ operator+()

◆ operator-() [1/2]

◆ operator*() [1/3]

◆ operator*() [2/3]

◆ operator-() [2/2]

◆ operator==()

◆ operator!=()

◆ Dot()

◆ Norm()

◆ normalise()

◆ Inverse()

◆ UnitInverse()

◆ Exp()

◆ Log()

◆ operator*() [3/3]

◆ getRoll()

◆ getPitch()

◆ getYaw()

◆ equals()

◆ orientationEquals()

◆ Slerp()

◆ SlerpExtraSpins()

◆ Intermediate()

◆ Squad()

◆ nlerp()

◆ isNaN()

Friends And Related Function Documentation

◆ operator*

◆ operator<<

Member Data Documentation

◆ msEpsilon

◆ ZERO

◆ IDENTITY

◆ w

◆ x

◆ y

◆ z