Struct Mat4 

#[repr(C)]
pub struct Mat4 {
    pub cols: [Vec4; 4],
}

A 4x4 column-major matrix, used for 3D affine transformations.

This is the primary type for representing transformations (translation, rotation, scale) in 3D space. It is also used for camera view and projection matrices. The memory layout is column-major, which is compatible with modern graphics APIs like Vulkan, Metal, and DirectX.

Examples

use khora_core::math::{Mat4, Quaternion, Vec3};
use std::f32::consts::FRAC_PI_2;

// The identity matrix leaves a point unchanged.
assert_eq!(Mat4::IDENTITY.transform_point(Vec3::ONE), Vec3::ONE);

// Compose translation ∘ rotation ∘ scale by multiplying matrices
// (applied right-to-left).
let model = Mat4::from_translation(Vec3::new(0.0, 1.0, 0.0))
    * Mat4::from_quat(Quaternion::from_axis_angle(Vec3::Y, FRAC_PI_2))
    * Mat4::from_scale(Vec3::ONE * 2.0);
let moved = model.transform_point(Vec3::ZERO);
assert!((moved - Vec3::new(0.0, 1.0, 0.0)).length() < 1e-5);

// A perspective projection for a 16:9 viewport.
let proj = Mat4::perspective_rh_zo(FRAC_PI_2, 16.0 / 9.0, 0.1, 1000.0);
assert!(proj != Mat4::IDENTITY);

Fields

cols: [Vec4; 4]

The columns of the matrix. cols[0] is the first column, and so on.

Implementations

impl Mat4

pub const IDENTITY: Mat4

The 4x4 identity matrix.

pub const ZERO: Mat4

A 4x4 matrix with all elements set to 0.

pub fn from_cols(c0: Vec4, c1: Vec4, c2: Vec4, c3: Vec4) -> Mat4

Creates a new matrix from four column vectors.

pub fn get_row(&self, index: usize) -> Vec4

Returns a row of the matrix as a Vec4.

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

Returns the matrix as a 2D array of columns: [[x, y, z, w]; 4].

pub fn from_translation(v: Vec3) -> Mat4

Creates a translation matrix.

Arguments

• v: The translation vector to apply.

pub fn from_scale(scale: Vec3) -> Mat4

Creates a non-uniform scaling matrix.

pub fn from_rotation_x(angle: f32) -> Mat4

Creates a matrix for a rotation around the X-axis.

Arguments

• angle: The angle of rotation in radians.

pub fn from_rotation_y(angle: f32) -> Mat4

Creates a matrix for a right-handed rotation around the Y-axis.

Arguments

• angle: The angle of rotation in radians.

pub fn from_rotation_z(angle: f32) -> Mat4

Creates a matrix for a rotation around the Z-axis.

Arguments

• angle: The angle of rotation in radians.

pub fn from_axis_angle(axis: Vec3, angle: f32) -> Mat4

Creates a rotation matrix from a normalized axis and an angle.

Arguments

• axis: The axis of rotation. Must be a unit vector.
• angle: The angle of rotation in radians.

pub fn from_quat(q: Quaternion) -> Mat4

Creates a rotation matrix from a quaternion.

pub fn perspective_rh_zo( fov_y_radians: f32, aspect_ratio: f32, z_near: f32, z_far: f32, ) -> Mat4

Creates a right-handed perspective projection matrix with a [0, 1] depth range (ZO).

Arguments

• fov_y_radians: Vertical field of view in radians.
• aspect_ratio: Width divided by height of the viewport.
• z_near: Distance to the near clipping plane (must be positive).
• z_far: Distance to the far clipping plane (must be positive and > z_near).

pub fn orthographic_rh_zo( left: f32, right: f32, bottom: f32, top: f32, z_near: f32, z_far: f32, ) -> Mat4

Creates a right-handed orthographic projection matrix with a [0, 1] depth range (ZO).

pub fn look_at_rh(eye: Vec3, target: Vec3, up: Vec3) -> Option<Mat4>

Creates a right-handed view matrix for a camera looking from eye towards target.

Arguments

• eye: The position of the camera in world space.
• target: The point in world space that the camera is looking at.
• up: A vector indicating the “up” direction of the world (commonly Vec3::Y).

Returns

Returns Some(Mat4) if a valid view matrix can be constructed, or None if eye and target are too close, or if up is parallel to the view direction.

pub fn cube_face_view_proj(position: Vec3, face: CubeFace, far: f32) -> Mat4

View-projection matrix for one face of an omnidirectional cubemap rendered from position.

Builds a 90°-FOV perspective with [NEAR, far] depth range, then a look-at matrix using CubeFace::forward and CubeFace::up in the wgpu cubemap convention. The near plane is fixed at 0.1 — the matching shader-side depth recompute (used in omnidirectional shadow sampling) assumes the same constant.

far should be the light’s effective range in world units.

pub fn cube_face_view_projs(position: Vec3, far: f32) -> [Mat4; 6]

Six view-projection matrices, one per cube face, in CubeFace::ALL order ([+X, -X, +Y, -Y, +Z, -Z]).

Equivalent to:

CubeFace::ALL.map(|f| Mat4::cube_face_view_proj(position, f, far))

pub fn transpose(&self) -> Mat4

Returns the transpose of the matrix, where rows and columns are swapped.

pub fn determinant(&self) -> f32

Computes the determinant of the matrix.

pub fn inverse(&self) -> Option<Mat4>

Computes the inverse of the matrix. Returns None if the matrix is not invertible.

pub fn affine_inverse(&self) -> Option<Mat4>

Computes the inverse of an affine transformation matrix more efficiently and with better numerical stability than the general inverse method.

An affine matrix is one composed of only translation, rotation, and scale.

Returns

None if the matrix is not affine or is not invertible.

pub fn transform_point(&self, p: Vec3) -> Vec3

Transforms a 3D point by this matrix (treating it as a homogeneous point with w=1).

This applies the full affine transformation including translation, rotation, and scale.

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

Transforms a 3D direction vector by this matrix (treating it as w=0).

This applies rotation and scale but not translation. Use this for normals, axes, and other direction vectors.

Trait Implementations

impl<'__de, __Context> BorrowDecode<'__de, __Context> for Mat4

fn borrow_decode<__D>(decoder: &mut __D) -> Result<Mat4, DecodeError>

where __D: BorrowDecoder<'__de, Context = __Context>,

Attempt to decode this type with the given BorrowDecode.

impl Clone for Mat4

fn clone(&self) -> Mat4

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Mat4

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

Formats the value using the given formatter.

impl<__Context> Decode<__Context> for Mat4

fn decode<__D>(decoder: &mut __D) -> Result<Mat4, DecodeError>

where __D: Decoder<Context = __Context>,

Attempt to decode this type with the given Decode.

impl Default for Mat4

fn default() -> Mat4

Returns the 4x4 identity matrix.

impl<'de> Deserialize<'de> for Mat4

fn deserialize<__D>( __deserializer: __D, ) -> Result<Mat4, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Encode for Mat4

fn encode<__E>(&self, encoder: &mut __E) -> Result<(), EncodeError>

where __E: Encoder,

Encode a given type.

impl From<AffineTransform> for Mat4

fn from(transform: AffineTransform) -> Mat4

Converts the AffineTransform into its inner Mat4.

impl From<Mat4> for AffineTransform

fn from(val: Mat4) -> AffineTransform

Converts a Mat4 into an AffineTransform.

Panics

Panics if the matrix is not a valid affine transformation.

impl Mul<Vec4> for Mat4

fn mul(self, rhs: Vec4) -> <Mat4 as Mul<Vec4>>::Output

Transforms a Vec4 by this matrix.

type Output = Vec4

The resulting type after applying the * operator.

impl Mul for Mat4

fn mul(self, rhs: Mat4) -> <Mat4 as Mul>::Output

Multiplies this matrix by another Mat4. Note that matrix multiplication is not commutative.

type Output = Mat4

The resulting type after applying the * operator.

impl PartialEq for Mat4

fn eq(&self, other: &Mat4) -> 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 Serialize for Mat4

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Zeroable for Mat4

fn zeroed() -> Self

Calls zeroed.

impl Copy for Mat4

impl Pod for Mat4

impl StructuralPartialEq for Mat4