Quaternion module

This module introduces a quaternion structure and operations on it, simplifying the built-in quaternion functions from the Daslang math module.

To use this module, include the following line in your project file:

require engine.math.quaternion // or require engine.core

Handled types

quat4

A stucture for quaternion representation. Internally, it’s just float4, so these two types can be easily converted one from another

Functions

quat4(): quat4

Returns the identity quaternion

quat4(value: float4): quat4

Constructs a quaternion from a given float4. Always returns a valid (normalized) quaternion

Arguments:

  • value : float4

quat4(euler_angles: float3): quat4

Constructs a quaternion from euler angles in radians. Each dimension in the euler_angles vector corresponds to a rotation around the respective axis

Arguments:

  • euler_angles : float3

quat4(from_direction: float3; to_direction: float3): quat4

Makes a quaternion that represents a rotation from from_direction to to_direction vectors. Note that the input vectors may not be normalized

Arguments:

  • from_direction : float3

  • to_direction : float3

quat4(m: float3x3 implicit): quat4

Constructs a quaternion from 3x3 matrix

Arguments:
quat4(m: float3x4 implicit): quat4

Constructs a quaternion from 3x4 matrix

Arguments:
quat4(m: float4x4 implicit): quat4

Constructs a quaternion from 4x4 matrix

Arguments:
quat4(nx: float3; ny: float3; nz: float3): quat4

Constructs a quaternion from basis vectors

Arguments:

  • nx : float3 - X-axis vector

  • ny : float3 - Y-axis vector

  • nz : float3 - Z-axis vector

make_quat_from_basis_xy(dir_x: float3; dir_y: float3): quat4

Constructs a quaternion from two basis vectors

Arguments:

  • dir_x : float3 - the new X-axis vector

  • dir_y : float3 - the new Y-axis vector

make_quat_from_basis_zy(dir_z: float3; dir_y: float3): quat4

Constructs a quaternion from two basis vectors

Arguments:

  • dir_z : float3 - the new Z-axis vector

  • dir_y : float3 - the new Y-axis vector

quat_to_euler(q: quat4): float3

Converts a quaternion to euler angles in radians :Arguments: * q : quat4

Returns:

  • float3 - the euler angles in radians (x contains the rotation around the x-axis, y contains the rotation around the y-axis, and z contains the rotation around the z-axis)

quat4*(q: quat4; v: float3): float3

Rotates a vector v by a quaternion q

Arguments:
quat4*(q1: quat4; q2: quat4): quat4

Multiplies two quaternions

Arguments:
inverse(q: quat4): quat4

Inverts a quaternion

Arguments:
normalize(q: quat4): quat4

Returns a normalized quaternion

Arguments:
slerp(from: quat4; to: quat4; t: float): quat4

Returns spherical linear interpolation between two quaternions

Arguments:

  • from : quat4 - the start quaternion

  • to : quat4 - the end quaternion

  • t : float - an interpolation factor

Returns:

  • quat4 - the resulting quaternion

approach(from: quat4; to: quat4; dt: float; half_life: float; eps: float = 1e-09f): quat4

Time independent exponential approach between from and to with given halflife. It used for smooth moving point x to target, in half_life period of time x will pass half of path. Returns the quaternion after moving from one quaternion to another with given half-life during the time interval, using exponential time-independent approach. It is used to smoothly move a quaternion, so that in a half_life period of time the quaternion will pass half of the path.

Arguments:

  • from : quat4 - the starting quaternion

  • to : quat4 - the target quaternion

  • dt : float - the time interval

  • half_life : float - the half-life of the approach

  • eps : float - the epsilon value to avoid division by zero

Returns:

  • quat4 - the new quaternion after moving from the starting quaternion to the target quaternion with the given half-life during the time interval

Usage example:

x = approach(x, target, dt, halflife)
quat4==(a: quat4; b: quat4): bool

Compares two quaternions for equality

Arguments:
quat4!=(a: quat4; b: quat4): bool

Compares two quaternions for inequality

Arguments:
float4(a: quat4): float4

Casts quat4 back to its base type float4

Arguments:
quat4(axis: float3; angle: float): quat4

Constructs a quaternion that represents a rotation around axis by an angle in radians. Note that axis may not be normalized

Arguments:

  • axis : float3

  • angle : float

quat4(x: auto; y: auto; z: auto): quat4

Constructs a quaternion from euler angles in radians.

Arguments:

  • x : auto - X-axis rotation

  • y : auto - Y-axis rotation

  • z : auto - Z-axis rotation

Returns:

  • quat4 - the quaternion that represents the rotation that rotates y radians around the y axis, z radians around the z axis, and x radians around the x axis; applied in that order.