Unigine::Math::quat Struct
Header: | #include <UnigineMathLib.h> |
This class represents a quaternion type. Quaternions represent a rotation. Typically, they are used for smooth interpolation between two angles, and for avoiding the gimbal lock problem that can occur with euler angles.
Quaternions add a fourth element to the [ x, y, z] values that define a vector, resulting in arbitrary 4-D vectors. The following example illustrates how each element of a unit quaternion relates to an axis-angle rotation, where q represents a unit quaternion (x, y, z, w), axis is normalized, and theta is the desired counterclockwise (CCW) rotation around the axis:
- q.x = sin(theta/2) * axis.x
- q.y = sin(theta/2) * axis.y
- q.z = sin(theta/2) * axis.z
- q.w = cos(theta/2)
Usage Example#
The following example creates a quaternion for node rotation: 60 degrees per second along Z axis.
// AppWorldLogic.cpp file
int AppWorldLogic::update()
{
/* ... */
// get delta time value
float delta_time = Game::get()->getIFps();
// create quat for 60 degrees per second rotation along Z axis
Unigine::Math::quat rotation_delta = Unigine::Math::quat(0.0f, 0.0f, 1.0f, 60 * delta_time);
// rotate the node
node->setWorldRotation(node->getWorldRotation() * delta_rotation);
/* ... */
}
In the example above, the quaternion was initialized by using four values: 3 axis components (x,y,z) and angle (w component of the quaternion). 1 value of the Z axis component shows that the rotation will be performed along Z axis.
See Also#
- An article on Quaternions and Spatial Rotation on Wikipedia.
- A video tutorial on moving and rotating the node by using quaternion (C++)
quat Class
Members
quat( const __m128 & v )
Constructor. Initializes the quaternion using a given __m128 variable (128-bit).Arguments
- const __m128 & v - 128-bit variable.
quat( const mat3 & m )
Constructor. Initializes the quaternion using a given mat3 source matrix (3x3).Arguments
- const mat3 & m - Source matrix (3x3).
quat( const vec4 & v )
Constructor. Initializes the quaternion using a given four-component vec4 source vector.Arguments
- const vec4 & v - Four-component source vector.
quat( const vec3 & v )
Constructor. Initializes the quaternion using a given three-component vec3 source vector.Arguments
- const vec3 & v - Thee-component source vector.
quat( )
Default constructor. Produces an identity quaternion (0.0, 0.0, 0.0, 1.0).quat( const quat & q )
Constructor. Initializes the quaternion by copying a given source quaternion.Arguments
- const quat & q - Source quaternion.
quat( const vec3 & axis, float angle )
Constructor. Initializes the quaternion using given rotation axis and angle.Arguments
- const vec3 & axis - Rotation axis.
- float angle - Rotation angle, in degrees.
quat( float angle_x, float angle_y, float angle_z )
Constructor. Initializes the quaternion using given angles for each axis.Arguments
- float angle_x - Rotation angle along the X axis, in degrees.
- float angle_y - Rotation angle along the Y axis, in degrees.
- float angle_z - Rotation angle along the Z axis, in degrees.
quat( const vec3 & col0, const vec3 & col1, const vec3 & col2 )
Constructor. Initializes the quaternion using three given matrix columns represented by vec3 vectors.Arguments
- const vec3 & col0 - First matrix column.
- const vec3 & col1 - Second matrix column.
- const vec3 & col2 - Third matrix column.
quat( float x, float y, float z, float angle )
Constructor. Initializes the quaternion using given float values.Arguments
- float x - X component of the quaternion.
- float y - Y component of the quaternion.
- float z - Z component of the quaternion.
- float angle - W component of the quaternion.
explicit quat( const mat4 & m )
Constructor. Initializes the quaternion using a given mat4 source matrix (4x4).Arguments
- const mat4 & m - Source matrix (4x4).
explicit quat( const dmat4 & m )
Constructor. Initializes the quaternion using a given dmat4 source matrix (3x4).Arguments
- const dmat4 & m - Source matrix (3x4).
explicit quat( const float * q )
Constructor. Initializes the vector using a given pointer to the quaternion.Arguments
- const float * q - Pointer to the quaternion.
void set( float x, float y, float z, float angle )
Sets the quaternion by components.Arguments
- float x - X component of the quaternion.
- float y - Y component of the quaternion.
- float z - Z component of the quaternion.
- float angle - W component of the quaternion.
Examples
quat(1.0, 2.0, 3.0, 60);
/*
Creates a quaternion (1.0, 2.0, 3.0, 60)
*/
void set( const float * qq )
Sets the quaternion using a given pointer to the source quaternion.Arguments
- const float * qq - Pointer to the source quaternion.
void set( const mat3 & m )
Sets the quaternion using a given mat3 source matrix (3x3).Arguments
- const mat3 & m - Source matrix (3x3).
void set( const vec3 & col0, const vec3 & col1, const vec3 & col2 )
Sets the quaternion using three given matrix columns represented by vec3 vectors.Arguments
- const vec3 & col0 - First matrix column.
- const vec3 & col1 - Second matrix column.
- const vec3 & col2 - Third matrix column.
void set( float angle_x, float angle_y, float angle_z )
Sets the quaternion using given angles for each axis.Arguments
- float angle_x - Rotation angle along the X axis, in degrees.
- float angle_y - Rotation angle along the Y axis, in degrees.
- float angle_z - Rotation angle along the Z axis, in degrees.
void set( const vec3 & axis, float angle )
Sets the quaternion using given rotation axis and angle.Arguments
- const vec3 & axis - Rotation axis.
- float angle - Rotation angle, in degrees.
void set( const vec3 & v )
Sets the quaternion using a given three-component vec3 source vector.Arguments
- const vec3 & v - Three-component source vector.
void set( const dmat4 & m )
Sets the quaternion using a given dmat4 source matrix (3x4).Arguments
- const dmat4 & m - Source matrix (3x4).
void set( const mat4 & m )
Sets the quaternion using a given mat4 source matrix (4x4).Arguments
- const mat4 & m - Source matrix (4x4).
void get( float * qq ) const
Gets the quaternion: qq[0]=x, qq[1]=y, qq[2]=z, qq[3]=w.Arguments
- float * qq - Pointer to the quaternion.
float * get( )
Returns a pointer to the quaternion.Return value
Pointer to the quaternion.const float * get( ) const
Returns a constant pointer to the quaternion.Return value
Constant pointer to the quaternion.void get( vec3 & axis, float & angle )
Gets rotation axis and angle of the quaternion and puts the values to corresponding variables: axis.x = x, axis.y = y, axis.z = z, angle = w.Arguments
- vec3 & axis - Rotation axis.
- float & angle - Rotation angle, in degrees.
float getAngle( const vec3 & axis )
Returns the rotation angle of the quaternion for a given rotation axis.Arguments
- const vec3 & axis - Rotation axis.
Return value
Rotation angle, in degrees, within the [-180, 180] range.vec3 getBinormal( ) const
Returns the quaternion binormal vector with respect to orientation.Return value
Quaternion binormal vector.mat3 getMat3( )
Returns the rotation matrix for the quaternion.For the quaternion (x, y, z, w) the corresponding rotation matrix M is defined as follows:
| 1 - 2y² - 2z² 2xy + 2wz 2xz - 2wy |
M= | 2xy - 2wz 1 - 2x² - 2z² 2yz + 2wx |
| 2xz + 2wy 2yz - 2wx 1 - 2x² - 2y² |
vec3 getNormal( ) const
Returns the quaternion normal vector.Return value
Quaternion normal vector.vec3 getTangent( ) const
Returns the quaternion tangent vector.Return value
Quaternion tangent vector.vec4 getTangent4( ) const
Returns the quaternion tangent vector and binormal orientation as a four-component vec4 vector.Return value
Four-component vector representing guaternion tangent vector and binormal orientation.quat & normalize( )
Returns normalized quaternion.Return value
Normalized quaternion.quat & normalizeFast( )
Returns normalized quaternion, calculated using the fast inverse square root algorithm.Return value
Normalized quaternion.__m128 operator __m128( )
Performs type conversion to __m128.const float * operator const float *( )
Performs type conversion to float void *.const void * operator const void *( )
Performs type conversion to const void *.float * operator float *( )
Performs type conversion to float *.void * operator void *( )
Performs type conversion to void *.quat & operator*=( const quat & q )
Performs quaternion multiplication.Arguments
- const quat & q - Quaternion.
Return value
Resulting quaternion.quat & operator*=( float v )
Performs scalar multiplication.Arguments
- float v - Scalar value.
Return value
Resulting quaternion.quat & operator+=( const quat & q )
Performs quaternion addition.Arguments
- const quat & q - Quaternion.
Return value
Resulting quaternion.quat operator-( )
Performs quaternion negation. The sign of each component of the quaternion is flipped.Return value
Resulting quaternion.quat & operator-=( const quat & q )
Performs quaternion subtraction.Arguments
- const quat & q - Quaternion.
Return value
Resulting quaternion.quat & operator=( const __m128 & v )
Sets the quaternion using a __m128 variable (128-bit) as a source.Arguments
- const __m128 & v - 128-bit variable.
Return value
Resulting quaternion.quat & operator=( const quat & qq )
Performs quaternion assignment. Destination quaternion = Source quaternion.Arguments
- const quat & qq - Source quaternion.
Return value
Result.float & operator[]( int i )
Performs array access to the quaternion item reference by using given item index.Arguments
- int i - Quaternion item index.
Return value
Quaternion item reference.float operator[]( int i ) const
Performs array access to the quaternion item by using given item index.Arguments
- int i - Quaternion item index.
Return value
Quaternion item.__m128 sse( )
Returns quaternion components as a 128-bit variable.Return value
128-bit variable.void sse( const __m128 & v )
Sets the quaternion components using a given 128-bit variable.Arguments
- const __m128 & v - 128-bit variable.