.. _stdlib_public_quaternion: ================= 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 +++++++++++++ .. _handle-public_quaternion-quat4: .. das:attribute:: quat4 A stucture for quaternion representation. Internally, it's just ``float4``, so these two types can be easily converted one from another +++++++++ Functions +++++++++ * :ref:`quat4 () : quat4 ` * :ref:`quat4 (value: float4) : quat4 ` * :ref:`quat4 (euler_angles: float3) : quat4 ` * :ref:`quat4 (from_direction: float3; to_direction: float3) : quat4 ` * :ref:`quat4 (m: float3x3 implicit) : quat4 ` * :ref:`quat4 (m: float3x4 implicit) : quat4 ` * :ref:`quat4 (m: float4x4 implicit) : quat4 ` * :ref:`quat4 (nx: float3; ny: float3; nz: float3) : quat4 ` * :ref:`make_quat_from_basis_xy (dir_x: float3; dir_y: float3) : quat4 ` * :ref:`make_quat_from_basis_zy (dir_z: float3; dir_y: float3) : quat4 ` * :ref:`quat_to_euler (q: quat4) : float3 ` * :ref:`quat4* (q: quat4; v: float3) : float3 ` * :ref:`quat4* (q1: quat4; q2: quat4) : quat4 ` * :ref:`inverse (q: quat4) : quat4 ` * :ref:`normalize (q: quat4) : quat4 ` * :ref:`slerp (from: quat4; to: quat4; t: float) : quat4 ` * :ref:`approach (from: quat4; to: quat4; dt: float; half_life: float; eps: float = 1e-09f) : quat4 ` * :ref:`quat4== (a: quat4; b: quat4) : bool ` * :ref:`quat4\!= (a: quat4; b: quat4) : bool ` * :ref:`float4 (a: quat4) : float4 ` * :ref:`quat4 (axis: float3; angle: float) : quat4 ` * :ref:`quat4 (x: auto; y: auto; z: auto) : quat4 ` .. _function-public_quaternion_quat4: .. das:function:: quat4() : quat4 Returns the identity quaternion .. _function-public_quaternion_quat4_float4: .. das:function:: quat4(value: float4) : quat4 Constructs a quaternion from a given `float4`. Always returns a valid (normalized) quaternion :Arguments: * **value** : float4 .. _function-public_quaternion_quat4_float3: .. das:function:: 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 .. _function-public_quaternion_quat4_float3_float3: .. das:function:: 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 .. _function-public_quaternion_quat4_float3x3_implicit: .. das:function:: quat4(m: float3x3 implicit) : quat4 Constructs a quaternion from 3x3 matrix :Arguments: * **m** : :ref:`float3x3 ` implicit .. _function-public_quaternion_quat4_float3x4_implicit: .. das:function:: quat4(m: float3x4 implicit) : quat4 Constructs a quaternion from 3x4 matrix :Arguments: * **m** : :ref:`float3x4 ` implicit .. _function-public_quaternion_quat4_float4x4_implicit: .. das:function:: quat4(m: float4x4 implicit) : quat4 Constructs a quaternion from 4x4 matrix :Arguments: * **m** : :ref:`float4x4 ` implicit .. _function-public_quaternion_quat4_float3_float3_float3: .. das:function:: 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 .. _function-public_quaternion_make_quat_from_basis_xy_float3_float3: .. das:function:: 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 .. _function-public_quaternion_make_quat_from_basis_zy_float3_float3: .. das:function:: 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 .. _function-public_quaternion_quat_to_euler_quat4: .. das:function:: quat_to_euler(q: quat4) : float3 Converts a quaternion to euler angles in radians :Arguments: * **q** : :ref:`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) .. _function-public_quaternion__st__quat4_float3: .. das:function:: quat4*(q: quat4; v: float3) : float3 Rotates a vector `v` by a quaternion `q` :Arguments: * **q** : :ref:`quat4 ` * **v** : float3 .. _function-public_quaternion__st__quat4_quat4: .. das:function:: quat4*(q1: quat4; q2: quat4) : quat4 Multiplies two quaternions :Arguments: * **q1** : :ref:`quat4 ` * **q2** : :ref:`quat4 ` .. _function-public_quaternion_inverse_quat4: .. das:function:: inverse(q: quat4) : quat4 Inverts a quaternion :Arguments: * **q** : :ref:`quat4 ` .. _function-public_quaternion_normalize_quat4: .. das:function:: normalize(q: quat4) : quat4 Returns a normalized quaternion :Arguments: * **q** : :ref:`quat4 ` .. _function-public_quaternion_slerp_quat4_quat4_float: .. das:function:: slerp(from: quat4; to: quat4; t: float) : quat4 Returns spherical linear interpolation between two quaternions :Arguments: * **from** : :ref:`quat4 ` - the start quaternion * **to** : :ref:`quat4 ` - the end quaternion * **t** : float - an interpolation factor :Returns: * :ref:`quat4 ` - the resulting quaternion .. _function-public_quaternion_approach_quat4_quat4_float_float_float: .. das:function:: 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** : :ref:`quat4 ` - the starting quaternion * **to** : :ref:`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: * :ref:`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) .. _function-public_quaternion__eq__eq__quat4_quat4: .. das:function:: quat4==(a: quat4; b: quat4) : bool Compares two quaternions for equality :Arguments: * **a** : :ref:`quat4 ` * **b** : :ref:`quat4 ` .. _function-public_quaternion__ex__eq__quat4_quat4: .. das:function:: quat4!=(a: quat4; b: quat4) : bool Compares two quaternions for inequality :Arguments: * **a** : :ref:`quat4 ` * **b** : :ref:`quat4 ` .. _function-public_quaternion_float4_quat4: .. das:function:: float4(a: quat4) : float4 Casts `quat4` back to its base type `float4` :Arguments: * **a** : :ref:`quat4 ` .. _function-public_quaternion_quat4_float3_float: .. das:function:: 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 .. _function-quaternion_quat4_auto_auto_auto: .. das:function:: 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: * :ref:`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.