Struct Matrix 

#[repr(transparent)]
pub struct Matrix<Repr, Map>(pub Repr, _);

A generic matrix type.

Tuple Fields

0: Repr

Implementations

impl<Repr, Map> Matrix<Repr, Map>

pub const fn new(els: Repr) -> Self

Returns a matrix with the given elements.

pub fn to<M>(&self) -> Matrix<Repr, M>

where Repr: Clone,

Returns a matrix equal to self but with mapping M.

This method can be used to coerce a matrix to a different mapping in case it is needed to make types match.

Examples found in repository

examples/hello_tri.rs (line 31)

fn main() {
    let verts = [
        vertex(pt3(-1.0, 1.0, 0.0), rgb(1.0, 0.0, 0.0)),
        vertex(pt3(1.0, 1.0, 0.0), rgb(0.0, 0.8, 0.0)),
        vertex(pt3(0.0, -1.0, 0.0), rgb(0.4, 0.4, 1.0)),
    ];

    #[cfg(feature = "fp")]
    let shader = shader::new(
        |v: Vertex3<Color3f>, mvp: &Mat4x4<ModelToProj>| {
            // Transform vertex position from model to projection space
            // Interpolate vertex colors in linear color space
            vertex(mvp.apply(&v.pos), v.attrib.to_linear())
        },
        |frag: Frag<Color3f<_>>| frag.var.to_srgb().to_color4(),
    );
    #[cfg(not(feature = "fp"))]
    let shader = shader::new(
        |v: Vertex3<Color3f>, mvp: &Mat4x4<ModelToProj>| {
            // Transform vertex position from model to projection space
            // Interpolate vertex colors in normal sRGB color space
            vertex(mvp.apply(&v.pos), v.attrib)
        },
        |frag: Frag<Color3f<_>>| frag.var.to_color4(),
    );

    let dims @ (w, h) = (640, 480);
    let modelview = translate3(0.0, 0.0, 2.0).to();
    let project = perspective(1.0, w as f32 / h as f32, 0.1..1000.0);
    let viewport = viewport(pt2(0, h)..pt2(w, 0));

    let mut framebuf = Buf2::<Color4>::new(dims);

    render(
        [tri(0, 1, 2)],
        verts,
        &shader,
        &modelview.then(&project),
        viewport,
        &mut framebuf,
        &Context::default(),
    );

    let center_pixel = framebuf[[w / 2, h / 2]];

    if cfg!(feature = "fp") {
        assert_eq!(center_pixel, rgba(150, 128, 186, 255));
    } else {
        assert_eq!(center_pixel, rgba(114, 102, 127, 255));
    }
    #[cfg(feature = "std")]
    {
        pnm::save_ppm("triangle.ppm", framebuf).unwrap();
    }
}

impl<Sc, const N: usize, const M: usize, Map> Matrix<[[Sc; N]; M], Map>

where Sc: Copy, Map: LinearMap,

pub fn row_vec(&self, i: usize) -> Vector<[Sc; N], Map::Source>

Returns the row vector of self with index i.

The returned vector is in space Map::Source.

Panics

If i >= M.

pub fn col_vec(&self, i: usize) -> Vector<[Sc; M], Map::Dest>

Returns the column vector of self with index i.

The returned vector is in space Map::Dest.

Panics

If i >= N.

impl<Sc: Copy, const N: usize, const DIM: usize, S, D> Matrix<[[Sc; N]; N], RealToReal<DIM, S, D>>

pub fn transpose(self) -> Matrix<[[Sc; N]; N], RealToReal<DIM, D, S>>

Returns self with its rows and columns swapped.

impl<const N: usize, Map> Matrix<[[f32; N]; N], Map>

pub const fn identity() -> Self

Returns the N×N identity matrix.

An identity matrix is a square matrix with ones on the main diagonal and zeroes everywhere else:

        ⎛ 1  0  ⋯  0 ⎞
 I  =   ⎜ 0  1       ⎟
        ⎜ ⋮     ⋱  0 ⎟
        ⎝ 0     0  1 ⎠

It is the neutral element of matrix multiplication: A · I = I · A = A, as well as matrix-vector multiplication: I·v = v.

impl Matrix<[[f32; 4]; 4], ()>

pub const fn from_linear<S, D>( i: Vec3<D>, j: Vec3<D>, k: Vec3<D>, ) -> Mat4x4<RealToReal<3, S, D>>

Constructs a matrix from a linear basis.

The basis does not have to be orthonormal.

pub const fn from_affine<S, D>( i: Vec3<D>, j: Vec3<D>, k: Vec3<D>, o: Point3<D>, ) -> Mat4x4<RealToReal<3, S, D>>

Constructs a matrix from an affine basis, or frame.

The basis does not have to be orthonormal.

impl<Sc, const N: usize, Map> Matrix<[[Sc; N]; N], Map>

where Sc: Linear<Scalar = Sc> + Copy, Map: LinearMap,

pub fn compose<Inner: LinearMap>( &self, other: &Matrix<[[Sc; N]; N], Inner>, ) -> Matrix<[[Sc; N]; N], <Map as Compose<Inner>>::Result>

where Map: Compose<Inner>,

Returns the composite transform of self and other.

Computes the matrix product of self and other such that applying the resulting transformation is equivalent to first applying other and then self. More succinctly,

(𝗠 ∘ 𝗡) 𝘃 = 𝗠(𝗡 𝘃)

for some matrices 𝗠 and 𝗡 and a vector 𝘃.

pub fn then<Outer: Compose<Map>>( &self, other: &Matrix<[[Sc; N]; N], Outer>, ) -> Matrix<[[Sc; N]; N], <Outer as Compose<Map>>::Result>

Returns the composite transform of other and self.

Computes the matrix product of self and other such that applying the resulting matrix is equivalent to first applying self and then other. The call self.then(other) is thus equivalent to other.compose(self).

Examples found in repository

examples/hello_tri.rs (line 41)

fn main() {
    let verts = [
        vertex(pt3(-1.0, 1.0, 0.0), rgb(1.0, 0.0, 0.0)),
        vertex(pt3(1.0, 1.0, 0.0), rgb(0.0, 0.8, 0.0)),
        vertex(pt3(0.0, -1.0, 0.0), rgb(0.4, 0.4, 1.0)),
    ];

    #[cfg(feature = "fp")]
    let shader = shader::new(
        |v: Vertex3<Color3f>, mvp: &Mat4x4<ModelToProj>| {
            // Transform vertex position from model to projection space
            // Interpolate vertex colors in linear color space
            vertex(mvp.apply(&v.pos), v.attrib.to_linear())
        },
        |frag: Frag<Color3f<_>>| frag.var.to_srgb().to_color4(),
    );
    #[cfg(not(feature = "fp"))]
    let shader = shader::new(
        |v: Vertex3<Color3f>, mvp: &Mat4x4<ModelToProj>| {
            // Transform vertex position from model to projection space
            // Interpolate vertex colors in normal sRGB color space
            vertex(mvp.apply(&v.pos), v.attrib)
        },
        |frag: Frag<Color3f<_>>| frag.var.to_color4(),
    );

    let dims @ (w, h) = (640, 480);
    let modelview = translate3(0.0, 0.0, 2.0).to();
    let project = perspective(1.0, w as f32 / h as f32, 0.1..1000.0);
    let viewport = viewport(pt2(0, h)..pt2(w, 0));

    let mut framebuf = Buf2::<Color4>::new(dims);

    render(
        [tri(0, 1, 2)],
        verts,
        &shader,
        &modelview.then(&project),
        viewport,
        &mut framebuf,
        &Context::default(),
    );

    let center_pixel = framebuf[[w / 2, h / 2]];

    if cfg!(feature = "fp") {
        assert_eq!(center_pixel, rgba(150, 128, 186, 255));
    } else {
        assert_eq!(center_pixel, rgba(114, 102, 127, 255));
    }
    #[cfg(feature = "std")]
    {
        pnm::save_ppm("triangle.ppm", framebuf).unwrap();
    }
}

impl<Src, Dest> Matrix<[[f32; 2]; 2], RealToReal<2, Src, Dest>>

pub const fn determinant(&self) -> f32

Returns the determinant of self.

Examples

use retrofire_core::math::{Mat2x2, mat::RealToReal};

let double: Mat2x2<RealToReal<2>> = [[2.0, 0.0], [0.0, 2.0]].into();
assert_eq!(double.determinant(), 4.0);

let singular: Mat2x2<RealToReal<2>> = [[1.0, 0.0], [2.0, 0.0]].into();
assert_eq!(singular.determinant(), 0.0);

pub const fn checked_inverse(&self) -> Option<Mat2x2<RealToReal<2, Dest, Src>>>

Returns the inverse of self, or None if self is not invertible.

A matrix is invertible if and only if its determinant is nonzero. A non-invertible matrix is also called singular.

Examples

use retrofire_core::math::{Mat2x2, mat::RealToReal};

let rotate_90: Mat2x2<RealToReal<2>> = [[0.0, -1.0], [1.0, 0.0]].into();
let rotate_neg_90 = rotate_90.checked_inverse();

assert_eq!(rotate_neg_90, Some([[0.0, 1.0], [-1.0, 0.0]].into()));

let singular: Mat2x2<RealToReal<2>> = [[1.0, 0.0], [2.0, 0.0]].into();
assert_eq!(singular.checked_inverse(), None);

pub const fn inverse(&self) -> Mat2x2<RealToReal<2, Dest, Src>>

Returns the inverse of self, if it exists.

A matrix is invertible if and only if its determinant is nonzero. A non-invertible matrix is also called singular.

Panics

If self has no inverse.

Examples

use retrofire_core::math::{Mat2x2, mat::RealToReal, vec2};

let rotate_90: Mat2x2<RealToReal<2>> = [[0.0, -1.0], [1.0, 0.0]].into();
let rotate_neg_90 = rotate_90.inverse();

assert_eq!(rotate_neg_90.0, [[0.0, 1.0], [-1.0, 0.0]]);
assert_eq!(rotate_90.then(&rotate_neg_90), Mat2x2::identity())

// This matrix has no inverse
let singular: Mat2x2<RealToReal<2>> = [[1.0, 0.0], [2.0, 0.0]].into();

// This will panic
let _ = singular.inverse();

impl<Src, Dest> Matrix<[[f32; 3]; 3], RealToReal<2, Src, Dest>>

pub const fn determinant(&self) -> f32

Returns the determinant of self.

pub const fn cofactor(&self, row: usize, col: usize) -> f32

Returns the cofactor of the element at the given row and column.

Cofactors are used to compute the inverse of a matrix. A cofactor is calculated as follows:

1. Remove the given row and column from self to get a 2x2 submatrix;
2. Compute its determinant;
3. If exactly one of row and col is even, multiply by -1.

Examples

use retrofire_core::{mat, math::Mat3x3, math::mat::RealToReal};

let mat: Mat3x3<RealToReal<2>> = mat![
    1.0, 2.0, 3.0;
    4.0, 5.0, 6.0;
    7.0, 8.0, 9.0
];
// Remove row 0 and col 1, giving [[4.0, 6.0], [7.0, 9.0]].
// The determinant of this submatrix is 4.0 * 7.0 - 6.0 * 9.0.
// Multiply by -1 because row is even and col is odd.
assert_eq!(mat.cofactor(0, 1), 6.0 * 7.0 - 4.0 * 9.0);

pub fn checked_inverse(&self) -> Option<Mat3x3<RealToReal<2, Dest, Src>>>

Returns the inverse of self, or None if self is singular.

pub fn inverse(&self) -> Mat3x3<RealToReal<2, Dest, Src>>

impl<Src, Dst> Matrix<[[f32; 4]; 4], RealToReal<3, Src, Dst>>

pub fn determinant(&self) -> f32

Returns the determinant of self.

Given a matrix M,

        ⎛ a  b  c  d ⎞
 M  =   ⎜ e  f  g  h ⎟
        ⎜ i  j  k  l ⎟
        ⎝ m  n  o  p ⎠

its determinant can be computed by recursively computing the determinants of sub-matrices on rows 1..4 and multiplying them by the elements on row 0:

             ⎜ f g h ⎜       ⎜ e g h ⎜
det(M) = a · ⎜ j k l ⎜ - b · ⎜ i k l ⎜  + - ···
             ⎜ n o p ⎜       ⎜ m o p ⎜

pub fn inverse(&self) -> Mat4x4<RealToReal<3, Dst, Src>>

Returns the inverse matrix of self.

The inverse 𝝡^-1 of matrix 𝝡 is a matrix that, when composed with 𝝡, results in the identity matrix:

𝝡 ∘ 𝝡^-1 = 𝝡^-1 ∘ 𝝡 = 𝐈

In other words, it applies the transform of 𝝡 in reverse. Given vectors 𝘃 and 𝘂,

𝝡𝘃 = 𝘂 ⇔ 𝝡^-1 𝘂 = 𝘃.

Only matrices with a nonzero determinant have a defined inverse. A matrix without an inverse is said to be singular.

Note: This method uses naive Gauss–Jordan elimination and may suffer from imprecision or numerical instability in certain cases.

Panics

If debug assertions are enabled, panics if self is singular or near-singular. If not enabled, the return value is unspecified and may contain non-finite values (infinities and NaNs).

Trait Implementations

impl<Repr, E, M> ApproxEq<Matrix<Repr, M>, E> for Matrix<Repr, M>

where Repr: ApproxEq<Repr, E>,

fn approx_eq_eps(&self, other: &Self, rel_eps: &E) -> bool

Returns whether self and other are approximately equal, using the relative epsilon rel_eps.

fn relative_epsilon() -> E

Returns the default relative epsilon of type E.

fn approx_eq(&self, other: &Other) -> bool

Returns whether self and other are approximately equal. Uses the epsilon returned by Self::relative_epsilon.

impl<R: Clone, M> Clone for Matrix<R, M>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<S: Debug, Map: Debug + Default, const N: usize, const M: usize> Debug for Matrix<[[S; N]; M], Map>

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

Formats the value using the given formatter.

impl<const N: usize, Map> Default for Matrix<[[f32; N]; N], Map>

fn default() -> Self

Returns the N×N identity matrix.

impl<Repr, M> From<Repr> for Matrix<Repr, M>

fn from(repr: Repr) -> Self

Converts to this type from the input type.

impl<Repr: PartialEq, Map: PartialEq> PartialEq for Matrix<Repr, Map>

fn eq(&self, other: &Matrix<Repr, Map>) -> 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<Repr: Copy, Map: Copy> Copy for Matrix<Repr, Map>

impl<Repr: Eq, Map: Eq> Eq for Matrix<Repr, Map>

impl<Repr, Map> StructuralPartialEq for Matrix<Repr, Map>