Unigine::Math::quat Struct
Header: | #include <UnigineMathLibQuat.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: 45 degrees per second along X axis.
// AppWorldLogic.cpp file
// Declaring a pointer for a World light source node
NodePtr node;
int AppWorldLogic::init()
{
/* ... */
// Trying to find a World Node source in the current world
node = World::getNodeByType(Node::LIGHT_WORLD);
return 1;
}
int AppWorldLogic::update()
{
/* ... */
// get delta time value
float delta_time = Game::getIFps();
// create quat for 45 degrees per second rotation along X axis
Unigine::Math::quat rotation_delta = Unigine::Math::quat(1.0f, 0.0f, 0.0f, 45.0f * delta_time);
// rotate the node if it exists
if (node)
node->worldRotate(rotation_delta);
/* ... */
}
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 X axis component shows that the rotation will be performed along X axis.
See Also#
- An article on Quaternions and Spatial Rotation on Wikipedia.
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 ( ) #
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.
quat ( float x_, float y_, float z_, float w_, ConstexprTag ) #
Constructor. Initializes the quaternion using given constant 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 w_ - W component of the quaternion.
- ConstexprTag - Auxiliary tag.
void set ( float axis_x, float axis_y, float axis_z, float angle ) #
Sets the quaternion using the given angle and axis coordinates.Arguments
- float axis_x - X coordinate of the axis.
- float axis_y - Y coordinate of the axis.
- float axis_z - Z coordinate of the axis.
- float angle - Angle value, in degrees.
Examples
quat(1.0, 2.0, 3.0, 60);
/*
Creates a quaternion (0.133, 0.267, 0.4, 0.688)
*/
void set ( const float* q ) #
Sets the quaternion using a given pointer to the source quaternion.Arguments
- const float* q - 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 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 ) const#
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 ) const#
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 ( ) const#
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 & 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.const float * operator const float * ( ) const#
Performs type conversion to float void *.const void * operator const void * ( ) const#
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- ( ) const#
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& q ) #
Performs quaternion assignment. Destination quaternion = Source quaternion.Arguments
- const quat& q - 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.void set ( const vec4& v ) #
Sets the quaternion using a given four-component vec4 source vector.Arguments
- const vec4& v - Source vector.
void set ( const quat& v ) #
Sets the quaternion using the source quaternion.Arguments
- const quat& v - Source quaternion.