Struct Quat

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

Quaternions are efficient and robust mathematical objects for representing rotations! Understanding the details of how a quaternion works is not generally necessary for using them effectively, so don’t worry too much if they seem weird to you. They’re weird to me too.

If you’re interested in learning the details though, 3Blue1Brown and Ben Eater have an excellent interactive lesson about them! https://stereokit.net/Pages/StereoKit/Quat.html

see also glam::Quat

Examples

use stereokit_rust::maths::{Quat, Vec3, Vec4};

let mut quat1 = Quat::new(0.0, 0.0, 0.0, 1.0);
let mut quat2 = Quat::from_angles(0.0, 90.0, 0.0);
let mut quat2b :Quat= [0.0, 90.0, 0.0].into();
let mut quat3 = Quat::look_at(Vec3::X, Vec3::ZERO, None);
let vec4_w: Vec4 = (quat2 - quat3).into();

// quat2 == quat3 but because of epsilon here is the demo:
assert_eq!(vec4_w.w,            1.0);
assert_eq!(vec4_w.length_sq(),  1.0);
assert_eq!(quat2b,              quat2);

assert_eq!(quat1,               Quat::IDENTITY);
assert_eq!(*quat1.normalize(),  Quat::IDENTITY);
assert_eq!(*quat1.invert(),     Quat::IDENTITY);

Fields

x: f32

y: f32

z: f32

w: f32

Implementations

impl Quat

pub const IDENTITY: Self

This is the ‘multiply by one!’ of the quaternion rotation world. It’s basically a default, no rotation quaternion. https://stereokit.net/Pages/StereoKit/Quat/Identity.html

pub const Y_180: Self

This is a quaternion that represents a 180 degree rotation around the Y axis. It’s useful for representing a 180 degree turn in a 3D space, such as when you want to face the opposite direction.

pub const ZERO: Self

ZERO may be found when testing some crate::system::Input, crate::system::Pointer or crate::system::Controller

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

You may want to use static creation methods, like Quat::look_at, or Quat::IDENTITY instead of this one! Unless you know what you’re doing. https://stereokit.net/Pages/StereoKit/Quat/Quat.html

pub fn invert(&mut self) -> &mut Self

Makes this Quat the reverse rotation! If this quat goes from A to B, the inverse will go from B to A. Costly, see get_inverse for a faster way to get this. https://stereokit.net/Pages/StereoKit/Quat/Invert.html

see also Quat::get_inverse quat_inverse

Examples

use stereokit_rust::maths::Quat;

let mut q = Quat::new(1.0, 2.0, 3.0, 4.0);
q.invert();
assert_eq!(q, Quat { x: -0.033333335, y: -0.06666667, z: -0.1, w: 0.13333334 });

pub fn conjugate(&self) -> Self

Return the conjugate

Examples

use stereokit_rust::maths::Quat;

let mut q = Quat::new(1.0, 2.0, 3.0, 4.0);
let q2 = q.conjugate();
assert_eq!(q2, Quat { x: -1.0, y: -2.0, z: -3.0, w: 4.0 });

pub fn normalize(&mut self) -> &mut Self

Normalize this quaternion with the same orientation, and a length of 1. Costly, see get_normalized for a faster way to get this. https://stereokit.net/Pages/StereoKit/Quat/Normalize.html

see also Quat::get_normalized quat_normalize

Examples

use stereokit_rust::maths::Quat;

let mut q = Quat::new(1.0, 2.0, 3.0, 4.0);
q.normalize();
assert_eq!(q, Quat::new(0.18257419, 0.36514837, 0.54772256, 0.73029674));

pub fn relative(&mut self, to: Self) -> &mut Self

Rotates a quaternion making it relative to another rotation while preserving it’s “Length”! https://stereokit.net/Pages/StereoKit/Quat/Relative.html

• to - The relative quaternion.

Returns this quaternion made relative to another rotation. see also quat_mul

Examples

use stereokit_rust::maths::Quat;

let mut q = Quat::from_angles(0.0, 90.0, 0.0);
assert_eq!(q, Quat { x: 0.0, y: 0.70710677, z: 0.0, w: 0.7071067 });

let to = Quat::from_angles(0.0, 0.0, 90.0);
q.relative(to);
assert_eq!(q, Quat { x: 0.70710677, y: 0.0, z: 0.0, w: 0.7071067 });

pub fn rotate_point(&self, point: Vec3) -> Vec3

This rotates a point around the origin by the Quat. https://stereokit.net/Pages/StereoKit/Quat/Rotate.html

• point - The point to rotate around the origin.

Returns the rotated point. see also quat_mul_vec

Examples

use stereokit_rust::maths::{Vec3, Quat};

let q = Quat::from_angles(0.0, 90.0, 0.0);
let point = Vec3::new(1.0, 0.0, 0.0);
let rotated_point = q.rotate_point(point);
assert_eq!(rotated_point, Vec3::new(0.0, 0.0, -1.0));

pub fn to_angles_degrees(&self) -> [f32; 3]

Get an array of the 3 angles in degrees of this Quat with x, y and z axis https://stereokit.net/Pages/StereoKit/Quat.html

see also quat_to_axis_angle

Examples

use stereokit_rust::maths::{Quat, Vec3};

let quat = Quat::from_angles(90.0, 180.0, -180.0);

let angles: Vec3  = quat.to_angles_degrees().into();
assert_eq!(angles, [-270.0, 0.0, 0.0].into());

pub fn to_angles(&self) -> [f32; 3]

Get an array of the 3 angles in radians of this Quat with x, y and z axis https://stereokit.net/Pages/StereoKit/Quat.html

Examples

use stereokit_rust::maths::{Quat, Vec3};

let quat = Quat::from_angles(90.0, 0.0, 0.0);
let angles = quat.to_angles();
assert_eq!(angles, [1.5707964, 0.0, 0.0]);

pub fn rotate(a: Quat, point: Vec3) -> Vec3

This rotates a point around the origin by the Quat. https://stereokit.net/Pages/StereoKit/Quat/Rotate.html

• a - The Quat to use for rotation.
• point - The point to rotate around the origin.

Returns the rotated point. see also quat_mul_vec operator ‘*’ Quat::rotate_point

Examples

use stereokit_rust::maths::{Vec3, Quat};

let a = Quat::from_angles(0.0, 90.0, 0.0);
let point = Vec3::new(1.0, 0.0, 0.0);
let result1 = a * point;
let result2 = Quat::rotate(a, point);
let result3 = a.rotate_point(point);
assert_eq!(result1, result2);
assert_eq!(result2, result3);
assert_eq!(result1, Vec3::new(0.0, 0.0, -1.0));

pub fn delta(from: Self, to: Self) -> Self

Creates a quaternion that goes from one rotation to another. https://stereokit.net/Pages/StereoKit/Quat/Delta.html

• from - The origin rotation.
• to - The target rotation.

Returns the quaternion between from and to. see also - operator quat_difference

Examples

use stereokit_rust::maths::Quat;

let from = Quat::from_angles(180.0, 0.0, 0.0);
let to = Quat::from_angles(0.0, 180.0, 0.0);
let delta = Quat::delta(from, to);
assert_eq!(delta, Quat::from_angles(0.0, 0.0, 180.0));

let delta_b = from - to;
assert_eq!(delta_b, delta);

pub fn delta_dir(from: Vec3, to: Vec3) -> Self

Creates a rotation that goes from one direction to another. Which is comes in handy when trying to roll something around with position data. https://stereokit.net/Pages/StereoKit/Quat/Delta.html

• from - The origin direction.
• to - The target direction.

Returns the quaternion between the two directions.

Examples

use stereokit_rust::maths::{Quat, Vec3};

let from = Vec3::new(1.0, 0.0, 0.0);
let to = Vec3::new(0.0, 0.0, 1.0);
let delta = Quat::delta_dir(from, to);
assert_eq!(delta, Quat::from_angles(0.0, -90.0, 0.0));

pub fn from_angles(pitch_x_deg: f32, yaw_y_deg: f32, roll_z_deg: f32) -> Self

Creates a Roll/Pitch/Yaw rotation (applied in that order) from the provided angles in degrees! There is also a From<[f32; 3]> for Quat implementation that does the same thing. https://stereokit.net/Pages/StereoKit/Quat/FromAngles.html

• pitch_x_deg - The angle to rotate around the X-axis in degrees.
• yaw_y_deg - The angle to rotate around the Y-axis in degrees.
• roll_z_deg - The angle to rotate around the Z-axis in degrees.

Returns a quaternion representing the given Roll/Pitch/Yaw rotation! see also quat_from_angles Quat::from

Examples

use stereokit_rust::maths::Quat;

let quat = Quat::from_angles(45.0, 30.0, 60.0);
let quat2: Quat = [45.0, 30.0, 60.0].into();
assert_eq!(quat, quat2);

let quat = Quat::from_angles(0.0, 180.0, 0.0);
let quat2: Quat = Quat::Y_180;
assert_eq!(quat, quat2);

pub fn look_at<V: Into<Vec3>>(from: V, at: V, up: Option<Vec3>) -> Self

Creates a rotation that describes looking from a point, to another point! This is a great function for camera style rotation, or other facing behavior when you know where an object is, and where you want it to look at. This rotation works best when applied to objects that face Vec3.Forward in their resting/model space pose. https://stereokit.net/Pages/StereoKit/Quat/LookAt.html

• from - Position of where the ‘object’ is.
• at - The position you want the ‘object’ to look at.
• up - Look From/At positions describe X and Y axis rotation well, but leave Z Axis/Roll undefined. Providing an upDirection vector helps to indicate roll around the From/At line. If None : up direction will be (0,1,0), to prevent roll.

Returns a rotation that describes looking from a point, towards another point. see also quat_lookat quat_lookat_up

Examples

use stereokit_rust::maths::{Quat, Vec3};

let from = Vec3::new(1.0, 0.0, 0.0);
let at = Vec3::new(0.0, 0.0, 1.0);
let up = Vec3::new(0.0, 1.0, 0.0);
let quat = Quat::look_at(from, at, Some(up));
assert_eq!(quat, Quat::from_angles(0.0, 135.0, 0.0));

let quat = Quat::look_at(from, at, None);
assert_eq!(quat, Quat::from_angles(0.0, 135.0, 0.0));

pub fn look_dir<V: Into<Vec3>>(direction: V) -> Self

Creates a rotation that describes looking towards a direction. This is great for quickly describing facing behavior! This rotation works best when applied to objects that face Vec3.Forward in their resting/model space pose. https://stereokit.net/Pages/StereoKit/Quat/LookDir.html

• direction - The direction the rotation should be looking. Doesn’t need to be normalized.

Returns a rotation that describes looking towards a direction. see also quat_lookat

Examples

use stereokit_rust::maths::{Quat, Vec3};

let direction = Vec3::new(1.0, 0.0, 0.0);
let quat = Quat::look_dir(direction);
assert_eq!(quat, Quat::from_angles(0.0, 270.0, 0.0));

pub fn slerp(a: Self, b: Self, slerp: f32) -> Self

Spherical Linear interpolation. Interpolates between two quaternions! Both Quats should be normalized/unit quaternions, or you may get unexpected results. https://stereokit.net/Pages/StereoKit/Quat/Slerp.html

• a - Start quaternion, should be normalized/unit length.
• b - End quaternion, should be normalized/unit length.
• slerp - The interpolation amount! This’ll be a if 0, and b if 1. Unclamped.

Returns a blend between the two quaternions! see also quat_slerp

Examples

use stereokit_rust::maths::Quat;

let a = Quat::from_angles(0.0, 0.0, 0.0);
let b = Quat::from_angles(0.0, 0.0, 90.0);
let result = Quat::slerp(a, b, 0.25);
assert_eq!(result, Quat::from_angles(0.0, 0.0, 22.5));

pub fn get_inverse(&self) -> Self

The reverse rotation! If this quat goes from A to B, the inverse will go from B to A. https://stereokit.net/Pages/StereoKit/Quat/Inverse.html

see also quat_inverse

Examples

use stereokit_rust::maths::Quat;

let q = Quat::from_angles(90.0, 0.0, 0.0);
let q_inv = q.get_inverse();
assert_eq!(q_inv, Quat::from_angles(-90.0, 0.0, 0.0));

pub fn get_normalized(&self) -> Self

A normalized quaternion has the same orientation, and a length of 1. https://stereokit.net/Pages/StereoKit/Quat/Normalized.html

see also quat_normalize

Examples

use stereokit_rust::maths::Quat;

let q = Quat::new(2.0, 0.0, 0.0, 0.0);
let normalized = q.get_normalized();
assert_eq!(normalized, Quat::new(1.0, 0.0, 0.0, 0.0));
assert_eq!(normalized, Quat::from_angles(180.0, 0.0, 0.0));

pub fn get_as_vec4(&self) -> Vec4

A Vec4 and a Quat are only really different by name and purpose. So, if you need to do Quat math with your Vec4, or visa versa, who am I to judge? https://stereokit.net/Pages/StereoKit/Quat/Vec4.html

see also Quat::from

Examples

use stereokit_rust::maths::{Quat, Vec4};

let quat = Quat::new(1.0, 2.0, 3.0, 4.0);
let vec4 = Vec4::new(1.0, 2.0, 3.0, 4.0);
assert_eq!(vec4, quat.get_as_vec4());
assert_eq!(vec4, quat.into());
assert_eq!(quat, vec4.into());

pub fn mul(&self, rhs: Self) -> Self

This is the combination of rotations a and b. Note that order matters h https://stereokit.net/Pages/StereoKit/Quat/op_Multiply.html

see also * operator quat_mul

Examples

use stereokit_rust::maths::Quat;

let a = Quat::from_angles(180.0, 0.0, 0.0);
let b = Quat::from_angles(0.0, 180.0, 0.0);
let c = a * b;
let d = a.mul(b);
assert_eq!(c, Quat::from_angles(0.0, 0.0, -180.0));
assert_eq!(d, Quat::from_angles(0.0, 0.0, -180.0));

pub fn mul_vec3<V: Into<Vec3>>(&self, rhs: V) -> Vec3

This rotates a point around the origin by the Quat. https://stereokit.net/Pages/StereoKit/Quat/op_Multiply.html

see also * operator quat_mul_vec

Examples

use stereokit_rust::maths::{Quat, Vec3};

let q = Quat::from_angles(0.0, 90.0, 0.0);
let v = Vec3::new(1.0, 0.0, 0.0);
let result = q.mul_vec3(v);
assert_eq!(result, Vec3::new(0.0, 0.0, -1.0));

let result_b = q * v;
assert_eq!(result_b, result);

pub const fn to_array(&self) -> [f32; 4]

get an array

see also Quat::from

Examples

use stereokit_rust::maths::Quat;

let q = Quat::new(1.0, 2.0, 3.0, 4.0);
assert_eq!(q.to_array(), [1.0, 2.0, 3.0, 4.0]);

Trait Implementations

impl Clone for Quat

fn clone(&self) -> Quat

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Quat

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

Formats the value using the given formatter.

impl Default for Quat

fn default() -> Self

Returns the “default value” for a type.

impl Display for Quat

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

Mostly for debug purposes, this is a decent way to log or inspect the vector in debug mode. Looks like “[x, y, z, w]” https://stereokit.net/Pages/StereoKit/Quat/ToString.html

Examples

use stereokit_rust::maths::Quat;

let quat = Quat::new(1.0, 2.0, 3.3, 4.0);
assert_eq!(format!("{}", quat), "[x:1, y:2, z:3.3, w:4]");

impl From<[f32; 3]> for Quat

fn from(val: [f32; 3]) -> Self

Converts to this type from the input type.

impl From<Quat> for Quat

fn from(val: Quat) -> Self

Converts to this type from the input type.

impl From<Quat> for Quat

fn from(val: Quat) -> Self

Converts to this type from the input type.

impl From<Quat> for Vec4

fn from(val: Quat) -> Self

Converts to this type from the input type.

impl From<Quat> for Vec4

fn from(val: Quat) -> Self

Converts to this type from the input type.

impl From<Vec4> for Quat

fn from(val: Vec4) -> Self

Converts to this type from the input type.

impl From<Vec4> for Quat

fn from(val: Vec4) -> Self

Converts to this type from the input type.

impl Mul<Matrix> for Quat

Transform an orientation by the Matrix. https://stereokit.net/Pages/StereoKit/Matrix/op_Multiply.html

see also matrix_transform_quat

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

Examples

use stereokit_rust::maths::{Quat, Matrix};

let transform = Matrix::r([0.0, 90.0, 0.0]);
let rotation = Quat::from_angles(0.0, 0.0, 0.0);

let transformed_rotation = rotation * transform;
assert_eq!(transformed_rotation, Quat::from_angles(0.0, 90.0, 0.0));

type Output = Quat

The resulting type after applying the * operator.

impl Mul<Quat> for Matrix

Transform an orientation by the Matrix. https://stereokit.net/Pages/StereoKit/Matrix/op_Multiply.html

see also matrix_transform_quat

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

Examples

use stereokit_rust::maths::{Quat, Matrix};

let transform = Matrix::r([0.0, 90.0, 0.0]);
let rotation = Quat::from_angles(0.0, 0.0, 0.0);

let transformed_rotation = transform * rotation;
assert_eq!(transformed_rotation, Quat::from_angles(0.0, 90.0, 0.0));

type Output = Quat

The resulting type after applying the * operator.

impl Mul<Vec3> for Quat

This rotates a point around the origin by the Quat. https://stereokit.net/Pages/StereoKit/Quat/op_Multiply.html

see also quat_mul_vec

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

Examples

use stereokit_rust::maths::{Quat, Vec3};

let q = Quat::from_angles(0.0, 90.0, 0.0);
let v = Vec3::new(1.0, 0.0, 0.0);
assert_eq!(q * v, Vec3::new(0.0, 0.0, -1.0));

type Output = Vec3

The resulting type after applying the * operator.

impl Mul for Quat

This is the combination of rotations a and b. Note that order matters h https://stereokit.net/Pages/StereoKit/Quat/op_Multiply.html

see also quat_mul

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

Examples

use stereokit_rust::maths::Quat;

let a = Quat::from_angles(180.0, 0.0, 0.0);
let b = Quat::from_angles(0.0, 180.0, 0.0);
let c = Quat::from_angles(0.0, 0.0, -180.0);
assert_eq!(a * b, c);

type Output = Quat

The resulting type after applying the * operator.

impl MulAssign<Matrix> for Quat

Transform an orientation by the Matrix. https://stereokit.net/Pages/StereoKit/Matrix/op_Multiply.html

see also matrix_transform_quat

fn mul_assign(&mut self, rhs: Matrix)

Examples

use stereokit_rust::maths::{Quat, Matrix};

let mut rotation = Quat::from_angles(0.0, 0.0, 0.0);
let transform = Matrix::r([0.0, 90.0, 0.0]);

rotation *= transform;
assert_eq!(rotation, Quat::from_angles(0.0, 90.0, 0.0));

impl MulAssign for Quat

This is the combination of rotations a and b. Note that order matters h https://stereokit.net/Pages/StereoKit/Quat/op_Multiply.html

see also quat_mul

fn mul_assign(&mut self, rhs: Quat)

Examples

use stereokit_rust::maths::Quat;

let mut q = Quat::new(1.0, 0.0, 0.0, 0.0);
let r = Quat::new(0.0, 1.0, 0.0, 0.0);
q *= r;
assert_eq!(q, Quat::new(0.0, 0.0, -1.0, 0.0));

impl PartialEq for Quat

Warning: Equality with a precision of 0.000001

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

Warning: Equality with a precision of 0.00001

Example

use stereokit_rust::maths::Quat;

let q0 = Quat::new(1.00002, 2.0, 3.0, 4.0);
let q1 = Quat::new(1.000001, 2.000001, 3.000001, 4.0);
let q2 = Quat::new(1.0, 2.0, 3.0, 4.0);
assert_ne!(q0, q1);
assert_eq!(q1, q2);

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 Quat

Gets a Quat representing the rotation from a to b. https://stereokit.net/Pages/StereoKit/Quat/op_Subtraction.html see also QuatT::delta()

see also quat_difference

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

Examples

use stereokit_rust::maths::Quat;

let from = Quat::from_angles(180.0, 0.0, 0.0);
let to = Quat::from_angles(0.0, 180.0, 0.0);
let delta = Quat::delta(from, to);
assert_eq!(delta, Quat::from_angles(0.0, 0.0, 180.0));
assert_eq!(from - to, delta);

type Output = Quat

The resulting type after applying the - operator.

impl Copy for Quat