Union Matrix

#[repr(C)]
pub union Matrix {
    pub row: [Vec4; 4],
    pub m: [f32; 16],
}

A Matrix in StereoKit is a 4x4 grid of numbers that is used to represent a transformation for any sort of position or vector! This is an oversimplification of what a matrix actually is, but it’s accurate in this case.

Matrices are really useful for transforms because you can chain together all sorts of transforms into a single Matrix! A Matrix transform really shines when applied to many positions, as the more expensive operations get cached within the matrix values.

Multiple matrix transforms can be combined by multiplying them. In StereoKit, to create a matrix that first scales an object, followed by rotating it, and finally translating it you would use this order: Matrix M = Matrix.S(…) * Matrix.R(…) * Matrix.T(…);

This order is related to the fact that StereoKit uses row-major order to store matrices. Note that in other 3D frameworks and certain 3D math references you may find column-major matrices, which would need the reverse order (i.e. TRS), so please keep this in mind when creating transformations.

Matrices are prominently used within shaders for mesh transforms! https://stereokit.net/Pages/StereoKit/Matrix.html

see also glam::Mat4

Examples

use stereokit_rust::{maths::{Vec3, Quat, Matrix}, model::Model};

let model = Model::from_file("center.glb", None).unwrap().copy();
let transform = Matrix::t_r_s(Vec3::NEG_Y * 0.7, [0.0, 155.0, 10.0], Vec3::ONE * 0.3);

filename_scr = "screenshots/matrix.jpeg";
test_screenshot!( // !!!! Get a proper main loop !!!!
    model.draw(token, transform, None, None);
);

Fields

row: [Vec4; 4]

m: [f32; 16]

Implementations

impl Matrix

pub const IDENTITY: Matrix

Identity matrix made of [[Vec4::X, Vec4::Y, Vec4::Z, Vec4::W]]

pub const Y_180: Matrix

Identity matrix rotated 180 degrees around the Y axis made of [[Vec4::NEG_X, Vec4::Y, Vec4::NEG_Z, Vec4::W]] This is mainly used for test screenshots, but it can be useful for other things too!

pub const NULL: Matrix

Null or Zero matrix made of [[Vec4::ZERO, Vec4::ZERO, Vec4::ZERO, Vec4::ZERO]]

pub fn orthographic( width: f32, height: f32, near_clip: f32, far_clip: f32, ) -> Self

This creates a matrix used for projecting 3D geometry onto a 2D surface for rasterization. Orthographic projection matrices will preserve parallel lines. This is great for 2D scenes or content. https://stereokit.net/Pages/StereoKit/Matrix/Orthographic.html

• width - in meters, of the area that will be projected.
• height - The height, in meters, of the area that will be projected
• near_clip - Anything closer than this distance (in meters) will be discarded. Must not be zero, and if you make this too small, you may experience glitching in your depth buffer.
• far_clip - Anything further than this distance (in meters) will be discarded. For low resolution depth buffers, this should not be too far away, or you’ll see bad z-fighting artifacts.

Returns the final orthographic Matrix.

Examples

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

let translate = Matrix::orthographic(1.0, 1.0, 0.1, 100.0);
let point = Vec3::new(1.0, 2.0, 3.0);

let projection = translate * point;
assert_eq!(projection, Vec3 { x: 2.0, y: 4.0, z: -0.03103103 });

see also matrix_orthographic

pub fn perspective( fov_degrees: f32, aspect_ratio: f32, near_clip: f32, far_clip: f32, ) -> Self

This creates a matrix used for projecting 3D geometry onto a 2D surface for rasterization. Perspective projection matrices will cause parallel lines to converge at the horizon. This is great for normal looking content. https://stereokit.net/Pages/StereoKit/Matrix/Perspective.html

• fov_degrees - This is the vertical field of view of the perspective matrix, units are in degrees.
• aspect_ratio - The projection surface’s width/height.
• near_clip - Anything closer than this distance (in meters) will be discarded. Must not be zero, and if you make this too small, you may experience glitching in your depth buffer.
• far_clip - Anything further than this distance (in meters) will be discarded. For low resolution depth buffers, this should not be too far away, or you’ll see bad z-fighting artifacts.

Returns the final perspective matrix. see also matrix_perspective

Examples

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

let translate = Matrix::perspective(90.0, 1.0, 0.1, 100.0);
let point = Vec3::new(1.0, 2.0, 3.0);

let projection = translate * point;
assert_eq!(projection,  Vec3 { x: 72.946686, y: 145.89337, z: -3.1031032 });

pub fn perspective_focal( image_resolution: Vec2, focal_length_px: f32, near_clip: f32, far_clip: f32, ) -> Self

This creates a matrix used for projecting 3D geometry onto a 2D surface for rasterization. With the known camera intrinsics, you can replicate its perspective! https://stereokit.net/Pages/StereoKit/Matrix/Perspective.html

• image_resolution - The resolution of the image. This should be the image’s width and height in pixels.
• focal_length_px - The focal length of camera in pixels, with image coordinates +X (pointing right) and +Y (pointing up).
• near_clip - Anything closer than this distance (in meters) will be discarded. Must not be zero, and if you make this too small, you may experience glitching in your depth buffer.
• far_clip - Anything further than this distance (in meters) will be discarded. For low resolution depth buffers, this should not be too far away, or you’ll see bad z-fighting artifacts.

Returns the final perspective matrix. Remarks: Think of the optical axis as an imaginary line that passes through the camera lens. In front of the camera lens, there’s an image plane, perpendicular to the optical axis, where the image of the scene being captured is formed. Its distance is equal to the focal length of the camera from the center of the lens. Here, we find the ratio between the size of the image plane and distance from the camera in one unit distance and multiply it by the near clip distance to find a near plane that is parallel.

see also matrix_perspective

Examples

use stereokit_rust::maths::{Vec2, Vec3, Matrix};

let translate = Matrix::perspective_focal(Vec2::new(1.0, 1.0), 1.0, 0.1, 100.0);
let point = Vec3::new(1.0, 2.0, 3.0);

let projection = translate * point;
assert_eq!(projection,  Vec3 { x: 2.0, y: 4.0, z: -3.1031032 });

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

A transformation that describes one position looking at another point. This is particularly useful for describing camera transforms! https://stereokit.net/Pages/StereoKit/Matrix/LookAt.html

see also matrix_r

Examples

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

let from = Vec3::new(1.0, 0.0, 0.0);
let at = Vec3::new(0.0, 0.0, 0.0);
let up = Vec3::new(0.0, 1.0, 0.0);
let transform = Matrix::look_at(from, at, Some(up));
assert_eq!(transform, Matrix::from([
    0.0, 0.0, 1.0, 0.0,
    0.0, 1.0, 0.0, 0.0,
    1.0, 0.0, 0.0, 0.0,
    0.0, 0.0,-1.0, 1.0,
]));

let transform_b = Matrix::look_at(from, at, None);
assert_eq!(transform, transform_b);

pub fn r<Q: Into<Quat>>(rotation: Q) -> Self

Create a rotation matrix from a Quaternion. Consider using Matrix::update_r when you have to recalculate Matrix at each steps in main loop. https://stereokit.net/Pages/StereoKit/Matrix/R.html

• rotation - The quaternion describing the rotation for this transform.

returns a Matrix that will rotate by the provided Quaternion orientation. see also matrix_r Matrix::update_r

Examples

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

let rotation = Quat::from_angles(90.0, 0.0, 0.0);
let matrix = Matrix::r(rotation);
assert_eq!(matrix, Matrix::from([
    1.0, 0.0, 0.0, 0.0,
    0.0, 0.0, 1.0, 0.0,
    0.0,-1.0, 0.0, 0.0,
    0.0, 0.0, 0.0, 1.0,
]));

let rotation = Quat::from_angles(0.0, 90.0, 0.0);
let matrix = Matrix::r(rotation);
assert_eq!(matrix, Matrix::from([
    0.0, 0.0, -1.0, 0.0,
    0.0, 1.0,  0.0, 0.0,
    1.0, 0.0,  0.0, 0.0,
    0.0, 0.0,  0.0, 1.0,
]));

pub fn update_r(&mut self, rotation: &Quat)

Create a rotation matrix from a Quaternion. https://stereokit.net/Pages/StereoKit/Matrix/R.html

• rotation - The quaternion describing the rotation for this transform.

see also matrix_trs_out Matrix::r

Examples

use stereokit_rust::{maths::{Vec3, Quat, Matrix}, mesh::Mesh, material::Material,
                     util::Time};

let mesh = Mesh::cube();
let material = Material::pbr();

let mut transform = Matrix::IDENTITY;
let mut delta_rotate = 90.0;

test_steps!( // !!!! Get a proper main loop !!!!
    delta_rotate = (delta_rotate + 10.0  * Time::get_stepf()) % 360.0;
    let rotation = Quat::from_angles(0.0, delta_rotate, 0.0);

    transform.update_r(&rotation);

    mesh.draw(token, &material, transform, None, None);
    assert_eq!(transform, Matrix::r(rotation));
);

pub fn s<V: Into<Vec3>>(scale: V) -> Self

Creates a scaling Matrix, where scale can be different on each axis (non-uniform).Consider using Matrix::update_s when you have to recalculate Matrix at each steps in main loop. https://stereokit.net/Pages/StereoKit/Matrix/S.html

• scale - How much larger or smaller this transform makes things. Vec3::ONE is the default.

Returns a non-uniform scaling matrix. see also matrix_s Matrix::update_s

Examples

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

let scale = Matrix::s(Vec3::new(2.0, 3.0, 4.0));
let point = Vec3::new(1.0, 1.0, 1.0);
let scaled_point = scale * point;
assert_eq!(scaled_point, Vec3::new(2.0, 3.0, 4.0));

pub fn update_s(&mut self, scale: &Vec3)

Creates a scaling Matrix, where scale can be different on each axis (non-uniform). https://stereokit.net/Pages/StereoKit/Matrix/S.html

• scale - How much larger or smaller this transform makes things. Vec3::ONE is the default.

see also matrix_trs_out Matrix::s

Examples

use stereokit_rust::{maths::{Vec3, Quat, Matrix}, mesh::Mesh, material::Material,
                     util::Time};

let mesh = Mesh::cube();
let material = Material::pbr();

let mut transform = Matrix::IDENTITY;
let mut delta_scale = 2.0;

test_steps!( // !!!! Get a proper main loop !!!!
    let scale = Vec3::ONE * (delta_scale * Time::get_stepf()).cos();

    transform.update_s(&scale);

    mesh.draw(token, &material, transform, None, None);
    assert_eq!(transform, Matrix::s(scale));
);

pub fn t<V: Into<Vec3>>(translation: V) -> Self

Translate. Creates a translation Matrix! Consider using Matrix::update_t when you have to recalculate Matrix at each steps in main loop. https://stereokit.net/Pages/StereoKit/Matrix/T.html

• translation - Move an object by this amount.

Returns a Matrix containing a simple translation! see also matrix_t Matrix::update_t

Examples

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

let translation = Matrix::t(Vec3::new(1.0, 2.0, 3.0));
let point = Vec3::new(0.0, 0.0, 0.0);
let translated_point = translation * point;
assert_eq!(translated_point, Vec3::new(1.0, 2.0, 3.0));

pub fn update_t(&mut self, translation: &Vec3)

Translate. Creates a translation Matrix! https://stereokit.net/Pages/StereoKit/Matrix/T.html

• translation - Move an object by this amount.

see also matrix_trs_out Matrix::t

Examples

use stereokit_rust::{maths::{Vec3, Quat, Matrix}, mesh::Mesh, material::Material,
                     util::Time};

let mesh = Mesh::cube();
let material = Material::pbr();

let mut transform = Matrix::IDENTITY;
let mut position = Vec3::ZERO;

test_steps!( // !!!! Get a proper main loop !!!!
    position += Vec3::NEG_Z * Time::get_stepf();

    transform.update_t(&position);

    mesh.draw(token, &material, transform, None, None);
    assert_eq!(transform, Matrix::t(position));
);

pub fn tr(translation: &Vec3, rotation: &Quat) -> Self

👎Deprecated since 0.40.0: please use Matrix::t_r or Matrix::update_t_r

Translate, Rotate. Creates a transform Matrix using these components! https://stereokit.net/Pages/StereoKit/Matrix/TR.html

• translation - Move an object by this amount.
• rotation - The quaternion describing the rotation for this transform.

Returns a Matrix that combines translation and rotation information into a single Matrix! see also matrix_trs

pub fn t_r<V: Into<Vec3>, Q: Into<Quat>>(translation: V, rotation: Q) -> Self

Translate, Rotate. Creates a transform Matrix using these components! Consider using Matrix::update_t_r when you have to recalculate Matrix at each steps in main loop. https://stereokit.net/Pages/StereoKit/Matrix/TR.html

• translation - Move an object by this amount.
• rotation - The quaternion describing the rotation for this transform.

Returns a Matrix that combines translation and rotation information into a single Matrix! see also matrix_trs Matrix::update_t_r

Examples

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

let transform = Matrix::t_r([1.0, 2.0, 3.0], [0.0, 180.0, 0.0]);
let point = Vec3::new(1.0, 1.0, 1.0);
let transformed_point = transform * point;
assert_eq!(transformed_point, Vec3::new(0.0, 3.0, 2.0));

pub fn update_t_r(&mut self, translation: &Vec3, rotation: &Quat)

Translate, Rotate. Creates a transform Matrix using these components! https://stereokit.net/Pages/StereoKit/Matrix/TR.html

• translation - Move an object by this amount.
• rotation - The quaternion describing the rotation for this transform.

see also matrix_trs_out Matrix::t_r

Examples

use stereokit_rust::{maths::{Vec3, Quat, Matrix}, mesh::Mesh, material::Material,
                     util::Time};

let mesh = Mesh::cube();
let material = Material::pbr();

let mut transform = Matrix::IDENTITY;
let mut position = Vec3::ZERO;
let mut delta_rotate = 90.0;

test_steps!( // !!!! Get a proper main loop !!!!
    position += Vec3::NEG_Z * Time::get_stepf();
    delta_rotate = (delta_rotate + 10.0  * Time::get_stepf()) % 360.0;
    let rotation = Quat::from_angles(0.0, delta_rotate, 0.0);

    transform.update_t_r(&position, &rotation);

    mesh.draw(token, &material, transform, None, None);
    assert_eq!(transform, Matrix::t_r(position, rotation));
);

pub fn ts<V: Into<Vec3>>(translation: V, scale: V) -> Self

👎Deprecated since 0.40.0: please use Matrix::t_s or Matrix::update_t_s

Translate, Scale. Creates a transform Matrix using these components! https://stereokit.net/Pages/StereoKit/Matrix/TS.html

• translation - Move an object by this amount.
• scale - How much larger or smaller this transform makes things. Vec3::ONE is the default.

Returns a Matrix that combines translation and rotation information into a single Matrix! see also matrix_ts

pub fn t_s<V: Into<Vec3>>(translation: V, scale: V) -> Self

Translate, Scale. Creates a transform Matrix using these components! Consider using Matrix::update_t_s when you have to recalculate Matrix at each steps in main loop. https://stereokit.net/Pages/StereoKit/Matrix/TS.html

• translation - Move an object by this amount.
• scale - How much larger or smaller this transform makes things. Vec3::ONE is the default.

Returns a Matrix that combines translation and rotation information into a single Matrix! see also matrix_ts Matrix::update_t_s

Examples

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

let transform = Matrix::t_s([1.0, 2.0, 3.0], [2.0, 2.0, 2.0]);
let point = Vec3::new(1.0, 1.0, 1.0);
let transformed_point = transform * point;
assert_eq!(transformed_point, Vec3::new(3.0, 4.0, 5.0));

pub fn update_t_s(&mut self, translation: &Vec3, scale: &Vec3)

Translate, Scale. Creates a transform Matrix using these components! https://stereokit.net/Pages/StereoKit/Matrix/TS.html

• translation - Move an object by this amount.
• scale - How much larger or smaller this transform makes things. Vec3::ONE is the default.

Returns a Matrix that combines translation and rotation information into a single Matrix! see also matrix_trs_out Matrix::t_s

Examples

use stereokit_rust::{maths::{Vec3, Quat, Matrix}, mesh::Mesh, material::Material,
                     util::Time};

let mesh = Mesh::cube();
let material = Material::pbr();

let mut transform = Matrix::IDENTITY;
let mut position = Vec3::ZERO;
let mut delta_scale = 2.0;

test_steps!( // !!!! Get a proper main loop !!!!
    position += Vec3::NEG_Z * Time::get_stepf();
    let scale = Vec3::ONE * (delta_scale * Time::get_stepf()).cos();

    transform.update_t_s(&position, &scale);

    mesh.draw(token, &material, transform, None, None);
    assert_eq!(transform, Matrix::t_s(position, scale));
);

pub fn trs(translation: &Vec3, rotation: &Quat, scale: &Vec3) -> Self

👎Deprecated since 0.40.0: please use Matrix::t_r_s or Matrix::update_t_r_s

Translate, Rotate, Scale. Creates a transform Matrix using all these components! https://stereokit.net/Pages/StereoKit/Matrix/TRS.html

• translation - Move an object by this amount.
• rotation - The quaternion describing the rotation for this transform.
• scale - How much larger or smaller this transform makes things. Vec3::ONE is a good default.

Returns a Matrix that combines translation, rotation and scale information into a single Matrix! see also matrix_trs

pub fn t_r_s<V: Into<Vec3>, Q: Into<Quat>>( translation: V, rotation: Q, scale: V, ) -> Self

Translate, Rotate, Scale. Creates a transform Matrix using all these components! Consider using Matrix::update_t_r_s when you have to recalculate Matrix at each steps in main loop. https://stereokit.net/Pages/StereoKit/Matrix/TRS.html

• translation - Move an object by this amount.
• rotation - The quaternion describing the rotation for this transform.
• scale - How much larger or smaller this transform makes things. Vec3::ONE is a good default.

Returns a Matrix that combines translation, rotation and scale information into a single Matrix! see also matrix_trs Matrix::update_t_r_s

Examples

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

let transform = Matrix::t_r_s([1.0, 2.0, 3.0], [0.0, 180.0, 0.0], [2.0, 2.0, 2.0]);
let point = Vec3::new(1.0, 1.0, 1.0);
let transformed_point = transform * point;
assert_eq!(transformed_point, Vec3::new(-1.0, 4.0, 1.0));

pub fn update_t_r_s( &mut self, translation: &Vec3, rotation: &Quat, scale: &Vec3, )

Translate, Rotate, Scale. Creates a transform Matrix using all these components! https://stereokit.net/Pages/StereoKit/Matrix/TRS.html

• translation - Move an object by this amount.
• rotation - The quaternion describing the rotation for this transform.
• scale - How much larger or smaller this transform makes things. Vec3::ONE is a good default.

Returns a Matrix that combines translation, rotation and scale information into a single Matrix! see also matrix_trs_out Matrix::t_r_s

Examples

use stereokit_rust::{maths::{Vec3, Quat, Matrix}, mesh::Mesh, material::Material,
                     util::Time};

let mesh = Mesh::cube();
let material = Material::pbr();

let mut transform = Matrix::IDENTITY;
let mut position = Vec3::ZERO;
let mut delta_scale = 2.0;
let mut delta_rotate = 90.0;

test_steps!( // !!!! Get a proper main loop !!!!
    position += Vec3::NEG_Z * Time::get_stepf();
    delta_rotate = (delta_rotate + 10.0  * Time::get_stepf()) % 360.0;
    let rotation = Quat::from_angles(0.0, delta_rotate, 0.0);
    let scale = Vec3::ONE * (delta_scale * Time::get_stepf()).cos();

    transform.update_t_r_s(&position, &rotation, &scale);

    mesh.draw(token, &material, transform, None, None);
    assert_eq!(transform, Matrix::t_r_s(position, rotation, scale));
);

pub fn trs_to_pointer( translation: &Vec3, rotation: &Quat, scale: &Vec3, out_result: *mut Matrix, )

👎Deprecated since 0.40.0: please use Matrix::update_t_r, Matrix::update_t_s or Matrix::update_t_r_s

Translate, Rotate, Scale. Update a transform Matrix using all these components! https://stereokit.net/Pages/StereoKit/Matrix/TRS.html

• translation - Move an object by this amount.
• rotation - The quaternion describing the rotation for this transform.
• scale - How much larger or smaller this transform makes things. Vec3::ONE is a good default.

see also matrix_trs_out

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

Inverts this Matrix! If the matrix takes a point from a -> b, then its inverse takes the point from b -> a. The Matrix is modified so use get_inverse* for performance gains https://stereokit.net/Pages/StereoKit/Matrix/Invert.html

see also Matrix::get_inverse matrix_invert

Examples

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

let mut transform = Matrix::t([1.0, 2.0, 3.0]);
transform.invert();
let point = Vec3::new(1.0, 2.0, 3.0);
let transformed_point = transform * point;
assert_eq!(transformed_point, Vec3::new(0.0, 0.0, 0.0));

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

Transposes this Matrix! Transposing is like rotating the matrix 90 clockwise, or turning the rows into columns. This can be useful for inverting orthogonal matrices, or converting matrices for use in a math library that uses different conventions! The Matrix is modified so use get_transposed* for performance gains https://stereokit.net/Pages/StereoKit/Matrix/Transpose.html

see also matrix_transpose

Examples

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

let mut transform = Matrix::t([1.0, 2.0, 3.0]);
assert_eq!(transform, Matrix::from([
    1.0, 0.0, 0.0, 0.0,
    0.0, 1.0, 0.0, 0.0,
    0.0, 0.0, 1.0, 0.0,
    1.0, 2.0, 3.0, 1.0,
]));

transform.transpose();
assert_eq!(transform, Matrix::from([
    1.0, 0.0, 0.0, 1.0,
    0.0, 1.0, 0.0, 2.0,
    0.0, 0.0, 1.0, 3.0,
    0.0, 0.0, 0.0, 1.0,
]));

pub fn decompose(&self) -> Option<(Vec3, Vec3, Quat)>

Returns this transformation matrix to its original translation, rotation and scale components. Not exactly a cheap function. If this is not a transform matrix, there’s a chance this call will fail, and return false. https://stereokit.net/Pages/StereoKit/Matrix/Decompose.html Returns the tuple (position:Vec3, scale:Vec3, orientation:QuatT)

see also matrix_decompose Matrix::decompose_to_ptr

Examples

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

let position = Vec3::new(1.0, 2.0, 3.0);
let orientation = Quat::from_angles(0.0, 90.0, 0.0);
let scale = Vec3::new(2.0, 2.0, 2.0);
let matrix = Matrix::t_r_s(position, orientation, scale);

let (pos, sca, ori) = matrix.decompose().unwrap();
assert_eq!(pos, position);
assert_eq!(sca, scale);
assert_eq!(ori, orientation);

pub fn decompose_to_ptr( &self, out_position: &mut Vec3, out_orientation: &mut Quat, out_scale: &mut Vec3, ) -> bool

Returns this transformation matrix to its original translation, rotation and scale components. Not exactly a cheap function. If this is not a transform matrix, there’s a chance this call will fail, and return false. https://stereokit.net/Pages/StereoKit/Matrix/Decompose.html

• out_position - The translation component of the matrix.
• out_orientation - The rotation component of the matrix, some lossiness may be encountered when composing/decomposing.
• out_scale - The scale component of the matrix.

see also matrix_decompose

Examples

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

let position = Vec3::new(1.0, 2.0, 3.0);
let orientation = Quat::from_angles(0.0, 90.0, 0.0);
let scale = Vec3::new(2.0, 2.0, 2.0);
let matrix = Matrix::t_r_s(position, orientation, scale);

let mut pos = Vec3::ZERO;
let mut sca = Vec3::ZERO;
let mut ori = Quat::ZERO;

matrix.decompose_to_ptr(&mut pos, &mut ori, &mut sca);
assert_eq!(pos, position);
assert_eq!(sca, scale);
assert_eq!(ori, orientation);

pub fn transform_point<V: Into<Vec3>>(&self, point: V) -> Vec3

Transforms a point through the Matrix! This is basically just multiplying a vector (x,y,z,1) with the Matrix. https://stereokit.net/Pages/StereoKit/Matrix/Transform.html

• point - The point to transform.

Returns the point transformed by the Matrix. see also the ‘*’ operator matrix_transform_pt

Examples

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

let transform = Matrix::t([1.0, 2.0, 3.0]);
let point = Vec3::new(1.0, 1.0, 1.0);
let transformed_point = transform.transform_point(point);
assert_eq!(transformed_point, Vec3::new(2.0, 3.0, 4.0));

let transformed_point_b = transform * point;
assert_eq!(transformed_point_b, transformed_point);

pub fn transform_ray<R: Into<Ray>>(&self, ray: R) -> Ray

Shorthand to transform a ray though the Matrix! This properly transforms the position with the point transform method, and the direction with the direction transform method. Does not normalize, nor does it preserve a normalized direction if the Matrix contains scale data. https://stereokit.net/Pages/StereoKit/Matrix/Transform.html

• ray - A ray you wish to transform from one space to another.

Returns the Ray transformed by the Matrix. see also the * operator matrix_transform_ray

Examples

use stereokit_rust::maths::{Vec3, Matrix, Ray};

let transform = Matrix::t([1.0, 2.0, 3.0]);
let ray = Ray::new([0.0, 0.0, 0.0], [1.0, 0.0, 0.0]);
let transformed_ray = transform.transform_ray(ray);
assert_eq!(transformed_ray, Ray::new([1.0, 2.0, 3.0], [1.0, 0.0, 0.0]));

let transformed_ray_b = transform * ray;
assert_eq!(transformed_ray_b, transformed_ray);

pub fn transform_pose<P: Into<Pose>>(&self, pose: P) -> Pose

Shorthand for transforming a Pose! This will transform the position of the Pose with the matrix, extract a rotation Quat from the matrix and apply that to the Pose’s orientation. Note that extracting a rotation Quat is an expensive operation, so if you’re doing it more than once, you should cache the rotation Quat and do this transform manually. https://stereokit.net/Pages/StereoKit/Matrix/Transform.html

• pose - The original pose.

Returns the transformed pose. see also the * operator matrix_transform_pose

Examples

use stereokit_rust::maths::{Pose, Vec3, Matrix};

let transform = Matrix::t([1.0, 2.0, 3.0]);
let pose = Pose::new([0.0, 0.0, 0.0], None);
let transformed_pose = transform.transform_pose(pose);
assert_eq!(transformed_pose, Pose::new([1.0, 2.0, 3.0], None));

let transformed_pose_b = transform * pose;
assert_eq!(transformed_pose_b, transformed_pose);

pub fn transform_quat<Q: Into<Quat>>(&self, rotation: Q) -> Quat

Shorthand for transforming a rotation! This will extract a rotation Quat from the matrix and apply that to the QuatT’s orientation. Note that extracting a rotation Quat is an expensive operation, so if you’re doing it more than once, you should cache the rotation Quat and do this transform manually. https://stereokit.net/Pages/StereoKit/Matrix/Transform.html

• rotation - The original rotation

Return the transformed quat. see also the * operator matrix_transform_quat

Examples

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

let transform = Matrix::r([0.0, 90.0, 0.0]);
let rotation = Quat::from_angles(0.0, 90.0, 0.0);
let transformed_rotation = transform.transform_quat(rotation);
assert_eq!(transformed_rotation, Quat::from_angles(0.0, 180.0, 0.0));

let transformed_rotation_b = transform * rotation;
assert_eq!(transformed_rotation_b, transformed_rotation);

pub fn transform_normal<V: Into<Vec3>>(&self, normal: V) -> Vec3

Transforms a point through the Matrix, but excluding translation! This is great for transforming vectors that are -directions- rather than points in space. Use this to transform normals and directions. The same as multiplying (x,y,z,0) with the Matrix. Do not correspond to * operator ! https://stereokit.net/Pages/StereoKit/Matrix/TransformNormal.html

• normal - A direction vector to be transformed.

Returns the direction transformed by the Matrix. see also matrix_transform_dir

Examples

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

let transform = Matrix::r([0.0, 90.0, 0.0]);
let normal = Vec3::new(1.0, 0.0, 0.0);
let transformed_normal = transform.transform_normal(normal);
assert_eq!(transformed_normal, Vec3::new(0.0, 0.0, -1.0));

pub fn get_inverse(&self) -> Self

Creates an inverse matrix! If the matrix takes a point from a -> b, then its inverse takes the point from b -> a. https://stereokit.net/Pages/StereoKit/Matrix/Inverse.html

see also matrix_inverse

Examples

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

let transform = Matrix::t([1.0, 2.0, 3.0]);
let inverse = transform.get_inverse();
let point = Vec3::new(1.0, 2.0, 3.0);
let transformed_point = inverse * point;
assert_eq!(transformed_point, Vec3::new(0.0, 0.0, 0.0));

pub fn get_inverse_to_ptr(&self, out: &mut Matrix)

Creates an inverse matrix! If the matrix takes a point from a -> b, then its inverse takes the point from b -> a. https://stereokit.net/Pages/StereoKit/Matrix/Inverse.html

• out - The output matrix.

see also matrix_inverse

Examples

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

let transform = Matrix::t([1.0, 2.0, 3.0]);
let mut inverse = Matrix::NULL;

transform.get_inverse_to_ptr(&mut inverse);
let point = Vec3::new(1.0, 2.0, 3.0);
let transformed_point = inverse * point;
assert_eq!(transformed_point, Vec3::new(0.0, 0.0, 0.0));

pub fn get_pose(&self) -> Pose

Extracts translation and rotation information from the transform matrix, and makes a Pose from it! Not exactly fast. This is backed by Decompose, so if you need any additional info, it’s better to just call Decompose instead. https://stereokit.net/Pages/StereoKit/Matrix/Pose.html

see also matrix_extract_pose

Examples

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

let matrix = Matrix::t_r(Vec3::new(1.0, 2.0, 3.0), [0.0, 0.0, 0.0]);

let pose = matrix.get_pose();
assert_eq!(pose.position, Vec3::new(1.0, 2.0, 3.0));
assert_eq!(pose.orientation, Quat::IDENTITY)

pub fn get_rotation(&self) -> Quat

A slow function that returns the rotation quaternion embedded in this transform matrix. This is backed by Decompose, so if you need any additional info, it’s better to just call Decompose instead. https://stereokit.net/Pages/StereoKit/Matrix/Rotation.html

see also matrix_extract_rotation

Examples

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

let matrix = Matrix::t_r(Vec3::new(1.0, 2.0, 3.0), [0.0, 90.0, 0.0]);

let rotation = matrix.get_rotation();
assert_eq!(rotation, Quat::from_angles(0.0, 90.0, 0.0))

pub fn get_scale(&self) -> Vec3

Returns the scale embedded in this transform matrix. Not exactly cheap, requires 3 sqrt calls, but is cheaper than calling Decompose. https://stereokit.net/Pages/StereoKit/Matrix/Scale.html

see also matrix_extract_scale

Examples

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

let matrix = Matrix::t_s(Vec3::new(1.0, 2.0, 3.0), Vec3::new(2.0, 2.0, 2.0));

let scale = matrix.get_scale();
assert_eq!(scale, Vec3::new(2.0, 2.0, 2.0))

pub fn get_translation(&self) -> Vec3

A fast getter that will return or set the translation component embedded in this transform matrix. https://stereokit.net/Pages/StereoKit/Matrix/Translation.html

see also matrix_extract_translation

Examples

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

let transform = Matrix::r([0.0, 90.0, 0.0]);
let normal = Vec3::new(1.0, 0.0, 0.0);

let transformed_normal = transform.transform_normal(normal);
assert_eq!(transformed_normal, Vec3::new(0.0, 0.0, -1.0));

pub fn get_transposed(&self) -> Self

Creates a matrix that has been transposed! Transposing is like rotating the matrix 90 clockwise, or turning the rows into columns. This can be useful for inverting orthogonal matrices, or converting matrices for use in a math library that uses different conventions! https://stereokit.net/Pages/StereoKit/Matrix/Transposed.html

see also matrix_transpose

Examples

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

let transform = Matrix::t([1.0, 2.0, 3.0]);
assert_eq!(transform, Matrix::from([
    1.0, 0.0, 0.0, 0.0,
    0.0, 1.0, 0.0, 0.0,
    0.0, 0.0, 1.0, 0.0,
    1.0, 2.0, 3.0, 1.0,
]));

let transposed = transform.get_transposed();
assert_eq!(transposed, Matrix::from([
    1.0, 0.0, 0.0, 1.0,
    0.0, 1.0, 0.0, 2.0,
    0.0, 0.0, 1.0, 3.0,
    0.0, 0.0, 0.0, 1.0,
]));

Trait Implementations

impl Clone for Matrix

fn clone(&self) -> Matrix

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Matrix

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

Formats the value using the given formatter.

impl Display for Matrix

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

Mostly for debug purposes, this is a decent way to log or inspect the matrix in debug mode. Looks like “[, , , ]”

Examples

use stereokit_rust::maths::Matrix;

let matrix = Matrix::from([
    1.0, 2.0, 3.3, 4.0,
    5.0, 6.0, 7.0, 8.0,
    9.0, 10.0, 11.0, 12.0,
    13.0, 14.0, 15.0, 16.0,
]);
assert_eq!(format!("{}", matrix),
"[\r\n [x:1, y:2, z:3.3, w:4],\r\n [x:5, y:6, z:7, w:8],\r\n [x:9, y:10, z:11, w:12],\r\n [x:13, y:14, z:15, w:16]]");

impl From<[f32; 16]> for Matrix

fn from(s: [f32; 16]) -> Self

Converts to this type from the input type.

impl From<Mat4> for Matrix

fn from(m: Mat4) -> Self

Converts to this type from the input type.

impl From<Matrix> for Pose

fn from(matrix: Matrix) -> Self

Converts to this type from the input type.

impl From<Pose> for Matrix

fn from(pose: Pose) -> Self

Converts to this type from the input type.

impl Mul<Matrix> for Pose

Transforms a Pose by the Matrix! The position and orientation are both transformed by the matrix, accounting properly for the Pose’s quaternion. https://stereokit.net/Pages/StereoKit/Matrix/op_Multiply.html

see also matrix_transform_pose

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

Examples

use stereokit_rust::maths::{Pose, Vec3, Matrix};

let transform = Matrix::t([1.0, 2.0, 3.0]);
let pose = Pose::new([0.0, 0.0, 0.0], None);

let transformed_pose = pose * transform;
assert_eq!(transformed_pose, Pose::new([1.0, 2.0, 3.0], None));

type Output = Pose

The resulting type after applying the * operator.

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<Matrix> for Ray

Transforms a Ray by the Matrix! The position and direction are both multiplied by the matrix, accounting properly for which should include translation, and which should not. https://stereokit.net/Pages/StereoKit/Matrix/op_Multiply.html

see also matrix_transform_ray

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

Examples

use stereokit_rust::maths::{Vec3, Matrix, Ray};

let transform = Matrix::t([1.0, 2.0, 3.0]);
let ray = Ray::new([0.0, 0.0, 0.0], [1.0, 0.0, 0.0]);

let transformed_ray = ray * transform;
assert_eq!(transformed_ray, Ray::new([1.0, 2.0, 3.0], [1.0, 0.0, 0.0]));

type Output = Ray

The resulting type after applying the * operator.

impl Mul<Matrix> for Vec3

Multiplies the vector by the Matrix! Since only a 1x4 vector can be multiplied against a 4x4 matrix, this uses ‘1’ for the 4th element, so the result will also include translation! To exclude translation, use Matrix.transform_normal. https://stereokit.net/Pages/StereoKit/Matrix/op_Multiply.html

see also matrix_transform_pt

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

Examples

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

let transform = Matrix::t([1.0, 2.0, 3.0]);
let point = Vec3::new(1.0, 1.0, 1.0);

let transformed_point = point * transform;
assert_eq!(transformed_point, Vec3::new(2.0, 3.0, 4.0));

type Output = Vec3

The resulting type after applying the * operator.

impl Mul<Matrix> for Vec4

https://stereokit.net/Pages/StereoKit/Matrix/op_Multiply.html

see also matrix_transform_pt4

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

Examples

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

let transform = Matrix::t([1.0, 2.0, 3.0]);
let v4 = Vec4::new(1.0, 1.0, 1.0, 1.0);

let transformed_v4 = v4 * transform;
assert_eq!(transformed_v4, Vec4::new(2.0, 3.0, 4.0, 1.0));

type Output = Vec4

The resulting type after applying the * operator.

impl Mul<Pose> for Matrix

Transforms a Pose by the Matrix! The position and orientation are both transformed by the matrix, accounting properly for the Pose’s quaternion. https://stereokit.net/Pages/StereoKit/Matrix/op_Multiply.html

see also matrix_transform_pose

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

Examples

use stereokit_rust::maths::{Pose, Vec3, Matrix};

let transform = Matrix::t([1.0, 2.0, 3.0]);
let pose = Pose::new([0.0, 0.0, 0.0], None);

let transformed_pose = transform * pose;
assert_eq!(transformed_pose, Pose::new([1.0, 2.0, 3.0], None));

type Output = Pose

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<Ray> for Matrix

Transforms a Ray by the Matrix! The position and direction are both multiplied by the matrix, accounting properly for which should include translation, and which should not. https://stereokit.net/Pages/StereoKit/Matrix/op_Multiply.html

see also matrix_transform_ray

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

Examples

use stereokit_rust::maths::{Vec3, Matrix, Ray};

let transform = Matrix::t([1.0, 2.0, 3.0]);
let ray = Ray::new([0.0, 0.0, 0.0], [1.0, 0.0, 0.0]);

let transformed_ray = transform * ray;
assert_eq!(transformed_ray, Ray::new([1.0, 2.0, 3.0], [1.0, 0.0, 0.0]));

type Output = Ray

The resulting type after applying the * operator.

impl Mul<Vec3> for Matrix

Multiplies the vector by the Matrix! Since only a 1x4 vector can be multiplied against a 4x4 matrix, this uses ‘1’ for the 4th element, so the result will also include translation! To exclude translation, use Matrix.transform_normal. https://stereokit.net/Pages/StereoKit/Matrix/op_Multiply.html

see also matrix_transform_pt

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

Examples

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

let transform = Matrix::t([1.0, 2.0, 3.0]);
let point = Vec3::new(1.0, 1.0, 1.0);

let transformed_point = transform * point;
assert_eq!(transformed_point, Vec3::new(2.0, 3.0, 4.0));

type Output = Vec3

The resulting type after applying the * operator.

impl Mul<Vec4> for Matrix

https://stereokit.net/Pages/StereoKit/Matrix/op_Multiply.html

see also matrix_transform_pt4

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

Examples

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

let transform = Matrix::t([1.0, 2.0, 3.0]);
let v4 = Vec4::new(1.0, 1.0, 1.0, 1.0);

let transformed_v4 = transform * v4;
assert_eq!(transformed_v4, Vec4::new(2.0, 3.0, 4.0, 1.0));

type Output = Vec4

The resulting type after applying the * operator.

impl Mul for Matrix

Multiplies two matrices together! This is a great way to combine transform operations. Note that StereoKit’s matrices are row-major, and multiplication order is important! To translate, then scale, multiply in order of ‘translate * scale’. https://stereokit.net/Pages/StereoKit/Matrix/op_Multiply.html

see also matrix_mul

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

Examples

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

let transform_a = Matrix::t([1.0, 2.0, 3.0]);
let transform_b = Matrix::s([2.0, 2.0, 2.0]);

let transform_c = transform_a * transform_b;
let point = Vec3::new(1.0, 1.0, 1.0);
let transformed_point = transform_c * point;
assert_eq!(transformed_point, Vec3::new(4.0, 6.0, 8.0));

type Output = Matrix

The resulting type after applying the * operator.

impl MulAssign<Matrix> for Pose

Transforms a Pose by the Matrix! The position and orientation are both transformed by the matrix, accounting properly for the Pose’s quaternion. https://stereokit.net/Pages/StereoKit/Matrix/op_Multiply.html

see also matrix_transform_pose

fn mul_assign(&mut self, rhs: Matrix)

Examples

use stereokit_rust::maths::{Pose, Vec3, Matrix};

let mut pose = Pose::new([0.0, 0.0, 0.0], None);
let transform = Matrix::t([1.0, 2.0, 3.0]);

pose *= transform;
assert_eq!(pose, Pose::new([1.0, 2.0, 3.0], None));

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<Matrix> for Ray

Transforms a Ray by the Matrix! The position and direction are both multiplied by the matrix, accounting properly for which should include translation, and which should not. https://stereokit.net/Pages/StereoKit/Matrix/op_Multiply.html

see also matrix_transform_ray

fn mul_assign(&mut self, rhs: Matrix)

use stereokit_rust::maths::{Vec3, Matrix, Ray};

let mut ray = Ray::new([0.0, 0.0, 0.0], [1.0, 0.0, 0.0]);
let transform = Matrix::t([1.0, 2.0, 3.0]);

ray *= transform;
assert_eq!(ray, Ray::new([1.0, 2.0, 3.0], [1.0, 0.0, 0.0]));

impl MulAssign<Matrix> for Vec3

Multiplies the vector by the Matrix! Since only a 1x4 vector can be multiplied against a 4x4 matrix, this uses ‘1’ for the 4th element, so the result will also include translation! To exclude translation, use Matrix.transform_normal. https://stereokit.net/Pages/StereoKit/Matrix/op_Multiply.html

see also matrix_transform_pt

fn mul_assign(&mut self, rhs: Matrix)

Examples

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

let mut point = Vec3::new(1.0, 1.0, 1.0);
let transform = Matrix::t([1.0, 2.0, 3.0]);

point *= transform;
assert_eq!(point, Vec3::new(2.0, 3.0, 4.0));

impl MulAssign<Matrix> for Vec4

https://stereokit.net/Pages/StereoKit/Matrix/op_Multiply.html

see also matrix_transform_pt4

fn mul_assign(&mut self, rhs: Matrix)

Examples

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

let mut v4 = Vec4::new(1.0, 1.0, 1.0, 1.0);
let transform = Matrix::t([1.0, 2.0, 3.0]);

v4 *= transform;
assert_eq!(v4, Vec4::new(2.0, 3.0, 4.0, 1.0));

impl MulAssign for Matrix

Multiplies two matrices together! This is a great way to combine transform operations. Note that StereoKit’s matrices are row-major, and multiplication order is important! To translate, then scale, multiply in order of ‘translate * scale’. https://stereokit.net/Pages/StereoKit/Matrix/op_Multiply.html

see also matrix_mul

fn mul_assign(&mut self, rhs: Matrix)

Examples

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

let mut transform_a = Matrix::t([1.0, 2.0, 3.0]);
let transform_b = Matrix::s([2.0, 2.0, 2.0]);

transform_a *= transform_b;
let point = Vec3::new(1.0, 1.0, 1.0);
let transformed_point = transform_a * point;
assert_eq!(transformed_point, Vec3::new(4.0, 6.0, 8.0));

impl PartialEq for Matrix

Warning: Equality with a precision of 0.1 millimeter

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

Warning: Equality with a precision of 0.00001

Examples

use stereokit_rust::maths::Matrix;

let matrix = Matrix::IDENTITY;
assert_eq!(matrix, Matrix::IDENTITY);

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 Copy for Matrix