# 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->setNodeWorldRotation(node->getNodeWorldRotation() * 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.

## int IDENTITY

### Description

Quaternion representing no rotation (0.0, 0.0, 0.0, 1.0).

## int ZERO

### Description

Zero quaternion (0.0, 0.0, 0.0, 0.0).
Last update: 2017-07-03