Struct euclid::Transform3D

source ·
#[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§

source§

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

source

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 ) -> Self

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,
);
source

pub fn new_2d(m11: T, m12: T, m21: T, m22: T, m41: T, m42: T) -> Self
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 representating the translation terms).

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

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

source§

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

source

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.

source

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.

source

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

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

source

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.

source

pub fn from_array(array: [T; 16]) -> Self

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).

source

pub fn from_arrays(array: [[T; 4]; 4]) -> Self

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).

source

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

Tag a unitless value with units.

source

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

Drop the units, preserving only the numeric value.

source

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

Returns the same transform with a different source unit.

source

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

Returns the same transform with a different destination unit.

source

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 self.is_2d() returns true beforehand.

source§

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

source

pub fn identity() -> Self

Creates an identity matrix:

1 0 0 0
0 1 0 0
0 0 1 0
0 0 0 1
source

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

source

pub fn perspective(d: T) -> Self
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.

source§

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

Methods for combining generic transformations

source

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

source§

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

Methods for creating and combining translation transformations

source

pub fn translation(x: T, y: T, z: T) -> Self

Create a 3d translation transform:

1 0 0 0
0 1 0 0
0 0 1 0
x y z 1
source

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

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

source

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

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

source§

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

Methods for creating and combining rotation transformations

source

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

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

source

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

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

source

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

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

source§

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

Methods for creating and combining scale transformations

source

pub fn scale(x: T, y: T, z: T) -> Self

Create a 3d scale transform:

x 0 0 0
0 y 0 0
0 0 z 0
0 0 0 1
source

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

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

source

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

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

source§

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

Methods for apply transformations to objects

source

pub fn transform_point2d_homogeneous( &self, p: Point2D<T, Src> ) -> HomogeneousVector<T, Dst>

Returns the homogeneous vector corresponding to the transformed 2d point.

The input point must be use the unit Src, and the returned point has the unit Dst.

source

pub fn transform_point2d(&self, p: Point2D<T, Src>) -> Option<Point2D<T, Dst>>
where T: Div<Output = T> + Zero + PartialOrd,

Returns the given 2d point transformed by this transform, if the transform makes sense, or None otherwise.

The input point must be use the unit Src, and the returned point has the unit Dst.

source

pub fn transform_vector2d(&self, v: Vector2D<T, Src>) -> Vector2D<T, Dst>

Returns the given 2d vector transformed by this matrix.

The input point must be use the unit Src, and the returned point has the unit Dst.

source

pub fn transform_point3d_homogeneous( &self, p: Point3D<T, Src> ) -> HomogeneousVector<T, Dst>

Returns the homogeneous vector corresponding to the transformed 3d point.

The input point must be use the unit Src, and the returned point has the unit Dst.

source

pub fn transform_point3d(&self, p: Point3D<T, Src>) -> Option<Point3D<T, Dst>>
where T: Div<Output = T> + Zero + PartialOrd,

Returns the given 3d point transformed by this transform, if the transform makes sense, or None otherwise.

The input point must be use the unit Src, and the returned point has the unit Dst.

source

pub fn transform_vector3d(&self, v: Vector3D<T, Src>) -> Vector3D<T, Dst>

Returns the given 3d vector transformed by this matrix.

The input point must be use the unit Src, and the returned point has the unit Dst.

source

pub fn outer_transformed_rect( &self, rect: &Rect<T, Src> ) -> Option<Rect<T, Dst>>
where T: Sub<Output = T> + Div<Output = T> + Zero + PartialOrd,

Returns a rectangle that encompasses the result of transforming the given rectangle by this transform, if the transform makes sense for it, or None otherwise.

source

pub fn outer_transformed_box2d( &self, b: &Box2D<T, Src> ) -> Option<Box2D<T, Dst>>
where T: Sub<Output = T> + Div<Output = T> + Zero + PartialOrd,

Returns a 2d box that encompasses the result of transforming the given box by this transform, if the transform makes sense for it, or None otherwise.

source

pub fn outer_transformed_box3d( &self, b: &Box3D<T, Src> ) -> Option<Box3D<T, Dst>>
where T: Sub<Output = T> + Div<Output = T> + Zero + PartialOrd,

Returns a 3d box that encompasses the result of transforming the given box by this transform, if the transform makes sense for it, or None otherwise.

source§

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

source

pub fn ortho(left: T, right: T, bottom: T, top: T, near: T, far: T) -> Self

Create an orthogonal projection transform.

source

pub fn is_backface_visible(&self) -> bool

Check whether shapes on the XY plane with Z pointing towards the screen transformed by this matrix would be facing back.

source

pub fn is_invertible(&self) -> bool

Returns whether it is possible to compute the inverse transform.

source

pub fn inverse(&self) -> Option<Transform3D<T, Dst, Src>>

Returns the inverse transform if possible.

source

pub fn determinant(&self) -> T

Compute the determinant of the transform.

source

pub fn mul_s(&self, x: T) -> Self

Multiplies all of the transform’s component by a scalar and returns the result.

source

pub fn from_scale(scale: Scale<T, Src, Dst>) -> Self

Convenience function to create a scale transform from a Scale.

source§

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

source

pub fn project_to_2d(&self) -> Self

Returns a projection of this transform in 2d space.

source§

impl<T: NumCast + Copy, Src, Dst> Transform3D<T, Src, Dst>

source

pub fn cast<NewT: NumCast>(&self) -> Transform3D<NewT, Src, Dst>

Cast from one numeric representation to another, preserving the units.

source

pub fn try_cast<NewT: NumCast>(&self) -> Option<Transform3D<NewT, Src, Dst>>

Fallible cast from one numeric representation to another, preserving the units.

source§

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

source

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

Returns true is this transform is approximately equal to the other one, using T’s default epsilon value.

The same as ApproxEq::approx_eq() but available without importing trait.

source

pub fn approx_eq_eps(&self, other: &Self, eps: &T) -> bool

Returns true is this transform is approximately equal to the other one, using a provided epsilon value.

The same as ApproxEq::approx_eq_eps() but available without importing trait.

Trait Implementations§

source§

impl<T: ApproxEq<T>, Src, Dst> ApproxEq<T> for Transform3D<T, Src, Dst>

source§

fn approx_epsilon() -> T

Default epsilon value
source§

fn approx_eq_eps(&self, other: &Self, eps: &T) -> bool

Returns true is this object is approximately equal to the other one, using a provided epsilon value.
source§

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

Returns true is this object is approximately equal to the other one, using the approx_epsilon() epsilon value.
source§

impl<T: Clone, Src, Dst> Clone for Transform3D<T, Src, Dst>

source§

fn clone(&self) -> Self

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl<T, Src, Dst> Debug for Transform3D<T, Src, Dst>
where T: Copy + Debug + PartialEq + One + Zero,

source§

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

Formats the value using the given formatter. Read more
source§

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

source§

fn default() -> Self

Returns the identity transform.

source§

impl<T, Src, Dst> Hash for Transform3D<T, Src, Dst>
where T: Hash,

source§

fn hash<H: Hasher>(&self, h: &mut H)

Feeds this value into the given Hasher. Read more
1.3.0 · source§

fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher. Read more
source§

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

source§

fn into(self) -> Transform3D<T, Src, Dst>

Converts this type into the (usually inferred) input type.
source§

impl<T, Src, Dst> PartialEq for Transform3D<T, Src, Dst>
where T: PartialEq,

source§

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

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

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

source§

impl<T, Src, Dst> Eq for Transform3D<T, Src, Dst>
where T: Eq,

Auto Trait Implementations§

§

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

§

impl<T, Src, Dst> Send for Transform3D<T, Src, Dst>
where Dst: Send, Src: Send, T: Send,

§

impl<T, Src, Dst> Sync for Transform3D<T, Src, Dst>
where Dst: Sync, Src: Sync, T: Sync,

§

impl<T, Src, Dst> Unpin for Transform3D<T, Src, Dst>
where Dst: Unpin, Src: Unpin, T: Unpin,

§

impl<T, Src, Dst> UnwindSafe for Transform3D<T, Src, Dst>
where Dst: UnwindSafe, Src: UnwindSafe, T: UnwindSafe,

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.