# 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::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.

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

## voidset( 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)
*/``````

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

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

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

### 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: 2018-12-27