Quaternion API

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 <W, X, Y, Z> 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 <sh4zam/shz_quat.h>
• C++ header: #include <sh4zam/shz_quat.hpp>
• C++ types: shz::quat
• Symbols: 47

Suffixes

Suffixes used in this module. The full list is in 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	Initializes and returns a new quaternion with the given components, in WXYZ order.
shz_quat_identity	Initializes and returns an identity quaternion.
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	Initializes and returns a quaternion with the given X-Y-Z rotations in radians.
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	Returns the quaternion of the rotation shz_xmtrx_init_rotation_zyx() builds, Qz * Qy * Qx, from angles in radians.
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	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	Equivalent to shz_quat_from_rotation_xyz(), with 16-bit binary angles (65536 per turn, the FSCA unit).
shz_quat_from_rotation_zyx_u16	Equivalent to shz_quat_from_rotation_zyx(), with 16-bit binary angles.
shz_quat_from_rotation_zxy_u16	Equivalent to shz_quat_from_rotation_zxy(), with 16-bit binary angles.
shz_quat_from_rotation_yxz_u16	Equivalent to shz_quat_from_rotation_yxz(), with 16-bit binary angles.
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	Creates a quaternion looking in the given direction with the given reference direction.
shz_quat_from_rotated_axis	Returns the quaternion representing the rotation from axis v1 to v2.
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	Equivalent to shz_quat_lerp(), except that the resulting quaternion is normalized.
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	Evaluates a smooth cubic spherical interpolation (SQUAD) at parameter t.

Properties

Routines returning derived values from a quaternion.

Symbol	Description
shz_quat_angle	Returns the angle of rotation from the given quaternion.
shz_quat_axis	Returns the axis of rotation from the given quaternion.
shz_quat_angle_x	Returns the angle of rotation the quaternion represents about the X axis in radians.
shz_quat_angle_y	Returns the angle of rotation the quaternion represents about the Y axis in radians.
shz_quat_angle_z	Returns the angle of rotation the quaternion represents about the Z axis in radians.
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	Returns the roll, pitch, and yaw angles of rotation represented by the given quaternion.
shz_quat_magnitude_sqr	Returns the squared magnitude of the given quaternion.
shz_quat_magnitude	Returns the magnitude of the given quaternion.
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	Returns the normalized form of the given quaternion.
shz_quat_normalize_safe	SAFELY returns the normalized form of the given quaternion.
shz_quat_conjugate	Returns the conjugate of the given quaternion.
shz_quat_inv	Returns the inverse of the given quaternion.
shz_quat_neg	Returns the negation of the given quaternion.

Arithmetic

Routines performing calculations with quaternions.

Symbol	Description
shz_quat_add	Returns the quaternion produced from adding each component of the given quaternions.
shz_quat_sub	Returns the quaternion produced from subtracting each component of quaternion p from quaterion q.
shz_quat_scale	Scales the components of the given quaternion by the given factor.
shz_quat_mult	Multiplies the two quaternions, returning the result as a new quaternion.
shz_quat_div	Divides quaternion p by quaternion q (multiplying by its inverse), returning the resulting quaternion.
shz_quat_dot	Returns the dot product of the two quaternions.
shz_quat_dot2	Returns the two dot products taken between the l quaternion and the r1 and r2 quaternions.
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	Returns the angle in radians between the rotations represented by quaternions q and p.
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	Rotates a vector by the given quaternion.

Types

Symbol	Description
shz_quat_t	Represents a 3D quaternion.
shz_quat	Alternate shz_quat_t C typedef for those who hate POSIX style.