# Quaternion API Source: https://sh4zam.com/api/quat/ > Routines for quaternion math This module contains the public type(s) and interface providing the quaternion math API. Quaternions are a mathematical structure representing a rotation about a single arbitrary axis. `shz_quat_t` is stored in `` order, with W first, and the identity quaternion is (1, 0, 0, 0). Interpolation covers `lerp`, `nlerp`, `slerp` and `squad`, and C++ users get the same API on `shz::quat`. - **C header:** `#include ` - **C++ header:** `#include ` - **C++ types:** [`shz::quat`](https://sh4zam.com/api/cpp/quat/) - **Symbols:** 47 ## Suffixes Suffixes used in this module. The full list is in [Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/). - `_safe`: Guards degenerate input (zero-length vectors, zero denominators) at a small cost. - `_deg`: Angle argument is in degrees. The default is radians. - `dot2/dot3`: Computes 2 or 3 dot products of one left-hand side against several right-hand sides in one pipelined `FIPR` sequence. ## Initialization Routines for creating and initializing quaternions. | Symbol | Description | | --- | --- | | [`shz_quat_init`](https://sh4zam.com/api/quat/shz_quat_init/) | Initializes and returns a new quaternion with the given components, in WXYZ order. | | [`shz_quat_identity`](https://sh4zam.com/api/quat/shz_quat_identity/) | Initializes and returns an identity quaternion. | | [`shz_quat_equal`](https://sh4zam.com/api/quat/shz_quat_equal/) | Returns true if the two given quaternions are considered equal based on either absolute or relative tolerance. | | [`shz_quat_from_angles_xyz`](https://sh4zam.com/api/quat/shz_quat_from_angles_xyz/) | Initializes and returns a quaternion with the given X-Y-Z rotations in radians. | | [`shz_quat_from_rotation_xyz`](https://sh4zam.com/api/quat/shz_quat_from_rotation_xyz/) | Returns the quaternion of the rotation `shz_xmtrx_init_rotation_xyz()` builds, from angles in radians. | | [`shz_quat_from_rotation_zyx`](https://sh4zam.com/api/quat/shz_quat_from_rotation_zyx/) | Returns the quaternion of the rotation `shz_xmtrx_init_rotation_zyx()` builds, Qz \* Qy \* Qx, from angles in radians. | | [`shz_quat_from_rotation_zxy`](https://sh4zam.com/api/quat/shz_quat_from_rotation_zxy/) | Returns the quaternion of the rotation `shz_xmtrx_init_rotation_zxy()` builds, Qz \* Qx \* Qy, from angles in radians. | | [`shz_quat_from_rotation_yxz`](https://sh4zam.com/api/quat/shz_quat_from_rotation_yxz/) | Returns the quaternion of the rotation `shz_xmtrx_init_rotation_yxz()` builds, Qy \* Qx \* Qz, from angles in radians. | | [`shz_quat_from_rotation_xyz_u16`](https://sh4zam.com/api/quat/shz_quat_from_rotation_xyz_u16/) | Equivalent to `shz_quat_from_rotation_xyz()`, with 16-bit binary angles (65536 per turn, the FSCA unit). | | [`shz_quat_from_rotation_zyx_u16`](https://sh4zam.com/api/quat/shz_quat_from_rotation_zyx_u16/) | Equivalent to `shz_quat_from_rotation_zyx()`, with 16-bit binary angles. | | [`shz_quat_from_rotation_zxy_u16`](https://sh4zam.com/api/quat/shz_quat_from_rotation_zxy_u16/) | Equivalent to `shz_quat_from_rotation_zxy()`, with 16-bit binary angles. | | [`shz_quat_from_rotation_yxz_u16`](https://sh4zam.com/api/quat/shz_quat_from_rotation_yxz_u16/) | Equivalent to `shz_quat_from_rotation_yxz()`, with 16-bit binary angles. | | [`shz_quat_from_axis_angle`](https://sh4zam.com/api/quat/shz_quat_from_axis_angle/) | Initializes and returns a quaternion representing a rotation of `angle` radians about the given `axis`. | | [`shz_quat_from_look_axis`](https://sh4zam.com/api/quat/shz_quat_from_look_axis/) | Creates a quaternion looking in the given direction with the given reference direction. | | [`shz_quat_from_rotated_axis`](https://sh4zam.com/api/quat/shz_quat_from_rotated_axis/) | Returns the quaternion representing the rotation from axis `v1` to `v2`. | | [`shz_quat_lerp`](https://sh4zam.com/api/quat/shz_quat_lerp/) | Returns the quaternion that is linearly interpolating `a` to `b`, by a t factor of `0.0f-1.0f`. | | [`shz_quat_nlerp`](https://sh4zam.com/api/quat/shz_quat_nlerp/) | Equivalent to `shz_quat_lerp()`, except that the resulting quaternion is normalized. | | [`shz_quat_slerp`](https://sh4zam.com/api/quat/shz_quat_slerp/) | Returns the quaternion that is spherically linearly interpolating `a` to `b`, by a `t` factor of `0.0f-1.0f`. | | [`shz_quat_squad`](https://sh4zam.com/api/quat/shz_quat_squad/) | Evaluates a smooth cubic spherical interpolation (SQUAD) at parameter `t`. | ## Properties Routines returning derived values from a quaternion. | Symbol | Description | | --- | --- | | [`shz_quat_angle`](https://sh4zam.com/api/quat/shz_quat_angle/) | Returns the angle of rotation from the given quaternion. | | [`shz_quat_axis`](https://sh4zam.com/api/quat/shz_quat_axis/) | Returns the axis of rotation from the given quaternion. | | [`shz_quat_angle_x`](https://sh4zam.com/api/quat/shz_quat_angle_x/) | Returns the angle of rotation the quaternion represents about the X axis in radians. | | [`shz_quat_angle_y`](https://sh4zam.com/api/quat/shz_quat_angle_y/) | Returns the angle of rotation the quaternion represents about the Y axis in radians. | | [`shz_quat_angle_z`](https://sh4zam.com/api/quat/shz_quat_angle_z/) | Returns the angle of rotation the quaternion represents about the Z axis in radians. | | [`shz_quat_to_axis_angle`](https://sh4zam.com/api/quat/shz_quat_to_axis_angle/) | Returns both the axis and angle of rotation simultaneously (faster if both are needed) from the given quaternion. | | [`shz_quat_to_angles_xyz`](https://sh4zam.com/api/quat/shz_quat_to_angles_xyz/) | Returns the roll, pitch, and yaw angles of rotation represented by the given quaternion. | | [`shz_quat_magnitude_sqr`](https://sh4zam.com/api/quat/shz_quat_magnitude_sqr/) | Returns the squared magnitude of the given quaternion. | | [`shz_quat_magnitude`](https://sh4zam.com/api/quat/shz_quat_magnitude/) | Returns the magnitude of the given quaternion. | | [`shz_quat_magnitude_inv`](https://sh4zam.com/api/quat/shz_quat_magnitude_inv/) | Returns the inverse magnitude of the given quaternion. | ## Modifiers Routines for returning new quaternions derived from existing ones. | Symbol | Description | | --- | --- | | [`shz_quat_normalize`](https://sh4zam.com/api/quat/shz_quat_normalize/) | Returns the normalized form of the given quaternion. | | [`shz_quat_normalize_safe`](https://sh4zam.com/api/quat/shz_quat_normalize_safe/) | SAFELY returns the normalized form of the given quaternion. | | [`shz_quat_conjugate`](https://sh4zam.com/api/quat/shz_quat_conjugate/) | Returns the conjugate of the given quaternion. | | [`shz_quat_inv`](https://sh4zam.com/api/quat/shz_quat_inv/) | Returns the inverse of the given quaternion. | | [`shz_quat_neg`](https://sh4zam.com/api/quat/shz_quat_neg/) | Returns the negation of the given quaternion. | ## Arithmetic Routines performing calculations with quaternions. | Symbol | Description | | --- | --- | | [`shz_quat_add`](https://sh4zam.com/api/quat/shz_quat_add/) | Returns the quaternion produced from adding each component of the given quaternions. | | [`shz_quat_sub`](https://sh4zam.com/api/quat/shz_quat_sub/) | Returns the quaternion produced from subtracting each component of quaternion `p` from quaterion `q`. | | [`shz_quat_scale`](https://sh4zam.com/api/quat/shz_quat_scale/) | Scales the components of the given quaternion by the given factor. | | [`shz_quat_mult`](https://sh4zam.com/api/quat/shz_quat_mult/) | Multiplies the two quaternions, returning the result as a new quaternion. | | [`shz_quat_div`](https://sh4zam.com/api/quat/shz_quat_div/) | Divides quaternion `p` by quaternion `q` (multiplying by its inverse), returning the resulting quaternion. | | [`shz_quat_dot`](https://sh4zam.com/api/quat/shz_quat_dot/) | Returns the dot product of the two quaternions. | | [`shz_quat_dot2`](https://sh4zam.com/api/quat/shz_quat_dot2/) | Returns the two dot products taken between the `l` quaternion and the `r1` and `r2` quaternions. | | [`shz_quat_dot3`](https://sh4zam.com/api/quat/shz_quat_dot3/) | Returns the two dot products taken between the `l` quaternion and the `r1`, `r2`, and `r3` quaternions. | ## Miscellaneous Other types of quaternion operations. | Symbol | Description | | --- | --- | | [`shz_quat_angle_between`](https://sh4zam.com/api/quat/shz_quat_angle_between/) | Returns the angle in radians between the rotations represented by quaternions `q` and `p`. | | [`shz_quat_rotate_towards`](https://sh4zam.com/api/quat/shz_quat_rotate_towards/) | Rotates quaternion `from` towards quaternion `to` by at most `max_angle` radians. | ## Transformations Routines for applying quaternion transforms. | Symbol | Description | | --- | --- | | [`shz_quat_transform_vec3`](https://sh4zam.com/api/quat/shz_quat_transform_vec3/) | Rotates a vector by the given quaternion. | ## Types | Symbol | Description | | --- | --- | | [`shz_quat_t`](https://sh4zam.com/api/quat/shz_quat_t/) | Represents a 3D quaternion. | | [`shz_quat`](https://sh4zam.com/api/quat/shz_quat/) | Alternate [`shz_quat_t`](https://sh4zam.com/api/quat/shz_quat_t/) C typedef for those who hate POSIX style. |