Struct Transform3D

#[repr(C)]
pub struct Transform3D<T, Src, Dst> {Show 16 fields
    pub m11: T,
    pub m12: T,
    pub m13: T,
    pub m14: T,
    pub m21: T,
    pub m22: T,
    pub m23: T,
    pub m24: T,
    pub m31: T,
    pub m32: T,
    pub m33: T,
    pub m34: T,
    pub m41: T,
    pub m42: T,
    pub m43: T,
    pub m44: T,
    /* private fields */
}

Expand description

A 3d transform stored as a column-major 4 by 4 matrix.

Transforms can be parametrized over the source and destination units, to describe a transformation from a space to another. For example, Transform3D<f32, WorldSpace, ScreenSpace>::transform_point3d takes a Point3D<f32, WorldSpace> and returns a Point3D<f32, ScreenSpace>.

Transforms expose a set of convenience methods for pre- and post-transformations. Pre-transformations (pre_* methods) correspond to adding an operation that is applied before the rest of the transformation, while post-transformations (then_* methods) add an operation that is applied after.

When translating Transform3D into general matrix representations, consider that the representation follows the column major notation with column vectors.

 |x'|   | m11 m12 m13 m14 |   |x|
 |y'|   | m21 m22 m23 m24 |   |y|
 |z'| = | m31 m32 m33 m34 | x |y|
 |w |   | m41 m42 m43 m44 |   |1|

The translation terms are m41, m42 and m43.

Fields§

§m11: T§m12: T§m13: T§m14: T§m21: T§m22: T§m23: T§m24: T§m31: T§m32: T§m33: T§m34: T§m41: T§m42: T§m43: T§m44: T

Implementations§

§

impl<T, Src, Dst> Transform3D<T, Src, Dst>

pub const fn new( m11: T, m12: T, m13: T, m14: T, m21: T, m22: T, m23: T, m24: T, m31: T, m32: T, m33: T, m34: T, m41: T, m42: T, m43: T, m44: T, ) -> Transform3D<T, Src, Dst>

Create a transform specifying all of it’s component as a 4 by 4 matrix.

Components are specified following column-major-column-vector matrix notation. For example, the translation terms m41, m42, m43 are the 13rd, 14th and 15th parameters.

use euclid::default::Transform3D;
let tx = 1.0;
let ty = 2.0;
let tz = 3.0;
let translation = Transform3D::new(
  1.0, 0.0, 0.0, 0.0,
  0.0, 1.0, 0.0, 0.0,
  0.0, 0.0, 1.0, 0.0,
  tx,  ty,  tz,  1.0,
);

pub fn new_2d( m11: T, m12: T, m21: T, m22: T, m41: T, m42: T, ) -> Transform3D<T, Src, Dst>
where T: Zero + One,

Create a transform representing a 2d transformation from the components of a 2 by 3 matrix transformation.

Components follow the column-major-column-vector notation (m41 and m42 representing the translation terms).

m11  m12   0   0
m21  m22   0   0
  0    0   1   0
m41  m42   0   1

pub fn is_2d(&self) -> bool
where T: Zero + One + PartialEq,

Returns true if this transform can be represented with a Transform2D.

See https://drafts.csswg.org/css-transforms/#2d-transform

§

impl<T, Src, Dst> Transform3D<T, Src, Dst>
where T: Copy,

pub fn to_array(&self) -> [T; 16]

Returns an array containing this transform’s terms.

The terms are laid out in the same order as they are specified in Transform3D::new, that is following the column-major-column-vector matrix notation.

For example the translation terms are found on the 13th, 14th and 15th slots of the array.

pub fn to_array_transposed(&self) -> [T; 16]

Returns an array containing this transform’s terms transposed.

The terms are laid out in transposed order from the same order of Transform3D::new and Transform3D::to_array, that is following the row-major-column-vector matrix notation.

For example the translation terms are found at indices 3, 7 and 11 of the array.

pub fn to_arrays(&self) -> [[T; 4]; 4]

Equivalent to to_array with elements packed four at a time in an array of arrays.

pub fn to_arrays_transposed(&self) -> [[T; 4]; 4]

Equivalent to to_array_transposed with elements packed four at a time in an array of arrays.

pub fn from_array(array: [T; 16]) -> Transform3D<T, Src, Dst>

Create a transform providing its components via an array of 16 elements instead of as individual parameters.

The order of the components corresponds to the column-major-column-vector matrix notation (the same order as Transform3D::new).

pub fn from_arrays(array: [[T; 4]; 4]) -> Transform3D<T, Src, Dst>

Equivalent to from_array with elements packed four at a time in an array of arrays.

The order of the components corresponds to the column-major-column-vector matrix notation (the same order as Transform3D::new).

pub fn from_untyped( m: &Transform3D<T, UnknownUnit, UnknownUnit>, ) -> Transform3D<T, Src, Dst>

Tag a unitless value with units.

pub fn to_untyped(&self) -> Transform3D<T, UnknownUnit, UnknownUnit>

Drop the units, preserving only the numeric value.

pub fn with_source<NewSrc>(&self) -> Transform3D<T, NewSrc, Dst>

Returns the same transform with a different source unit.

pub fn with_destination<NewDst>(&self) -> Transform3D<T, Src, NewDst>

Returns the same transform with a different destination unit.

pub fn to_2d(&self) -> Transform2D<T, Src, Dst>

Create a 2D transform picking the relevant terms from this transform.

This method assumes that self represents a 2d transformation, callers should check that is_2d returns true beforehand.

§

impl<T, Src, Dst> Transform3D<T, Src, Dst>
where T: Zero + One,

pub fn identity() -> Transform3D<T, Src, Dst>

Creates an identity matrix:

pub fn skew(alpha: Angle<T>, beta: Angle<T>) -> Transform3D<T, Src, Dst>
where T: Trig,

Create a 2d skew transform.

See https://drafts.csswg.org/css-transforms/#funcdef-skew

pub fn perspective(d: T) -> Transform3D<T, Src, Dst>
where T: Neg<Output = T> + Div<Output = T>,

Create a simple perspective transform, projecting to the plane z = -d.

1   0   0   0
0   1   0   0
0   0   1 -1/d
0   0   0   1

See https://drafts.csswg.org/css-transforms-2/#PerspectiveDefined.

§

impl<T, Src, Dst> Transform3D<T, Src, Dst>
where T: Copy + Add<Output = T> + Mul<Output = T>,

Methods for combining generic transformations

pub fn then<NewDst>( &self, other: &Transform3D<T, Dst, NewDst>, ) -> Transform3D<T, Src, NewDst>

Returns the multiplication of the two matrices such that mat’s transformation applies after self’s transformation.

Assuming row vectors, this is equivalent to self * mat

§

impl<T, Src, Dst> Transform3D<T, Src, Dst>
where T: Zero + One,

Methods for creating and combining translation transformations

pub fn translation(x: T, y: T, z: T) -> Transform3D<T, Src, Dst>

Create a 3d translation transform:

pub fn pre_translate(&self, v: Vector3D<T, Src>) -> Transform3D<T, Src, Dst>
where T: Copy + Add<Output = T> + Mul<Output = T>,

Returns a transform with a translation applied before self’s transformation.

pub fn then_translate(&self, v: Vector3D<T, Dst>) -> Transform3D<T, Src, Dst>
where T: Copy + Add<Output = T> + Mul<Output = T>,

Returns a transform with a translation applied after self’s transformation.

§

impl<T, Src, Dst> Transform3D<T, Src, Dst>
where T: Add<Output = T> + Sub<Output = T> + Mul<Output = T> + Div<Output = T> + Copy + Zero + One + Trig,

Methods for creating and combining rotation transformations

pub fn rotation(x: T, y: T, z: T, theta: Angle<T>) -> Transform3D<T, Src, Dst>

Create a 3d rotation transform from an angle / axis. The supplied axis must be normalized.

pub fn then_rotate( &self, x: T, y: T, z: T, theta: Angle<T>, ) -> Transform3D<T, Src, Dst>

Returns a transform with a rotation applied after self’s transformation.

pub fn pre_rotate( &self, x: T, y: T, z: T, theta: Angle<T>, ) -> Transform3D<T, Src, Dst>

Returns a transform with a rotation applied before self’s transformation.

§

impl<T, Src, Dst> Transform3D<T, Src, Dst>
where T: Zero + One,

Methods for creating and combining scale transformations

pub fn scale(x: T, y: T, z: T) -> Transform3D<T, Src, Dst>

Create a 3d scale transform:

pub fn pre_scale(&self, x: T, y: T, z: T) -> Transform3D<T, Src, Dst>
where T: Copy + Add<Output = T> + Mul<Output = T>,

Returns a transform with a scale applied before self’s transformation.

pub fn then_scale(&self, x: T, y: T, z: T) -> Transform3D<T, Src, Dst>
where T: Copy + Add<Output = T> + Mul<Output = T>,

Returns a transform with a scale applied after self’s transformation.

§