Struct Quaternion

#[repr(C)]
pub struct Quaternion {
    pub x: f32,
    pub y: f32,
    pub z: f32,
    pub w: f32,
}

Represents a quaternion for efficient 3D rotations.

Quaternions are a four-dimensional complex number system that can represent rotations in 3D space. They are generally more efficient and numerically stable than rotation matrices, avoiding issues like gimbal lock.

A quaternion is stored as (x, y, z, w), where [x, y, z] is the “vector” part and w is the “scalar” part. For representing rotations, it should be a “unit quaternion” where x² + y² + z² + w² = 1.

Fields

x: f32

The x component of the vector part.

y: f32

The y component of the vector part.

z: f32

The z component of the vector part.

w: f32

The scalar (real) part.

Implementations

impl Quaternion

pub const IDENTITY: Quaternion

The identity quaternion, representing no rotation.

pub fn new(x: f32, y: f32, z: f32, w: f32) -> Self

Creates a new quaternion from its raw components.

Note: This does not guarantee a unit quaternion. For creating rotations, prefer using from_axis_angle or other rotation-specific constructors.

pub fn from_axis_angle(axis: Vec3, angle_radians: f32) -> Self

Creates a quaternion representing a rotation around a given axis by a given angle.

Arguments

• axis: The axis of rotation. It is recommended to pass a normalized vector.
• angle_radians: The angle of rotation in radians.

pub fn from_rotation_matrix(m: &Mat4) -> Self

Creates a quaternion from a 4x4 rotation matrix.

This method only considers the upper 3x3 part of the matrix for the conversion.

pub fn magnitude_squared(&self) -> f32

Calculates the squared length (magnitude) of the quaternion.

pub fn magnitude(&self) -> f32

Calculates the length (magnitude) of the quaternion.

pub fn normalize(&self) -> Self

Returns a normalized version of the quaternion with a length of 1. If the quaternion has a near-zero magnitude, it returns the identity quaternion.

pub fn conjugate(&self) -> Self

Computes the conjugate of the quaternion, which negates the vector part.

pub fn inverse(&self) -> Self

Computes the inverse of the quaternion. For a unit quaternion, the inverse is equal to its conjugate.

pub fn dot(&self, other: Self) -> f32

Computes the dot product of two quaternions.

pub fn rotate_vec3(&self, v: Vec3) -> Vec3

Rotates a 3D vector by this quaternion.

pub fn slerp(start: Self, end: Self, t: f32) -> Self

Performs a Spherical Linear Interpolation (Slerp) between two quaternions.

Slerp provides a smooth, constant-speed interpolation between two rotations, following the shortest path on the surface of a 4D sphere.

• t - The interpolation factor, clamped to the [0.0, 1.0] range.

Trait Implementations

impl Add for Quaternion

fn add(self, rhs: Self) -> Self::Output

Adds two quaternions component-wise. Note: This is not a standard rotation operation.

type Output = Quaternion

The resulting type after applying the + operator.

impl Clone for Quaternion

fn clone(&self) -> Quaternion

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Quaternion

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Quaternion

fn default() -> Self

Returns the identity quaternion, representing no rotation.

impl Mul<Vec3> for Quaternion

fn mul(self, rhs: Vec3) -> Self::Output

Rotates a Vec3 by this quaternion.

type Output = Vec3

The resulting type after applying the * operator.

impl Mul<f32> for Quaternion

fn mul(self, scalar: f32) -> Self::Output

Scales all components of the quaternion by a scalar.

type Output = Quaternion

The resulting type after applying the * operator.

impl Mul for Quaternion

fn mul(self, rhs: Self) -> Self::Output

Combines two rotations using the Hamilton product. Note that quaternion multiplication is not commutative.

type Output = Quaternion

The resulting type after applying the * operator.

impl MulAssign for Quaternion

fn mul_assign(&mut self, rhs: Self)

Combines this rotation with another.

impl Neg for Quaternion

fn neg(self) -> Self::Output

Negates all components of the quaternion.

type Output = Quaternion

The resulting type after applying the - operator.

impl PartialEq for Quaternion

fn eq(&self, other: &Quaternion) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Sub for Quaternion

fn sub(self, rhs: Self) -> Self::Output

Subtracts two quaternions component-wise.

type Output = Quaternion

The resulting type after applying the - operator.

impl Copy for Quaternion

impl StructuralPartialEq for Quaternion