Warning! This version of documentation is OUTDATED, as it describes an older SDK version! Please switch to the documentation for the latest SDK version.
Warning! This version of documentation describes an old SDK version which is no longer supported! Please upgrade to the latest SDK version.

# Unigine::Math::quat Struct

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::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->WorldRotate(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.

## quat ( const __m128 & v ) #

Constructor. Initializes the quaternion using a given __m128 variable (128-bit).
Notice
We 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 ( ) #

Constructor. Initializes 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.

## voidset ( float x, float y, float z, float angle ) #

Sets the quaternion using the given angle and axis coordinates.

### Arguments

• float x - X coordinate of the axis.
• float y - Y coordinate of the axis.
• float z - Z coordinate of the axis.
• float angle - Angle value, in degrees.

### Examples

Source code (UnigineScript)
``````quat(1.0, 2.0, 3.0, 60);
/*
Creates a quaternion (0.133, 0.267, 0.4, 0.688)
*/``````

## voidset ( const float * qq ) #

Sets the quaternion using a given pointer to the source quaternion.

### Arguments

• const float * qq - Pointer to the source quaternion.

## voidset ( const mat3 & m ) #

Sets the quaternion using a given mat3 source matrix (3x3).

### Arguments

• const mat3 & m - Source matrix (3x3).

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

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

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

## voidset ( const vec3 & v ) #

Sets the quaternion using a given three-component vec3 source vector.

### Arguments

• const vec3 & v - Three-component source vector.

## voidset ( const dmat4 & m ) #

Sets the quaternion using a given dmat4 source matrix (3x4).

### Arguments

• const dmat4 & m - Source matrix (3x4).

## voidset ( const mat4 & m ) #

Sets the quaternion using a given mat4 source matrix (4x4).

### Arguments

• const mat4 & m - Source matrix (4x4).

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

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

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

## vec3getBinormal ( ) const#

Returns the quaternion binormal vector with respect to orientation.

### Return value

Quaternion binormal vector.

## mat3getMat3 ( ) #

Returns the rotation matrix for 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² |``````

## vec3getNormal ( ) const#

Returns the quaternion normal vector.

### Return value

Quaternion normal vector.

## vec3getTangent ( ) const#

Returns the quaternion tangent vector.

### Return value

Quaternion tangent vector.

## vec4getTangent4 ( ) 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 &normalizeValid ( ) #

Normalizes a quaternion, makes its magnitude equal to 1. When normalized, a quaternion keeps the same direction but its length is equal to 1. Check for the zero quaternion is performed: if the argument is a zero quaternion, then a zero quaternion is returned.

### Return value

Normalized quaternion.

## quat &normalizeFast ( ) #

Returns normalized quaternion, calculated using the fast inverse square root algorithm.

### Return value

Normalized quaternion.

## quat &normalizeValidFast ( ) #

Returns normalized quaternion, calculated using the fast inverse square root algorithm. Check for the zero quaternion is performed: if the argument is a zero quaternion, then a zero quaternion is returned.

### Return value

Normalized quaternion.

## __m128operator __m128 ( ) #

Performs type conversion to __m128.
Notice
We do not recommend to use this method unless you have a clear understanding of SSE2.

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

### Arguments

• const quat & q - Quaternion.

### Return value

Resulting quaternion.

## quatoperator- ( ) #

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.
Notice
We 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.

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.

## floatoperator[] ( int i ) const#

Performs array access to the quaternion item by using given item index.

### Arguments

• int i - Quaternion item index.

Quaternion item.

## __m128sse ( ) #

Returns quaternion components as a 128-bit variable.
Notice
We do not recommend to use this method unless you have a clear understanding of SSE2.

### Return value

128-bit variable.

## voidsse ( const __m128 & v ) #

Sets the quaternion components using a given 128-bit variable.
Notice
We do not recommend to use this method unless you have a clear understanding of SSE2.

### Arguments

• const __m128 & v - 128-bit variable.
Last update: 2021-04-29