ezEngine  Milestone 7
ezQuatTemplate< Type > Class Template Reference

Quaternions can be used to represent rotations in 3D space. More...

#include <Quat.h>

Public Types

typedef Type ComponentType
 

Public Member Functions

 EZ_DECLARE_POD_TYPE ()
 
 ezQuatTemplate (Type X, Type Y, Type Z, Type W)
 For internal use. You should never construct quaternions this way.
 
void SetIdentity ()
 Sets the Quaternion to the identity.
 
void SetElements (Type X, Type Y, Type Z, Type W)
 Sets the individual elements of the quaternion directly. Note that x,y,z do NOT represent a rotation axis, and w does NOT represent an angle. More...
 
void SetFromAxisAndAngle (const ezVec3Template< Type > &vRotationAxis, ezAngle angle)
 Creates a quaternion from a rotation-axis and an angle.
 
void SetShortestRotation (const ezVec3Template< Type > &vDirFrom, const ezVec3Template< Type > &vDirTo)
 Creates a quaternion, that rotates through the shortest arc from "vDirFrom" to "vDirTo". More...
 
void SetFromMat3 (const ezMat3Template< Type > &m)
 Creates a quaternion from the given matrix.
 
void SetSlerp (const ezQuatTemplate &qFrom, const ezQuatTemplate &qTo, Type t)
 Sets this quaternion to be the spherical linear interpolation of the other two.
 
void Normalize ()
 Normalizes the quaternion to unit length. ALL rotation-quaternions should be normalized at all times (automatically).
 
ezResult GetRotationAxisAndAngle (ezVec3Template< Type > &vAxis, ezAngle &angle) const
 Returns the rotation-axis and angle, that this quaternion rotates around.
 
const ezMat3Template< Type > GetAsMat3 () const
 Returns the Quaternion as a matrix.
 
const ezMat4Template< Type > GetAsMat4 () const
 Returns the Quaternion as a matrix.
 
bool IsValid (Type fEpsilon=ezMath::BasicType< Type >::DefaultEpsilon()) const
 Checks whether all components are neither NaN nor infinite and that the quaternion is normalized.
 
bool IsNaN () const
 Checks whether any component is NaN.
 
bool IsEqualRotation (const ezQuatTemplate &qOther, float fEpsilon) const
 Determines whether this and qOther represent the same rotation. This is a rather slow operation. More...
 
const ezQuatTemplate operator- () const
 Returns a Quaternion that represents the negative / inverted rotation.
 
void GetAsEulerAngles (ezAngle &out_Yaw, ezAngle &out_Pitch, ezAngle &out_Roll) const
 Converts the quaternion to Euler angles. More...
 
void SetFromEulerAngles (const ezAngle &Yaw, const ezAngle &Pitch, const ezAngle &Roll)
 Sets the quaternion from Euler angles. More...
 

Static Public Member Functions

static const ezQuatTemplate< Type > IdentityQuaternion ()
 Static function that returns a quaternion that represents the identity rotation (none).
 

Public Attributes

ezVec3Template< Type > v
 
Type w
 

Detailed Description

template<typename Type>
class ezQuatTemplate< Type >

Quaternions can be used to represent rotations in 3D space.

Quaternions are useful to represent 3D rotations, as they are smaller and more efficient than matrices and can be concatenated easily, without having the 'Gimbal Lock' problem of Euler Angles. Either use a full blown transformation (e.g. a 4x4 matrix) to represent a object, or use a Quaternion bundled with a position vector, if (non-uniform) scale is not required. Quaternions can also easily be interpolated (via Slerp). This implementation also allows to convert back and forth between Quaternions and Matrices easily.

Quaternions have no 'IsIdentical' or 'IsEqual' function, as there can be different representations for the same rotation, and it is rather difficult to check this. So to not convey any false notion of being equal (or rather unequal), those functions are not provided.

Member Function Documentation

template<typename Type >
void ezQuatTemplate< Type >::GetAsEulerAngles ( ezAngle out_Yaw,
ezAngle out_Pitch,
ezAngle out_Roll 
) const

Converts the quaternion to Euler angles.

Test:
This is new
template<typename Type >
bool ezQuatTemplate< Type >::IsEqualRotation ( const ezQuatTemplate< Type > &  qOther,
float  fEpsilon 
) const

Determines whether this and qOther represent the same rotation. This is a rather slow operation.

Currently it fails when one of the given quaternions is identity (so no rotation, at all), as it tries to compare rotation axis' and angles, which is undefined for the identity quaternion (also there are infinite representations for 'identity', so it's difficult to check for it).

template<typename Type>
EZ_FORCE_INLINE void ezQuatTemplate< Type >::SetElements ( Type  X,
Type  Y,
Type  Z,
Type  W 
)

Sets the individual elements of the quaternion directly. Note that x,y,z do NOT represent a rotation axis, and w does NOT represent an angle.

Use this function only if you have good understanding of quaternion math and know exactly what you are doing.

template<typename Type >
void ezQuatTemplate< Type >::SetFromEulerAngles ( const ezAngle Yaw,
const ezAngle Pitch,
const ezAngle Roll 
)

Sets the quaternion from Euler angles.

Test:
This is new
template<typename Type>
void ezQuatTemplate< Type >::SetShortestRotation ( const ezVec3Template< Type > &  vDirFrom,
const ezVec3Template< Type > &  vDirTo 
)

Creates a quaternion, that rotates through the shortest arc from "vDirFrom" to "vDirTo".

Note
This function will ALWAYS return a quaternion that rotates from one direction to another. If both directions are identical, it is the unit rotation (none). If they are exactly opposing, this will be ANY 180.0 degree rotation. That means the vectors will align perfectly, but there is no determine rotation for other points that might be rotated with this quaternion. If a main / fallback axis is needed to rotate points, you need to calculate such a rotation with other means.

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