# shz::quat Source: https://sh4zam.com/api/cpp/quat/ C++ structure representing a quaternion. A quaternion represents a rotation about an arbitrary axis in 3D space. - **Header:** `#include ` ([source](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.hpp#L38)) - **C type:** [`shz_quat_t`](https://sh4zam.com/api/quat/shz_quat_t/) (layout-compatible; the C API accepts it directly) - **Bases:** `shz_quat_t` ## Static functions ### identity ```cpp static quat identity() noexcept ``` Returns an identity quaternion. Calls: [`shz_quat_identity()`](https://sh4zam.com/api/quat/shz_quat_identity/) ### from_angles_xyz ```cpp static quat from_angles_xyz(float x, float y, float z) noexcept ``` C++ convenience wrapper for `shz_quat_from_angles_xyz()`. Calls: [`shz_quat_from_angles_xyz()`](https://sh4zam.com/api/quat/shz_quat_from_angles_xyz/) ### from_rotation_xyz ```cpp static quat from_rotation_xyz(float x, float y, float z) noexcept ``` C++ convenience wrapper for `shz_quat_from_rotation_xyz()`. Calls: [`shz_quat_from_rotation_xyz()`](https://sh4zam.com/api/quat/shz_quat_from_rotation_xyz/) ### from_rotation_zyx ```cpp static quat from_rotation_zyx(float z, float y, float x) noexcept ``` C++ convenience wrapper for `shz_quat_from_rotation_zyx()`. Calls: [`shz_quat_from_rotation_zyx()`](https://sh4zam.com/api/quat/shz_quat_from_rotation_zyx/) ### from_rotation_zxy ```cpp static quat from_rotation_zxy(float z, float x, float y) noexcept ``` C++ convenience wrapper for `shz_quat_from_rotation_zxy()`. Calls: [`shz_quat_from_rotation_zxy()`](https://sh4zam.com/api/quat/shz_quat_from_rotation_zxy/) ### from_rotation_yxz ```cpp static quat from_rotation_yxz(float y, float x, float z) noexcept ``` C++ convenience wrapper for `shz_quat_from_rotation_yxz()`. Calls: [`shz_quat_from_rotation_yxz()`](https://sh4zam.com/api/quat/shz_quat_from_rotation_yxz/) ### from_rotation_xyz_u16 ```cpp static quat from_rotation_xyz_u16(uint16_t x, uint16_t y, uint16_t z) noexcept ``` C++ convenience wrapper for `shz_quat_from_rotation_xyz_u16()`. Calls: [`shz_quat_from_rotation_xyz_u16()`](https://sh4zam.com/api/quat/shz_quat_from_rotation_xyz_u16/) ### from_rotation_zyx_u16 ```cpp static quat from_rotation_zyx_u16(uint16_t z, uint16_t y, uint16_t x) noexcept ``` C++ convenience wrapper for `shz_quat_from_rotation_zyx_u16()`. Calls: [`shz_quat_from_rotation_zyx_u16()`](https://sh4zam.com/api/quat/shz_quat_from_rotation_zyx_u16/) ### from_rotation_zxy_u16 ```cpp static quat from_rotation_zxy_u16(uint16_t z, uint16_t x, uint16_t y) noexcept ``` C++ convenience wrapper for `shz_quat_from_rotation_zxy_u16()`. Calls: [`shz_quat_from_rotation_zxy_u16()`](https://sh4zam.com/api/quat/shz_quat_from_rotation_zxy_u16/) ### from_rotation_yxz_u16 ```cpp static quat from_rotation_yxz_u16(uint16_t y, uint16_t x, uint16_t z) noexcept ``` C++ convenience wrapper for `shz_quat_from_rotation_yxz_u16()`. Calls: [`shz_quat_from_rotation_yxz_u16()`](https://sh4zam.com/api/quat/shz_quat_from_rotation_yxz_u16/) ### from_axis_angle ```cpp static quat from_axis_angle(const vec3 &axis, float angle) noexcept ``` Initializes a quaternion which is a rotation in `angle` radians about the given `axis`. Calls: [`shz_quat_from_axis_angle()`](https://sh4zam.com/api/quat/shz_quat_from_axis_angle/) ### from_look_axis ```cpp static quat from_look_axis(const vec3 &forward, const vec3 &up) noexcept ``` Creates a quaternion looking in the given direction with the given reference direction. Calls: [`shz_quat_from_look_axis()`](https://sh4zam.com/api/quat/shz_quat_from_look_axis/) ### from_rotated_axis ```cpp static quat from_rotated_axis(const vec3 &start, const vec3 &end) noexcept ``` Returns the quaternion representing the rotation from the `start` to the `end` axes. Calls: [`shz_quat_from_rotated_axis()`](https://sh4zam.com/api/quat/shz_quat_from_rotated_axis/) ### lerp ```cpp static quat lerp(const quat &q, const quat &p, float t) noexcept ``` Returns the quaternion that is linearly interpolating `q` to `p`, by a t factor of `0.0f-1.0f`. Calls: [`shz_quat_lerp()`](https://sh4zam.com/api/quat/shz_quat_lerp/) ### nlerp ```cpp static quat nlerp(const quat &q, const quat &p, float t) noexcept ``` Equivalent to `lerp()`, except that the resulting quaternion is normalized. Calls: [`shz_quat_nlerp()`](https://sh4zam.com/api/quat/shz_quat_nlerp/) ### slerp ```cpp static quat slerp(const quat &q, const quat &p, float t) noexcept ``` Returns the quaternion that is spherically linearly interpolating `q` to `p`, by a `t` factor of `0.0f-1.0f`. Calls: [`shz_quat_slerp()`](https://sh4zam.com/api/quat/shz_quat_slerp/) ### squad ```cpp static quat squad(const quat &q1, const quat &q2, const quat &s1, const quat &s2, float t) noexcept ``` Evaluates the smooth cubic spherical interpolation (SQUAD) at parameter `t`. Calls: [`shz_quat_squad()`](https://sh4zam.com/api/quat/shz_quat_squad/) ## Members ### quat ```cpp quat() noexcept=default quat(const quat &other) noexcept=default quat(float w, float x, float y, float z) noexcept quat(const shz_quat_t &q) noexcept quat(const volatile shz_quat_t &other) noexcept ``` Default constructor: does nothing. ### angle ```cpp float angle() const noexcept ``` Returns the angle of rotation represented by the given quaternion. Calls: [`shz_quat_angle()`](https://sh4zam.com/api/quat/shz_quat_angle/) ### axis ```cpp vec3 axis() const noexcept ``` Returns the axis of rotation represented by the given quaternion. Calls: [`shz_quat_axis()`](https://sh4zam.com/api/quat/shz_quat_axis/) ### angle_x ```cpp float angle_x() const noexcept ``` Returns the angle of rotation about the X axis represented by the given quaternion. Calls: [`shz_quat_angle_x()`](https://sh4zam.com/api/quat/shz_quat_angle_x/) ### angle_y ```cpp float angle_y() const noexcept ``` Returns the angle of rotation about the Y axis represented by the given quaternion. Calls: [`shz_quat_angle_y()`](https://sh4zam.com/api/quat/shz_quat_angle_y/) ### angle_z ```cpp float angle_z() const noexcept ``` Returns the angle of rotation about the Z axis represented by the given quaternion. Calls: [`shz_quat_angle_z()`](https://sh4zam.com/api/quat/shz_quat_angle_z/) ### magnitude_sqr ```cpp float magnitude_sqr() const noexcept ``` Returns the magnitude of the quaternion squared. Calls: [`shz_quat_magnitude_sqr()`](https://sh4zam.com/api/quat/shz_quat_magnitude_sqr/) ### magnitude ```cpp float magnitude() const noexcept ``` Returns the magnitude of the quaternion. Calls: [`shz_quat_magnitude()`](https://sh4zam.com/api/quat/shz_quat_magnitude/) ### magnitude_inv ```cpp float magnitude_inv() const noexcept ``` Returns the inverse of the magnitude of the quaternion. Calls: [`shz_quat_magnitude_inv()`](https://sh4zam.com/api/quat/shz_quat_magnitude_inv/) ### to_angles_xyz ```cpp vec3 to_angles_xyz() const noexcept ``` Returns the tait-bryan rotation angles about the X, Y, then Z axes which are represented by the given quaternion. Calls: [`shz_quat_to_angles_xyz()`](https://sh4zam.com/api/quat/shz_quat_to_angles_xyz/) ### to_axis_angle ```cpp void to_axis_angle(shz_vec3_t *axis, float *angle) const noexcept std::pair< vec3, float > to_axis_angle() const noexcept ``` Returns both the axis and angle of rotation through the pointer arguments. Calls: [`shz_quat_to_axis_angle()`](https://sh4zam.com/api/quat/shz_quat_to_axis_angle/) ### normalized ```cpp quat normalized() const noexcept ``` Returns the given quaternion as a unit quaternion. Calls: [`shz_quat_normalize()`](https://sh4zam.com/api/quat/shz_quat_normalize/) ### normalize ```cpp void normalize() noexcept ``` Normalizes the given quaternion. ### normalized_safe ```cpp quat normalized_safe() const noexcept ``` Returns a safely normalized quaternion from the given quaternion, protecting against division-by-zero. Calls: [`shz_quat_normalize_safe()`](https://sh4zam.com/api/quat/shz_quat_normalize_safe/) ### normalize_safe ```cpp void normalize_safe() noexcept ``` Safely normalizes the given quaternion by protecting against division-by-zero. ### conjugated ```cpp quat conjugated() const noexcept ``` Returns a quaternion that is the conjugate of the given quaternion. Calls: [`shz_quat_conjugate()`](https://sh4zam.com/api/quat/shz_quat_conjugate/) ### conjugate ```cpp void conjugate() noexcept ``` Conjugates the given quaternion. ### inverse ```cpp quat inverse() const noexcept ``` Returns the inverse of the given quaternion. Calls: [`shz_quat_inv()`](https://sh4zam.com/api/quat/shz_quat_inv/) ### invert ```cpp void invert() noexcept ``` Inverts the given quaternion. ### negated ```cpp quat negated() const noexcept ``` Returns a new quaternion whose components are the negated values of the given quaternion. Calls: [`shz_quat_neg()`](https://sh4zam.com/api/quat/shz_quat_neg/) ### negate ```cpp void negate() noexcept ``` Negates the components of the given quaternion. ### add ```cpp quat add(const quat &rhs) const noexcept ``` Returns a new quaternion from adding the given quaterion to `rhs`. Calls: [`shz_quat_add()`](https://sh4zam.com/api/quat/shz_quat_add/) ### sub ```cpp quat sub(const quat &rhs) const noexcept ``` Returns a new quaternion from adding `rhs` from the given quaternion. Calls: [`shz_quat_sub()`](https://sh4zam.com/api/quat/shz_quat_sub/) ### scaled ```cpp quat scaled(float s) const noexcept ``` Returns a new quaternion from scaling the given quaterion by `s`. Calls: [`shz_quat_scale()`](https://sh4zam.com/api/quat/shz_quat_scale/) ### scale ```cpp void scale(float s) noexcept ``` Multiplies each component of the given quaternion by `s`. ### dot ```cpp float dot(const quat &other) const noexcept vec2 dot(const quat &q1, const quat &q2) const noexcept vec3 dot(const quat &q1, const quat &q2, const quat &q3) const noexcept ``` Returns the dot product between the given quaternion and another. Calls: [`shz_quat_dot()`](https://sh4zam.com/api/quat/shz_quat_dot/), [`shz_quat_dot2()`](https://sh4zam.com/api/quat/shz_quat_dot2/), [`shz_quat_dot3()`](https://sh4zam.com/api/quat/shz_quat_dot3/) ### mult ```cpp quat mult(const quat &rhs) const noexcept ``` Returns a new quaterion from multiplying the given quaternion by another. Calls: [`shz_quat_mult()`](https://sh4zam.com/api/quat/shz_quat_mult/) ### div ```cpp quat div(const quat &rhs) const noexcept ``` Returns a new quaterion from dividing the given quaternion by another (or multiplying the given quaternion by the inverse of another). Calls: [`shz_quat_div()`](https://sh4zam.com/api/quat/shz_quat_div/) ### angle_between ```cpp float angle_between(const quat &p) const noexcept ``` Returns the angle in radians between the rotations represented by quaternions `q` and `p`. Calls: [`shz_quat_angle_between()`](https://sh4zam.com/api/quat/shz_quat_angle_between/) ### rotate_towards ```cpp quat rotate_towards(const quat &to, float max_angle) const noexcept ``` Rotates quaternion `from` towards quaternion `to` by at most `max_angle` radians. Calls: [`shz_quat_rotate_towards()`](https://sh4zam.com/api/quat/shz_quat_rotate_towards/) ### transform ```cpp vec3 transform(const vec3 &in) const noexcept ``` Returns a new `shz::vec3` from transforming `in` by the given quaternion. Calls: [`shz_quat_transform_vec3()`](https://sh4zam.com/api/quat/shz_quat_transform_vec3/) ### operator- ```cpp quat operator-() const noexcept ``` Overloaded unary negation operator, returns the negation of the given quaternion. ### operator+= ```cpp quat operator+=(const quat &rhs) noexcept ``` Adds and accumulates `rhs` onto the given quaternion. ### operator-= ```cpp quat operator-=(const quat &rhs) noexcept ``` Subtracts `rhs` from the given quaternion. ### operator*= ```cpp quat operator*=(const quat &rhs) noexcept quat operator*=(float rhs) noexcept ``` Multiplies and accumulates `rhs` into the given quaternion. ### operator/= ```cpp quat operator/=(const quat &rhs) noexcept quat operator/=(float rhs) noexcept ``` Divides the given quaternion by `rhs`. Calls: [`shz_invf()`](https://sh4zam.com/api/scalar/shz_invf/) ### operator== ```cpp bool operator==(const quat &lhs, const quat &rhs) noexcept ``` Overloaded comparison operator, checks for quaternion equality.