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.

Notice

It's supposed that you have already created node instance to rotate.

Source code (C#)

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

Methods:

Name	Description View: Sort by:
quat	Constructor.
set	Sets the quaternion by components.
get	Gets the quaternion: qq[0]=x, qq[1]=y, qq[2]=z, qq[3]=w.
getAngle	Returns the rotation angle of the quaternion for a given rotation axis.
getBinormal	Returns the quaternion binormal vector with respect to orientation.
getMat3	Returns the rotation matrix for the quaternion.
getNormal	Returns the quaternion normal vector.
getTangent	Returns the quaternion tangent vector.
getTangent4	Returns the quaternion tangent vector and binormal orientation as a four-component vec4 vector.
normalize	Returns normalized quaternion.
normalizeFast	Returns normalized quaternion, calculated using the fast inverse square root algorithm.
operator __m128	Performs type conversion to __m128.
operator const float *	Performs type conversion to float void *.
operator const void *	Performs type conversion to const void *.
operator float *	Performs type conversion to float *.
operator void *	Performs type conversion to void *.
*operator =**	Performs quaternion multiplication.
operator +=	Performs quaternion addition.
operator -	Performs quaternion negation.
operator -=	Performs quaternion subtraction.
operator =	Sets the quaternion using a __m128 variable (128-bit) as a source.
operator []	Performs array access to the quaternion item reference by using given item index.
sse	Returns quaternion components as a 128-bit variable.

Variables:

Name	Description
IDENTITY	Quaternion representing no rotation (0.0, 0.0, 0.0, 1.0).
ZERO	Zero quaternion (0.0, 0.0, 0.0, 0.0).

quat Class

Members

quat( const __m128 & v )

Constructor. Initializes the quaternion using a given __m128 variable (128-bit).

NoticeWe do not recommend to use this method unless you have a clear understanding of SSE2.

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

Source code (UnigineScript)

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.

Output

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² |

m128 operator m128( )

Performs type conversion to __m128.

NoticeWe do not recommend to use this method unless you have a clear understanding of SSE2.

quat & operator=( const __m128 & v )

Sets the quaternion using a __m128 variable (128-bit) as a source.

NoticeWe do not recommend to use this method unless you have a clear understanding of SSE2.

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.

NoticeWe do not recommend to use this method unless you have a clear understanding of SSE2.

Return value

128-bit variable.

void sse( const __m128 & v )

Sets the quaternion components using a given 128-bit variable.

NoticeWe do not recommend to use this method unless you have a clear understanding of SSE2.

Arguments

const __m128 & v - 128-bit variable.

Last update: 2018-12-27

Help improve this article

Was this article helpful?

Report a problem related to this article

(or select a word/phrase and press Ctrl+Enter)

Unigine::Math::quat Struct

Usage Example#

See Also#

Methods:

Variables:

quat Class

Members

quat( const __m128 & v )

Arguments

quat( const mat3 & m )

Arguments

quat( const vec4 & v )

Arguments

quat( const vec3 & v )

Arguments

quat( )

quat( const quat & q )

Arguments

quat( const vec3 & axis, float angle )

Arguments

quat( float angle_x, float angle_y, float angle_z )

Arguments

quat( const vec3 & col0, const vec3 & col1, const vec3 & col2 )

Arguments

quat( float x, float y, float z, float angle )

Arguments

explicit quat( const mat4 & m )

Arguments

explicit quat( const dmat4 & m )

Arguments

explicit quat( const float * q )

Arguments

void set( float x, float y, float z, float angle )

Arguments

Examples

void set( const float * qq )

Arguments

void set( const mat3 & m )

Arguments

void set( const vec3 & col0, const vec3 & col1, const vec3 & col2 )

Arguments

void set( float angle_x, float angle_y, float angle_z )

Arguments

void set( const vec3 & axis, float angle )

Arguments

void set( const vec3 & v )

Arguments

void set( const dmat4 & m )

Arguments

void set( const mat4 & m )

Arguments

void get( float * qq ) const

Arguments

float * get( )

Return value

const float * get( ) const

Return value

void get( vec3 & axis, float & angle )

Arguments

float getAngle( const vec3 & axis )

Arguments

Return value

vec3 getBinormal( ) const

Return value

mat3 getMat3( )

vec3 getNormal( ) const

Return value

vec3 getTangent( ) const

Return value

vec4 getTangent4( ) const

Return value

quat & normalize( )

Return value

quat & normalizeFast( )

Return value

__m128 operator __m128( )

const float * operator const float *( )

const void * operator const void *( )

float * operator float *( )

void * operator void *( )

m128 operator m128( )