euclid/
transform3d.rs

Help
1// Copyright 2013 The Servo Project Developers. See the COPYRIGHT
2// file at the top-level directory of this distribution.
3//
4// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
5// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
6// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
7// option. This file may not be copied, modified, or distributed
8// except according to those terms.
9
10#![allow(clippy::just_underscores_and_digits)]
11
12use super::{Angle, UnknownUnit};
13use crate::approxeq::ApproxEq;
14use crate::box2d::Box2D;
15use crate::box3d::Box3D;
16use crate::homogen::HomogeneousVector;
17use crate::num::{One, Zero};
18use crate::point::{point2, point3, Point2D, Point3D};
19use crate::rect::Rect;
20use crate::scale::Scale;
21use crate::transform2d::Transform2D;
22use crate::trig::Trig;
23use crate::vector::{vec2, vec3, Vector2D, Vector3D};
24
25use core::cmp::{Eq, PartialEq};
26use core::fmt;
27use core::hash::Hash;
28use core::marker::PhantomData;
29use core::ops::{Add, Div, Mul, Neg, Sub};
30
31#[cfg(feature = "bytemuck")]
32use bytemuck::{Pod, Zeroable};
33#[cfg(feature = "mint")]
34use mint;
35use num_traits::NumCast;
36#[cfg(feature = "serde")]
37use serde::{Deserialize, Serialize};
38
39/// A 3d transform stored as a column-major 4 by 4 matrix.
40///
41/// Transforms can be parametrized over the source and destination units, to describe a
42/// transformation from a space to another.
43/// For example, `Transform3D<f32, WorldSpace, ScreenSpace>::transform_point3d`
44/// takes a `Point3D<f32, WorldSpace>` and returns a `Point3D<f32, ScreenSpace>`.
45///
46/// Transforms expose a set of convenience methods for pre- and post-transformations.
47/// Pre-transformations (`pre_*` methods) correspond to adding an operation that is
48/// applied before the rest of the transformation, while post-transformations (`then_*`
49/// methods) add an operation that is applied after.
50///
51/// When translating `Transform3D` into general matrix representations, consider that the
52/// representation follows the column major notation with column vectors.
53///
54/// ```text
55///  |x'|   | m11 m12 m13 m14 |   |x|
56///  |y'|   | m21 m22 m23 m24 |   |y|
57///  |z'| = | m31 m32 m33 m34 | x |y|
58///  |w |   | m41 m42 m43 m44 |   |1|
59/// ```
60///
61/// The translation terms are `m41`, `m42` and `m43`.
62#[repr(C)]
63#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
64#[cfg_attr(
65    feature = "serde",
66    serde(bound(serialize = "T: Serialize", deserialize = "T: Deserialize<'de>"))
67)]
68#[rustfmt::skip]
69pub struct Transform3D<T, Src, Dst> {
70    pub m11: T, pub m12: T, pub m13: T, pub m14: T,
71    pub m21: T, pub m22: T, pub m23: T, pub m24: T,
72    pub m31: T, pub m32: T, pub m33: T, pub m34: T,
73    pub m41: T, pub m42: T, pub m43: T, pub m44: T,
74    #[doc(hidden)]
75    pub _unit: PhantomData<(Src, Dst)>,
76}
77
78#[cfg(feature = "arbitrary")]
79impl<'a, T, Src, Dst> arbitrary::Arbitrary<'a> for Transform3D<T, Src, Dst>
80where
81    T: arbitrary::Arbitrary<'a>,
82{
83    fn arbitrary(u: &mut arbitrary::Unstructured<'a>) -> arbitrary::Result<Self> {
84        let (m11, m12, m13, m14) = arbitrary::Arbitrary::arbitrary(u)?;
85        let (m21, m22, m23, m24) = arbitrary::Arbitrary::arbitrary(u)?;
86        let (m31, m32, m33, m34) = arbitrary::Arbitrary::arbitrary(u)?;
87        let (m41, m42, m43, m44) = arbitrary::Arbitrary::arbitrary(u)?;
88
89        Ok(Transform3D {
90            m11,
91            m12,
92            m13,
93            m14,
94            m21,
95            m22,
96            m23,
97            m24,
98            m31,
99            m32,
100            m33,
101            m34,
102            m41,
103            m42,
104            m43,
105            m44,
106            _unit: PhantomData,
107        })
108    }
109}
110
111#[cfg(feature = "bytemuck")]
112unsafe impl<T: Zeroable, Src, Dst> Zeroable for Transform3D<T, Src, Dst> {}
113
114#[cfg(feature = "bytemuck")]
115unsafe impl<T: Pod, Src: 'static, Dst: 'static> Pod for Transform3D<T, Src, Dst> {}
116
117impl<T: Copy, Src, Dst> Copy for Transform3D<T, Src, Dst> {}
118
119impl<T: Clone, Src, Dst> Clone for Transform3D<T, Src, Dst> {
120    fn clone(&self) -> Self {
121        Transform3D {
122            m11: self.m11.clone(),
123            m12: self.m12.clone(),
124            m13: self.m13.clone(),
125            m14: self.m14.clone(),
126            m21: self.m21.clone(),
127            m22: self.m22.clone(),
128            m23: self.m23.clone(),
129            m24: self.m24.clone(),
130            m31: self.m31.clone(),
131            m32: self.m32.clone(),
132            m33: self.m33.clone(),
133            m34: self.m34.clone(),
134            m41: self.m41.clone(),
135            m42: self.m42.clone(),
136            m43: self.m43.clone(),
137            m44: self.m44.clone(),
138            _unit: PhantomData,
139        }
140    }
141}
142
143impl<T, Src, Dst> Eq for Transform3D<T, Src, Dst> where T: Eq {}
144
145impl<T, Src, Dst> PartialEq for Transform3D<T, Src, Dst>
146where
147    T: PartialEq,
148{
149    fn eq(&self, other: &Self) -> bool {
150        self.m11 == other.m11
151            && self.m12 == other.m12
152            && self.m13 == other.m13
153            && self.m14 == other.m14
154            && self.m21 == other.m21
155            && self.m22 == other.m22
156            && self.m23 == other.m23
157            && self.m24 == other.m24
158            && self.m31 == other.m31
159            && self.m32 == other.m32
160            && self.m33 == other.m33
161            && self.m34 == other.m34
162            && self.m41 == other.m41
163            && self.m42 == other.m42
164            && self.m43 == other.m43
165            && self.m44 == other.m44
166    }
167}
168
169impl<T, Src, Dst> Hash for Transform3D<T, Src, Dst>
170where
171    T: Hash,
172{
173    fn hash<H: core::hash::Hasher>(&self, h: &mut H) {
174        self.m11.hash(h);
175        self.m12.hash(h);
176        self.m13.hash(h);
177        self.m14.hash(h);
178        self.m21.hash(h);
179        self.m22.hash(h);
180        self.m23.hash(h);
181        self.m24.hash(h);
182        self.m31.hash(h);
183        self.m32.hash(h);
184        self.m33.hash(h);
185        self.m34.hash(h);
186        self.m41.hash(h);
187        self.m42.hash(h);
188        self.m43.hash(h);
189        self.m44.hash(h);
190    }
191}
192
193impl<T, Src, Dst> Transform3D<T, Src, Dst> {
194    /// Create a transform specifying all of it's component as a 4 by 4 matrix.
195    ///
196    /// Components are specified following column-major-column-vector matrix notation.
197    /// For example, the translation terms m41, m42, m43 are the 13rd, 14th and 15th parameters.
198    ///
199    /// ```
200    /// use euclid::default::Transform3D;
201    /// let tx = 1.0;
202    /// let ty = 2.0;
203    /// let tz = 3.0;
204    /// let translation = Transform3D::new(
205    ///   1.0, 0.0, 0.0, 0.0,
206    ///   0.0, 1.0, 0.0, 0.0,
207    ///   0.0, 0.0, 1.0, 0.0,
208    ///   tx,  ty,  tz,  1.0,
209    /// );
210    /// ```
211    #[inline]
212    #[allow(clippy::too_many_arguments)]
213    #[rustfmt::skip]
214    pub const fn new(
215        m11: T, m12: T, m13: T, m14: T,
216        m21: T, m22: T, m23: T, m24: T,
217        m31: T, m32: T, m33: T, m34: T,
218        m41: T, m42: T, m43: T, m44: T,
219    ) -> Self {
220        Transform3D {
221            m11, m12, m13, m14,
222            m21, m22, m23, m24,
223            m31, m32, m33, m34,
224            m41, m42, m43, m44,
225            _unit: PhantomData,
226        }
227    }
228
229    /// Create a transform representing a 2d transformation from the components
230    /// of a 2 by 3 matrix transformation.
231    ///
232    /// Components follow the column-major-column-vector notation (m41 and m42
233    /// representing the translation terms).
234    ///
235    /// ```text
236    /// m11  m12   0   0
237    /// m21  m22   0   0
238    ///   0    0   1   0
239    /// m41  m42   0   1
240    /// ```
241    #[inline]
242    #[rustfmt::skip]
243    pub fn new_2d(m11: T, m12: T, m21: T, m22: T, m41: T, m42: T) -> Self
244    where
245        T: Zero + One,
246    {
247        let _0 = || T::zero();
248        let _1 = || T::one();
249
250        Self::new(
251            m11,  m12,  _0(), _0(),
252            m21,  m22,  _0(), _0(),
253            _0(), _0(), _1(), _0(),
254            m41,  m42,  _0(), _1()
255       )
256    }
257
258    /// Returns `true` if this transform can be represented with a `Transform2D`.
259    ///
260    /// See <https://drafts.csswg.org/css-transforms/#2d-transform>
261    #[inline]
262    pub fn is_2d(&self) -> bool
263    where
264        T: Zero + One + PartialEq,
265    {
266        let (_0, _1): (T, T) = (Zero::zero(), One::one());
267        self.m31 == _0
268            && self.m32 == _0
269            && self.m13 == _0
270            && self.m23 == _0
271            && self.m43 == _0
272            && self.m14 == _0
273            && self.m24 == _0
274            && self.m34 == _0
275            && self.m33 == _1
276            && self.m44 == _1
277    }
278}
279
280impl<T: Copy, Src, Dst> Transform3D<T, Src, Dst> {
281    /// Returns an array containing this transform's terms.
282    ///
283    /// The terms are laid out in the same order as they are
284    /// specified in `Transform3D::new`, that is following the
285    /// column-major-column-vector matrix notation.
286    ///
287    /// For example the translation terms are found on the
288    /// 13th, 14th and 15th slots of the array.
289    #[inline]
290    #[rustfmt::skip]
291    pub fn to_array(&self) -> [T; 16] {
292        [
293            self.m11, self.m12, self.m13, self.m14,
294            self.m21, self.m22, self.m23, self.m24,
295            self.m31, self.m32, self.m33, self.m34,
296            self.m41, self.m42, self.m43, self.m44
297        ]
298    }
299
300    /// Returns an array containing this transform's terms transposed.
301    ///
302    /// The terms are laid out in transposed order from the same order of
303    /// `Transform3D::new` and `Transform3D::to_array`, that is following
304    /// the row-major-column-vector matrix notation.
305    ///
306    /// For example the translation terms are found at indices 3, 7 and 11
307    /// of the array.
308    #[inline]
309    #[rustfmt::skip]
310    pub fn to_array_transposed(&self) -> [T; 16] {
311        [
312            self.m11, self.m21, self.m31, self.m41,
313            self.m12, self.m22, self.m32, self.m42,
314            self.m13, self.m23, self.m33, self.m43,
315            self.m14, self.m24, self.m34, self.m44
316        ]
317    }
318
319    /// Equivalent to `to_array` with elements packed four at a time
320    /// in an array of arrays.
321    #[inline]
322    #[rustfmt::skip]
323    pub fn to_arrays(&self) -> [[T; 4]; 4] {
324        [
325            [self.m11, self.m12, self.m13, self.m14],
326            [self.m21, self.m22, self.m23, self.m24],
327            [self.m31, self.m32, self.m33, self.m34],
328            [self.m41, self.m42, self.m43, self.m44],
329        ]
330    }
331
332    /// Equivalent to `to_array_transposed` with elements packed
333    /// four at a time in an array of arrays.
334    #[inline]
335    #[rustfmt::skip]
336    pub fn to_arrays_transposed(&self) -> [[T; 4]; 4] {
337        [
338            [self.m11, self.m21, self.m31, self.m41],
339            [self.m12, self.m22, self.m32, self.m42],
340            [self.m13, self.m23, self.m33, self.m43],
341            [self.m14, self.m24, self.m34, self.m44],
342        ]
343    }
344
345    /// Create a transform providing its components via an array
346    /// of 16 elements instead of as individual parameters.
347    ///
348    /// The order of the components corresponds to the
349    /// column-major-column-vector matrix notation (the same order
350    /// as `Transform3D::new`).
351    #[inline]
352    #[rustfmt::skip]
353    pub fn from_array(array: [T; 16]) -> Self {
354        Self::new(
355            array[0],  array[1],  array[2],  array[3],
356            array[4],  array[5],  array[6],  array[7],
357            array[8],  array[9],  array[10], array[11],
358            array[12], array[13], array[14], array[15],
359        )
360    }
361
362    /// Equivalent to `from_array` with elements packed four at a time
363    /// in an array of arrays.
364    ///
365    /// The order of the components corresponds to the
366    /// column-major-column-vector matrix notation (the same order
367    /// as `Transform3D::new`).
368    #[inline]
369    #[rustfmt::skip]
370    pub fn from_arrays(array: [[T; 4]; 4]) -> Self {
371        Self::new(
372            array[0][0], array[0][1], array[0][2], array[0][3],
373            array[1][0], array[1][1], array[1][2], array[1][3],
374            array[2][0], array[2][1], array[2][2], array[2][3],
375            array[3][0], array[3][1], array[3][2], array[3][3],
376        )
377    }
378
379    /// Tag a unitless value with units.
380    #[inline]
381    #[rustfmt::skip]
382    pub fn from_untyped(m: &Transform3D<T, UnknownUnit, UnknownUnit>) -> Self {
383        Transform3D::new(
384            m.m11, m.m12, m.m13, m.m14,
385            m.m21, m.m22, m.m23, m.m24,
386            m.m31, m.m32, m.m33, m.m34,
387            m.m41, m.m42, m.m43, m.m44,
388        )
389    }
390
391    /// Drop the units, preserving only the numeric value.
392    #[inline]
393    #[rustfmt::skip]
394    pub fn to_untyped(&self) -> Transform3D<T, UnknownUnit, UnknownUnit> {
395        Transform3D::new(
396            self.m11, self.m12, self.m13, self.m14,
397            self.m21, self.m22, self.m23, self.m24,
398            self.m31, self.m32, self.m33, self.m34,
399            self.m41, self.m42, self.m43, self.m44,
400        )
401    }
402
403    /// Returns the same transform with a different source unit.
404    #[inline]
405    #[rustfmt::skip]
406    pub fn with_source<NewSrc>(&self) -> Transform3D<T, NewSrc, Dst> {
407        Transform3D::new(
408            self.m11, self.m12, self.m13, self.m14,
409            self.m21, self.m22, self.m23, self.m24,
410            self.m31, self.m32, self.m33, self.m34,
411            self.m41, self.m42, self.m43, self.m44,
412        )
413    }
414
415    /// Returns the same transform with a different destination unit.
416    #[inline]
417    #[rustfmt::skip]
418    pub fn with_destination<NewDst>(&self) -> Transform3D<T, Src, NewDst> {
419        Transform3D::new(
420            self.m11, self.m12, self.m13, self.m14,
421            self.m21, self.m22, self.m23, self.m24,
422            self.m31, self.m32, self.m33, self.m34,
423            self.m41, self.m42, self.m43, self.m44,
424        )
425    }
426
427    /// Create a 2D transform picking the relevant terms from this transform.
428    ///
429    /// This method assumes that self represents a 2d transformation, callers
430    /// should check that [`is_2d`] returns `true` beforehand.
431    ///
432    /// [`is_2d`]: Self::is_2d
433    pub fn to_2d(&self) -> Transform2D<T, Src, Dst> {
434        Transform2D::new(self.m11, self.m12, self.m21, self.m22, self.m41, self.m42)
435    }
436}
437
438impl<T, Src, Dst> Transform3D<T, Src, Dst>
439where
440    T: Zero + One,
441{
442    /// Creates an identity matrix:
443    ///
444    /// ```text
445    /// 1 0 0 0
446    /// 0 1 0 0
447    /// 0 0 1 0
448    /// 0 0 0 1
449    /// ```
450    #[inline]
451    pub fn identity() -> Self {
452        Self::translation(T::zero(), T::zero(), T::zero())
453    }
454
455    /// Intentional not public, because it checks for exact equivalence
456    /// while most consumers will probably want some sort of approximate
457    /// equivalence to deal with floating-point errors.
458    #[inline]
459    fn is_identity(&self) -> bool
460    where
461        T: PartialEq,
462    {
463        *self == Self::identity()
464    }
465
466    /// Create a 2d skew transform.
467    ///
468    /// See <https://drafts.csswg.org/css-transforms/#funcdef-skew>
469    #[rustfmt::skip]
470    pub fn skew(alpha: Angle<T>, beta: Angle<T>) -> Self
471    where
472        T: Trig,
473    {
474        let _0 = || T::zero();
475        let _1 = || T::one();
476        let (sx, sy) = (beta.radians.tan(), alpha.radians.tan());
477
478        Self::new(
479            _1(), sx,   _0(), _0(),
480            sy,   _1(), _0(), _0(),
481            _0(), _0(), _1(), _0(),
482            _0(), _0(), _0(), _1(),
483        )
484    }
485
486    /// Create a simple perspective transform, projecting to the plane `z = -d`.
487    ///
488    /// ```text
489    /// 1   0   0   0
490    /// 0   1   0   0
491    /// 0   0   1 -1/d
492    /// 0   0   0   1
493    /// ```
494    ///
495    /// See <https://drafts.csswg.org/css-transforms-2/#PerspectiveDefined>.
496    pub fn perspective(d: T) -> Self
497    where
498        T: Neg<Output = T> + Div<Output = T>,
499    {
500        let _0 = || T::zero();
501        let _1 = || T::one();
502
503        Self::new(
504            _1(),
505            _0(),
506            _0(),
507            _0(),
508            _0(),
509            _1(),
510            _0(),
511            _0(),
512            _0(),
513            _0(),
514            _1(),
515            -_1() / d,
516            _0(),
517            _0(),
518            _0(),
519            _1(),
520        )
521    }
522}
523
524/// Methods for combining generic transformations
525impl<T, Src, Dst> Transform3D<T, Src, Dst>
526where
527    T: Copy + Add<Output = T> + Mul<Output = T>,
528{
529    /// Returns the multiplication of the two matrices such that mat's transformation
530    /// applies after self's transformation.
531    ///
532    /// Assuming row vectors, this is equivalent to self * mat
533    #[must_use]
534    #[rustfmt::skip]
535    pub fn then<NewDst>(&self, other: &Transform3D<T, Dst, NewDst>) -> Transform3D<T, Src, NewDst> {
536        Transform3D::new(
537            self.m11 * other.m11  +  self.m12 * other.m21  +  self.m13 * other.m31  +  self.m14 * other.m41,
538            self.m11 * other.m12  +  self.m12 * other.m22  +  self.m13 * other.m32  +  self.m14 * other.m42,
539            self.m11 * other.m13  +  self.m12 * other.m23  +  self.m13 * other.m33  +  self.m14 * other.m43,
540            self.m11 * other.m14  +  self.m12 * other.m24  +  self.m13 * other.m34  +  self.m14 * other.m44,
541
542            self.m21 * other.m11  +  self.m22 * other.m21  +  self.m23 * other.m31  +  self.m24 * other.m41,
543            self.m21 * other.m12  +  self.m22 * other.m22  +  self.m23 * other.m32  +  self.m24 * other.m42,
544            self.m21 * other.m13  +  self.m22 * other.m23  +  self.m23 * other.m33  +  self.m24 * other.m43,
545            self.m21 * other.m14  +  self.m22 * other.m24  +  self.m23 * other.m34  +  self.m24 * other.m44,
546
547            self.m31 * other.m11  +  self.m32 * other.m21  +  self.m33 * other.m31  +  self.m34 * other.m41,
548            self.m31 * other.m12  +  self.m32 * other.m22  +  self.m33 * other.m32  +  self.m34 * other.m42,
549            self.m31 * other.m13  +  self.m32 * other.m23  +  self.m33 * other.m33  +  self.m34 * other.m43,
550            self.m31 * other.m14  +  self.m32 * other.m24  +  self.m33 * other.m34  +  self.m34 * other.m44,
551
552            self.m41 * other.m11  +  self.m42 * other.m21  +  self.m43 * other.m31  +  self.m44 * other.m41,
553            self.m41 * other.m12  +  self.m42 * other.m22  +  self.m43 * other.m32  +  self.m44 * other.m42,
554            self.m41 * other.m13  +  self.m42 * other.m23  +  self.m43 * other.m33  +  self.m44 * other.m43,
555            self.m41 * other.m14  +  self.m42 * other.m24  +  self.m43 * other.m34  +  self.m44 * other.m44,
556        )
557    }
558}
559
560/// Methods for creating and combining translation transformations
561impl<T, Src, Dst> Transform3D<T, Src, Dst>
562where
563    T: Zero + One,
564{
565    /// Create a 3d translation transform:
566    ///
567    /// ```text
568    /// 1 0 0 0
569    /// 0 1 0 0
570    /// 0 0 1 0
571    /// x y z 1
572    /// ```
573    #[inline]
574    #[rustfmt::skip]
575    pub fn translation(x: T, y: T, z: T) -> Self {
576        let _0 = || T::zero();
577        let _1 = || T::one();
578
579        Self::new(
580            _1(), _0(), _0(), _0(),
581            _0(), _1(), _0(), _0(),
582            _0(), _0(), _1(), _0(),
583             x,    y,    z,   _1(),
584        )
585    }
586
587    /// Returns a transform with a translation applied before self's transformation.
588    #[must_use]
589    pub fn pre_translate(&self, v: Vector3D<T, Src>) -> Self
590    where
591        T: Copy + Add<Output = T> + Mul<Output = T>,
592    {
593        Transform3D::translation(v.x, v.y, v.z).then(self)
594    }
595
596    /// Returns a transform with a translation applied after self's transformation.
597    #[must_use]
598    pub fn then_translate(&self, v: Vector3D<T, Dst>) -> Self
599    where
600        T: Copy + Add<Output = T> + Mul<Output = T>,
601    {
602        self.then(&Transform3D::translation(v.x, v.y, v.z))
603    }
604}
605
606/// Methods for creating and combining rotation transformations
607impl<T, Src, Dst> Transform3D<T, Src, Dst>
608where
609    T: Copy
610        + Add<Output = T>
611        + Sub<Output = T>
612        + Mul<Output = T>
613        + Div<Output = T>
614        + Zero
615        + One
616        + Trig,
617{
618    /// Create a 3d rotation transform from an angle / axis.
619    /// The supplied axis must be normalized.
620    #[rustfmt::skip]
621    pub fn rotation(x: T, y: T, z: T, theta: Angle<T>) -> Self {
622        let (_0, _1): (T, T) = (Zero::zero(), One::one());
623        let _2 = _1 + _1;
624
625        let xx = x * x;
626        let yy = y * y;
627        let zz = z * z;
628
629        let half_theta = theta.get() / _2;
630        let sc = half_theta.sin() * half_theta.cos();
631        let sq = half_theta.sin() * half_theta.sin();
632
633        Transform3D::new(
634            _1 - _2 * (yy + zz) * sq,
635            _2 * (x * y * sq + z * sc),
636            _2 * (x * z * sq - y * sc),
637            _0,
638
639
640            _2 * (x * y * sq - z * sc),
641            _1 - _2 * (xx + zz) * sq,
642            _2 * (y * z * sq + x * sc),
643            _0,
644
645            _2 * (x * z * sq + y * sc),
646            _2 * (y * z * sq - x * sc),
647            _1 - _2 * (xx + yy) * sq,
648            _0,
649
650            _0,
651            _0,
652            _0,
653            _1
654        )
655    }
656
657    /// Returns a transform with a rotation applied after self's transformation.
658    #[must_use]
659    pub fn then_rotate(&self, x: T, y: T, z: T, theta: Angle<T>) -> Self {
660        self.then(&Transform3D::rotation(x, y, z, theta))
661    }
662
663    /// Returns a transform with a rotation applied before self's transformation.
664    #[must_use]
665    pub fn pre_rotate(&self, x: T, y: T, z: T, theta: Angle<T>) -> Self {
666        Transform3D::rotation(x, y, z, theta).then(self)
667    }
668}
669
670/// Methods for creating and combining scale transformations
671impl<T, Src, Dst> Transform3D<T, Src, Dst>
672where
673    T: Zero + One,
674{
675    /// Create a 3d scale transform:
676    ///
677    /// ```text
678    /// x 0 0 0
679    /// 0 y 0 0
680    /// 0 0 z 0
681    /// 0 0 0 1
682    /// ```
683    #[inline]
684    #[rustfmt::skip]
685    pub fn scale(x: T, y: T, z: T) -> Self {
686        let _0 = || T::zero();
687        let _1 = || T::one();
688
689        Self::new(
690             x,   _0(), _0(), _0(),
691            _0(),  y,   _0(), _0(),
692            _0(), _0(),  z,   _0(),
693            _0(), _0(), _0(), _1(),
694        )
695    }
696
697    /// Returns a transform with a scale applied before self's transformation.
698    #[must_use]
699    #[rustfmt::skip]
700    pub fn pre_scale(&self, x: T, y: T, z: T) -> Self
701    where
702        T: Copy + Add<Output = T> + Mul<Output = T>,
703    {
704        Transform3D::new(
705            self.m11 * x, self.m12 * x, self.m13 * x, self.m14 * x,
706            self.m21 * y, self.m22 * y, self.m23 * y, self.m24 * y,
707            self.m31 * z, self.m32 * z, self.m33 * z, self.m34 * z,
708            self.m41    , self.m42,     self.m43,     self.m44
709        )
710    }
711
712    /// Returns a transform with a scale applied after self's transformation.
713    #[must_use]
714    pub fn then_scale(&self, x: T, y: T, z: T) -> Self
715    where
716        T: Copy + Add<Output = T> + Mul<Output = T>,
717    {
718        self.then(&Transform3D::scale(x, y, z))
719    }
720}
721
722/// Methods for apply transformations to objects
723impl<T, Src, Dst> Transform3D<T, Src, Dst>
724where
725    T: Copy + Add<Output = T> + Mul<Output = T>,
726{
727    /// Returns the homogeneous vector corresponding to the transformed 2d point.
728    ///
729    /// The input point must be use the unit Src, and the returned point has the unit Dst.
730    #[inline]
731    #[rustfmt::skip]
732    pub fn transform_point2d_homogeneous(
733        &self, p: Point2D<T, Src>
734    ) -> HomogeneousVector<T, Dst> {
735        let x = p.x * self.m11 + p.y * self.m21 + self.m41;
736        let y = p.x * self.m12 + p.y * self.m22 + self.m42;
737        let z = p.x * self.m13 + p.y * self.m23 + self.m43;
738        let w = p.x * self.m14 + p.y * self.m24 + self.m44;
739
740        HomogeneousVector::new(x, y, z, w)
741    }
742
743    /// Returns the given 2d point transformed by this transform, if the transform makes sense,
744    /// or `None` otherwise.
745    ///
746    /// The input point must be use the unit Src, and the returned point has the unit Dst.
747    #[inline]
748    pub fn transform_point2d(&self, p: Point2D<T, Src>) -> Option<Point2D<T, Dst>>
749    where
750        T: Div<Output = T> + Zero + PartialOrd,
751    {
752        //Note: could use `transform_point2d_homogeneous()` but it would waste the calculus of `z`
753        let w = p.x * self.m14 + p.y * self.m24 + self.m44;
754        if w > T::zero() {
755            let x = p.x * self.m11 + p.y * self.m21 + self.m41;
756            let y = p.x * self.m12 + p.y * self.m22 + self.m42;
757
758            Some(Point2D::new(x / w, y / w))
759        } else {
760            None
761        }
762    }
763
764    /// Returns the given 2d vector transformed by this matrix.
765    ///
766    /// The input point must be use the unit Src, and the returned point has the unit Dst.
767    #[inline]
768    pub fn transform_vector2d(&self, v: Vector2D<T, Src>) -> Vector2D<T, Dst> {
769        vec2(
770            v.x * self.m11 + v.y * self.m21,
771            v.x * self.m12 + v.y * self.m22,
772        )
773    }
774
775    /// Returns the homogeneous vector corresponding to the transformed 3d point.
776    ///
777    /// The input point must be use the unit Src, and the returned point has the unit Dst.
778    #[inline]
779    pub fn transform_point3d_homogeneous(&self, p: Point3D<T, Src>) -> HomogeneousVector<T, Dst> {
780        let x = p.x * self.m11 + p.y * self.m21 + p.z * self.m31 + self.m41;
781        let y = p.x * self.m12 + p.y * self.m22 + p.z * self.m32 + self.m42;
782        let z = p.x * self.m13 + p.y * self.m23 + p.z * self.m33 + self.m43;
783        let w = p.x * self.m14 + p.y * self.m24 + p.z * self.m34 + self.m44;
784
785        HomogeneousVector::new(x, y, z, w)
786    }
787
788    /// Returns the given 3d point transformed by this transform, if the transform makes sense,
789    /// or `None` otherwise.
790    ///
791    /// The input point must be use the unit Src, and the returned point has the unit Dst.
792    #[inline]
793    pub fn transform_point3d(&self, p: Point3D<T, Src>) -> Option<Point3D<T, Dst>>
794    where
795        T: Div<Output = T> + Zero + PartialOrd,
796    {
797        self.transform_point3d_homogeneous(p).to_point3d()
798    }
799
800    /// Returns the given 3d vector transformed by this matrix.
801    ///
802    /// The input point must be use the unit Src, and the returned point has the unit Dst.
803    #[inline]
804    pub fn transform_vector3d(&self, v: Vector3D<T, Src>) -> Vector3D<T, Dst> {
805        vec3(
806            v.x * self.m11 + v.y * self.m21 + v.z * self.m31,
807            v.x * self.m12 + v.y * self.m22 + v.z * self.m32,
808            v.x * self.m13 + v.y * self.m23 + v.z * self.m33,
809        )
810    }
811
812    /// Returns a rectangle that encompasses the result of transforming the given rectangle by this
813    /// transform, if the transform makes sense for it, or `None` otherwise.
814    pub fn outer_transformed_rect(&self, rect: &Rect<T, Src>) -> Option<Rect<T, Dst>>
815    where
816        T: Sub<Output = T> + Div<Output = T> + Zero + PartialOrd,
817    {
818        let min = rect.min();
819        let max = rect.max();
820        Some(Rect::from_points(&[
821            self.transform_point2d(min)?,
822            self.transform_point2d(max)?,
823            self.transform_point2d(point2(max.x, min.y))?,
824            self.transform_point2d(point2(min.x, max.y))?,
825        ]))
826    }
827
828    /// Returns a 2d box that encompasses the result of transforming the given box by this
829    /// transform, if the transform makes sense for it, or `None` otherwise.
830    pub fn outer_transformed_box2d(&self, b: &Box2D<T, Src>) -> Option<Box2D<T, Dst>>
831    where
832        T: Sub<Output = T> + Div<Output = T> + Zero + PartialOrd,
833    {
834        Some(Box2D::from_points(&[
835            self.transform_point2d(b.min)?,
836            self.transform_point2d(b.max)?,
837            self.transform_point2d(point2(b.max.x, b.min.y))?,
838            self.transform_point2d(point2(b.min.x, b.max.y))?,
839        ]))
840    }
841
842    /// Returns a 3d box that encompasses the result of transforming the given box by this
843    /// transform, if the transform makes sense for it, or `None` otherwise.
844    pub fn outer_transformed_box3d(&self, b: &Box3D<T, Src>) -> Option<Box3D<T, Dst>>
845    where
846        T: Sub<Output = T> + Div<Output = T> + Zero + PartialOrd,
847    {
848        Some(Box3D::from_points(&[
849            self.transform_point3d(point3(b.min.x, b.min.y, b.min.z))?,
850            self.transform_point3d(point3(b.min.x, b.min.y, b.max.z))?,
851            self.transform_point3d(point3(b.min.x, b.max.y, b.min.z))?,
852            self.transform_point3d(point3(b.min.x, b.max.y, b.max.z))?,
853            self.transform_point3d(point3(b.max.x, b.min.y, b.min.z))?,
854            self.transform_point3d(point3(b.max.x, b.min.y, b.max.z))?,
855            self.transform_point3d(point3(b.max.x, b.max.y, b.min.z))?,
856            self.transform_point3d(point3(b.max.x, b.max.y, b.max.z))?,
857        ]))
858    }
859}
860
861impl<T, Src, Dst> Transform3D<T, Src, Dst>
862where
863    T: Copy
864        + Add<T, Output = T>
865        + Sub<T, Output = T>
866        + Mul<T, Output = T>
867        + Div<T, Output = T>
868        + Neg<Output = T>
869        + PartialOrd
870        + One
871        + Zero,
872{
873    /// Create an orthogonal projection transform.
874    #[rustfmt::skip]
875    pub fn ortho(left: T, right: T,
876                 bottom: T, top: T,
877                 near: T, far: T) -> Self {
878        let tx = -((right + left) / (right - left));
879        let ty = -((top + bottom) / (top - bottom));
880        let tz = -((far + near) / (far - near));
881
882        let (_0, _1): (T, T) = (Zero::zero(), One::one());
883        let _2 = _1 + _1;
884        Transform3D::new(
885            _2 / (right - left), _0                 , _0                , _0,
886            _0                 , _2 / (top - bottom), _0                , _0,
887            _0                 , _0                 , -_2 / (far - near), _0,
888            tx                 , ty                 , tz                , _1
889        )
890    }
891
892    /// Check whether shapes on the XY plane with Z pointing towards the
893    /// screen transformed by this matrix would be facing back.
894    #[rustfmt::skip]
895    pub fn is_backface_visible(&self) -> bool {
896        // inverse().m33 < 0;
897        let det = self.determinant();
898        let m33 = self.m12 * self.m24 * self.m41 - self.m14 * self.m22 * self.m41 +
899                  self.m14 * self.m21 * self.m42 - self.m11 * self.m24 * self.m42 -
900                  self.m12 * self.m21 * self.m44 + self.m11 * self.m22 * self.m44;
901        let _0: T = Zero::zero();
902        (m33 * det) < _0
903    }
904
905    /// Returns whether it is possible to compute the inverse transform.
906    #[inline]
907    pub fn is_invertible(&self) -> bool {
908        self.determinant() != Zero::zero()
909    }
910
911    /// Returns the inverse transform if possible.
912    pub fn inverse(&self) -> Option<Transform3D<T, Dst, Src>> {
913        let det = self.determinant();
914
915        if det == Zero::zero() {
916            return None;
917        }
918
919        // todo(gw): this could be made faster by special casing
920        // for simpler transform types.
921        #[rustfmt::skip]
922        let m = Transform3D::new(
923            self.m23*self.m34*self.m42 - self.m24*self.m33*self.m42 +
924            self.m24*self.m32*self.m43 - self.m22*self.m34*self.m43 -
925            self.m23*self.m32*self.m44 + self.m22*self.m33*self.m44,
926
927            self.m14*self.m33*self.m42 - self.m13*self.m34*self.m42 -
928            self.m14*self.m32*self.m43 + self.m12*self.m34*self.m43 +
929            self.m13*self.m32*self.m44 - self.m12*self.m33*self.m44,
930
931            self.m13*self.m24*self.m42 - self.m14*self.m23*self.m42 +
932            self.m14*self.m22*self.m43 - self.m12*self.m24*self.m43 -
933            self.m13*self.m22*self.m44 + self.m12*self.m23*self.m44,
934
935            self.m14*self.m23*self.m32 - self.m13*self.m24*self.m32 -
936            self.m14*self.m22*self.m33 + self.m12*self.m24*self.m33 +
937            self.m13*self.m22*self.m34 - self.m12*self.m23*self.m34,
938
939            self.m24*self.m33*self.m41 - self.m23*self.m34*self.m41 -
940            self.m24*self.m31*self.m43 + self.m21*self.m34*self.m43 +
941            self.m23*self.m31*self.m44 - self.m21*self.m33*self.m44,
942
943            self.m13*self.m34*self.m41 - self.m14*self.m33*self.m41 +
944            self.m14*self.m31*self.m43 - self.m11*self.m34*self.m43 -
945            self.m13*self.m31*self.m44 + self.m11*self.m33*self.m44,
946
947            self.m14*self.m23*self.m41 - self.m13*self.m24*self.m41 -
948            self.m14*self.m21*self.m43 + self.m11*self.m24*self.m43 +
949            self.m13*self.m21*self.m44 - self.m11*self.m23*self.m44,
950
951            self.m13*self.m24*self.m31 - self.m14*self.m23*self.m31 +
952            self.m14*self.m21*self.m33 - self.m11*self.m24*self.m33 -
953            self.m13*self.m21*self.m34 + self.m11*self.m23*self.m34,
954
955            self.m22*self.m34*self.m41 - self.m24*self.m32*self.m41 +
956            self.m24*self.m31*self.m42 - self.m21*self.m34*self.m42 -
957            self.m22*self.m31*self.m44 + self.m21*self.m32*self.m44,
958
959            self.m14*self.m32*self.m41 - self.m12*self.m34*self.m41 -
960            self.m14*self.m31*self.m42 + self.m11*self.m34*self.m42 +
961            self.m12*self.m31*self.m44 - self.m11*self.m32*self.m44,
962
963            self.m12*self.m24*self.m41 - self.m14*self.m22*self.m41 +
964            self.m14*self.m21*self.m42 - self.m11*self.m24*self.m42 -
965            self.m12*self.m21*self.m44 + self.m11*self.m22*self.m44,
966
967            self.m14*self.m22*self.m31 - self.m12*self.m24*self.m31 -
968            self.m14*self.m21*self.m32 + self.m11*self.m24*self.m32 +
969            self.m12*self.m21*self.m34 - self.m11*self.m22*self.m34,
970
971            self.m23*self.m32*self.m41 - self.m22*self.m33*self.m41 -
972            self.m23*self.m31*self.m42 + self.m21*self.m33*self.m42 +
973            self.m22*self.m31*self.m43 - self.m21*self.m32*self.m43,
974
975            self.m12*self.m33*self.m41 - self.m13*self.m32*self.m41 +
976            self.m13*self.m31*self.m42 - self.m11*self.m33*self.m42 -
977            self.m12*self.m31*self.m43 + self.m11*self.m32*self.m43,
978
979            self.m13*self.m22*self.m41 - self.m12*self.m23*self.m41 -
980            self.m13*self.m21*self.m42 + self.m11*self.m23*self.m42 +
981            self.m12*self.m21*self.m43 - self.m11*self.m22*self.m43,
982
983            self.m12*self.m23*self.m31 - self.m13*self.m22*self.m31 +
984            self.m13*self.m21*self.m32 - self.m11*self.m23*self.m32 -
985            self.m12*self.m21*self.m33 + self.m11*self.m22*self.m33
986        );
987
988        let _1: T = One::one();
989        Some(m.mul_s(_1 / det))
990    }
991
992    /// Compute the determinant of the transform.
993    #[rustfmt::skip]
994    pub fn determinant(&self) -> T {
995        self.m14 * self.m23 * self.m32 * self.m41 -
996        self.m13 * self.m24 * self.m32 * self.m41 -
997        self.m14 * self.m22 * self.m33 * self.m41 +
998        self.m12 * self.m24 * self.m33 * self.m41 +
999        self.m13 * self.m22 * self.m34 * self.m41 -
1000        self.m12 * self.m23 * self.m34 * self.m41 -
1001        self.m14 * self.m23 * self.m31 * self.m42 +
1002        self.m13 * self.m24 * self.m31 * self.m42 +
1003        self.m14 * self.m21 * self.m33 * self.m42 -
1004        self.m11 * self.m24 * self.m33 * self.m42 -
1005        self.m13 * self.m21 * self.m34 * self.m42 +
1006        self.m11 * self.m23 * self.m34 * self.m42 +
1007        self.m14 * self.m22 * self.m31 * self.m43 -
1008        self.m12 * self.m24 * self.m31 * self.m43 -
1009        self.m14 * self.m21 * self.m32 * self.m43 +
1010        self.m11 * self.m24 * self.m32 * self.m43 +
1011        self.m12 * self.m21 * self.m34 * self.m43 -
1012        self.m11 * self.m22 * self.m34 * self.m43 -
1013        self.m13 * self.m22 * self.m31 * self.m44 +
1014        self.m12 * self.m23 * self.m31 * self.m44 +
1015        self.m13 * self.m21 * self.m32 * self.m44 -
1016        self.m11 * self.m23 * self.m32 * self.m44 -
1017        self.m12 * self.m21 * self.m33 * self.m44 +
1018        self.m11 * self.m22 * self.m33 * self.m44
1019    }
1020
1021    /// Multiplies all of the transform's component by a scalar and returns the result.
1022    #[must_use]
1023    #[rustfmt::skip]
1024    pub fn mul_s(&self, x: T) -> Self {
1025        Transform3D::new(
1026            self.m11 * x, self.m12 * x, self.m13 * x, self.m14 * x,
1027            self.m21 * x, self.m22 * x, self.m23 * x, self.m24 * x,
1028            self.m31 * x, self.m32 * x, self.m33 * x, self.m34 * x,
1029            self.m41 * x, self.m42 * x, self.m43 * x, self.m44 * x
1030        )
1031    }
1032
1033    /// Convenience function to create a scale transform from a `Scale`.
1034    pub fn from_scale(scale: Scale<T, Src, Dst>) -> Self {
1035        Transform3D::scale(scale.get(), scale.get(), scale.get())
1036    }
1037}
1038
1039impl<T, Src, Dst> Transform3D<T, Src, Dst>
1040where
1041    T: Copy + Mul<Output = T> + Div<Output = T> + Zero + One + PartialEq,
1042{
1043    /// Returns a projection of this transform in 2d space.
1044    pub fn project_to_2d(&self) -> Self {
1045        let (_0, _1): (T, T) = (Zero::zero(), One::one());
1046
1047        let mut result = self.clone();
1048
1049        result.m31 = _0;
1050        result.m32 = _0;
1051        result.m13 = _0;
1052        result.m23 = _0;
1053        result.m33 = _1;
1054        result.m43 = _0;
1055        result.m34 = _0;
1056
1057        // Try to normalize perspective when possible to convert to a 2d matrix.
1058        // Some matrices, such as those derived from perspective transforms, can
1059        // modify m44 from 1, while leaving the rest of the fourth column
1060        // (m14, m24) at 0. In this case, after resetting the third row and
1061        // third column above, the value of m44 functions only to scale the
1062        // coordinate transform divide by W. The matrix can be converted to
1063        // a true 2D matrix by normalizing out the scaling effect of m44 on
1064        // the remaining components ahead of time.
1065        if self.m14 == _0 && self.m24 == _0 && self.m44 != _0 && self.m44 != _1 {
1066            let scale = _1 / self.m44;
1067            result.m11 = result.m11 * scale;
1068            result.m12 = result.m12 * scale;
1069            result.m21 = result.m21 * scale;
1070            result.m22 = result.m22 * scale;
1071            result.m41 = result.m41 * scale;
1072            result.m42 = result.m42 * scale;
1073            result.m44 = _1;
1074        }
1075
1076        result
1077    }
1078}
1079
1080impl<T: NumCast + Copy, Src, Dst> Transform3D<T, Src, Dst> {
1081    /// Cast from one numeric representation to another, preserving the units.
1082    #[inline]
1083    pub fn cast<NewT: NumCast>(&self) -> Transform3D<NewT, Src, Dst> {
1084        self.try_cast().unwrap()
1085    }
1086
1087    /// Fallible cast from one numeric representation to another, preserving the units.
1088    #[rustfmt::skip]
1089    pub fn try_cast<NewT: NumCast>(&self) -> Option<Transform3D<NewT, Src, Dst>> {
1090        match (NumCast::from(self.m11), NumCast::from(self.m12),
1091               NumCast::from(self.m13), NumCast::from(self.m14),
1092               NumCast::from(self.m21), NumCast::from(self.m22),
1093               NumCast::from(self.m23), NumCast::from(self.m24),
1094               NumCast::from(self.m31), NumCast::from(self.m32),
1095               NumCast::from(self.m33), NumCast::from(self.m34),
1096               NumCast::from(self.m41), NumCast::from(self.m42),
1097               NumCast::from(self.m43), NumCast::from(self.m44)) {
1098            (Some(m11), Some(m12), Some(m13), Some(m14),
1099             Some(m21), Some(m22), Some(m23), Some(m24),
1100             Some(m31), Some(m32), Some(m33), Some(m34),
1101             Some(m41), Some(m42), Some(m43), Some(m44)) => {
1102                Some(Transform3D::new(m11, m12, m13, m14,
1103                                      m21, m22, m23, m24,
1104                                      m31, m32, m33, m34,
1105                                      m41, m42, m43, m44))
1106            },
1107            _ => None
1108        }
1109    }
1110}
1111
1112impl<T: ApproxEq<T>, Src, Dst> Transform3D<T, Src, Dst> {
1113    /// Returns `true` if this transform is approximately equal to the other one, using
1114    /// `T`'s default epsilon value.
1115    ///
1116    /// The same as [`ApproxEq::approx_eq`] but available without importing trait.
1117    #[inline]
1118    pub fn approx_eq(&self, other: &Self) -> bool {
1119        <Self as ApproxEq<T>>::approx_eq(&self, &other)
1120    }
1121
1122    /// Returns `true` if this transform is approximately equal to the other one, using
1123    /// a provided epsilon value.
1124    ///
1125    /// The same as [`ApproxEq::approx_eq_eps`] but available without importing trait.
1126    #[inline]
1127    pub fn approx_eq_eps(&self, other: &Self, eps: &T) -> bool {
1128        <Self as ApproxEq<T>>::approx_eq_eps(&self, &other, &eps)
1129    }
1130}
1131
1132impl<T: ApproxEq<T>, Src, Dst> ApproxEq<T> for Transform3D<T, Src, Dst> {
1133    #[inline]
1134    fn approx_epsilon() -> T {
1135        T::approx_epsilon()
1136    }
1137
1138    #[rustfmt::skip]
1139    fn approx_eq_eps(&self, other: &Self, eps: &T) -> bool {
1140        self.m11.approx_eq_eps(&other.m11, eps) && self.m12.approx_eq_eps(&other.m12, eps) &&
1141        self.m13.approx_eq_eps(&other.m13, eps) && self.m14.approx_eq_eps(&other.m14, eps) &&
1142        self.m21.approx_eq_eps(&other.m21, eps) && self.m22.approx_eq_eps(&other.m22, eps) &&
1143        self.m23.approx_eq_eps(&other.m23, eps) && self.m24.approx_eq_eps(&other.m24, eps) &&
1144        self.m31.approx_eq_eps(&other.m31, eps) && self.m32.approx_eq_eps(&other.m32, eps) &&
1145        self.m33.approx_eq_eps(&other.m33, eps) && self.m34.approx_eq_eps(&other.m34, eps) &&
1146        self.m41.approx_eq_eps(&other.m41, eps) && self.m42.approx_eq_eps(&other.m42, eps) &&
1147        self.m43.approx_eq_eps(&other.m43, eps) && self.m44.approx_eq_eps(&other.m44, eps)
1148    }
1149}
1150
1151impl<T, Src, Dst> Default for Transform3D<T, Src, Dst>
1152where
1153    T: Zero + One,
1154{
1155    /// Returns the [identity transform](Self::identity).
1156    fn default() -> Self {
1157        Self::identity()
1158    }
1159}
1160
1161impl<T, Src, Dst> fmt::Debug for Transform3D<T, Src, Dst>
1162where
1163    T: Copy + fmt::Debug + PartialEq + One + Zero,
1164{
1165    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1166        if self.is_identity() {
1167            write!(f, "[I]")
1168        } else {
1169            self.to_array().fmt(f)
1170        }
1171    }
1172}
1173
1174#[cfg(feature = "mint")]
1175impl<T, Src, Dst> From<mint::RowMatrix4<T>> for Transform3D<T, Src, Dst> {
1176    #[rustfmt::skip]
1177    fn from(m: mint::RowMatrix4<T>) -> Self {
1178        Transform3D {
1179            m11: m.x.x, m12: m.x.y, m13: m.x.z, m14: m.x.w,
1180            m21: m.y.x, m22: m.y.y, m23: m.y.z, m24: m.y.w,
1181            m31: m.z.x, m32: m.z.y, m33: m.z.z, m34: m.z.w,
1182            m41: m.w.x, m42: m.w.y, m43: m.w.z, m44: m.w.w,
1183            _unit: PhantomData,
1184        }
1185    }
1186}
1187#[cfg(feature = "mint")]
1188impl<T, Src, Dst> From<Transform3D<T, Src, Dst>> for mint::RowMatrix4<T> {
1189    #[rustfmt::skip]
1190    fn from(t: Transform3D<T, Src, Dst>) -> Self {
1191        mint::RowMatrix4 {
1192            x: mint::Vector4 { x: t.m11, y: t.m12, z: t.m13, w: t.m14 },
1193            y: mint::Vector4 { x: t.m21, y: t.m22, z: t.m23, w: t.m24 },
1194            z: mint::Vector4 { x: t.m31, y: t.m32, z: t.m33, w: t.m34 },
1195            w: mint::Vector4 { x: t.m41, y: t.m42, z: t.m43, w: t.m44 },
1196        }
1197    }
1198}
1199
1200#[cfg(test)]
1201mod tests {
1202    use super::*;
1203    use crate::approxeq::ApproxEq;
1204    use crate::default;
1205    use crate::{point2, point3};
1206
1207    use core::f32::consts::{FRAC_PI_2, PI};
1208
1209    type Mf32 = default::Transform3D<f32>;
1210
1211    // For convenience.
1212    fn rad(v: f32) -> Angle<f32> {
1213        Angle::radians(v)
1214    }
1215
1216    #[test]
1217    pub fn test_translation() {
1218        let t1 = Mf32::translation(1.0, 2.0, 3.0);
1219        let t2 = Mf32::identity().pre_translate(vec3(1.0, 2.0, 3.0));
1220        let t3 = Mf32::identity().then_translate(vec3(1.0, 2.0, 3.0));
1221        assert_eq!(t1, t2);
1222        assert_eq!(t1, t3);
1223
1224        assert_eq!(
1225            t1.transform_point3d(point3(1.0, 1.0, 1.0)),
1226            Some(point3(2.0, 3.0, 4.0))
1227        );
1228        assert_eq!(
1229            t1.transform_point2d(point2(1.0, 1.0)),
1230            Some(point2(2.0, 3.0))
1231        );
1232
1233        assert_eq!(t1.then(&t1), Mf32::translation(2.0, 4.0, 6.0));
1234
1235        assert!(!t1.is_2d());
1236        assert_eq!(
1237            Mf32::translation(1.0, 2.0, 3.0).to_2d(),
1238            Transform2D::translation(1.0, 2.0)
1239        );
1240    }
1241
1242    #[test]
1243    pub fn test_rotation() {
1244        let r1 = Mf32::rotation(0.0, 0.0, 1.0, rad(FRAC_PI_2));
1245        let r2 = Mf32::identity().pre_rotate(0.0, 0.0, 1.0, rad(FRAC_PI_2));
1246        let r3 = Mf32::identity().then_rotate(0.0, 0.0, 1.0, rad(FRAC_PI_2));
1247        assert_eq!(r1, r2);
1248        assert_eq!(r1, r3);
1249
1250        assert!(r1
1251            .transform_point3d(point3(1.0, 2.0, 3.0))
1252            .unwrap()
1253            .approx_eq(&point3(-2.0, 1.0, 3.0)));
1254        assert!(r1
1255            .transform_point2d(point2(1.0, 2.0))
1256            .unwrap()
1257            .approx_eq(&point2(-2.0, 1.0)));
1258
1259        assert!(r1
1260            .then(&r1)
1261            .approx_eq(&Mf32::rotation(0.0, 0.0, 1.0, rad(FRAC_PI_2 * 2.0))));
1262
1263        assert!(r1.is_2d());
1264        assert!(r1.to_2d().approx_eq(&Transform2D::rotation(rad(FRAC_PI_2))));
1265    }
1266
1267    #[test]
1268    pub fn test_scale() {
1269        let s1 = Mf32::scale(2.0, 3.0, 4.0);
1270        let s2 = Mf32::identity().pre_scale(2.0, 3.0, 4.0);
1271        let s3 = Mf32::identity().then_scale(2.0, 3.0, 4.0);
1272        assert_eq!(s1, s2);
1273        assert_eq!(s1, s3);
1274
1275        assert!(s1
1276            .transform_point3d(point3(2.0, 2.0, 2.0))
1277            .unwrap()
1278            .approx_eq(&point3(4.0, 6.0, 8.0)));
1279        assert!(s1
1280            .transform_point2d(point2(2.0, 2.0))
1281            .unwrap()
1282            .approx_eq(&point2(4.0, 6.0)));
1283
1284        assert_eq!(s1.then(&s1), Mf32::scale(4.0, 9.0, 16.0));
1285
1286        assert!(!s1.is_2d());
1287        assert_eq!(
1288            Mf32::scale(2.0, 3.0, 0.0).to_2d(),
1289            Transform2D::scale(2.0, 3.0)
1290        );
1291    }
1292
1293    #[test]
1294    pub fn test_pre_then_scale() {
1295        let m = Mf32::rotation(0.0, 0.0, 1.0, rad(FRAC_PI_2)).then_translate(vec3(6.0, 7.0, 8.0));
1296        let s = Mf32::scale(2.0, 3.0, 4.0);
1297        assert_eq!(m.then(&s), m.then_scale(2.0, 3.0, 4.0));
1298    }
1299
1300    #[test]
1301    #[rustfmt::skip]
1302    pub fn test_ortho() {
1303        let (left, right, bottom, top) = (0.0f32, 1.0f32, 0.1f32, 1.0f32);
1304        let (near, far) = (-1.0f32, 1.0f32);
1305        let result = Mf32::ortho(left, right, bottom, top, near, far);
1306        let expected = Mf32::new(
1307             2.0,  0.0,         0.0, 0.0,
1308             0.0,  2.22222222,  0.0, 0.0,
1309             0.0,  0.0,        -1.0, 0.0,
1310            -1.0, -1.22222222, -0.0, 1.0
1311        );
1312        assert!(result.approx_eq(&expected));
1313    }
1314
1315    #[test]
1316    pub fn test_is_2d() {
1317        assert!(Mf32::identity().is_2d());
1318        assert!(Mf32::rotation(0.0, 0.0, 1.0, rad(0.7854)).is_2d());
1319        assert!(!Mf32::rotation(0.0, 1.0, 0.0, rad(0.7854)).is_2d());
1320    }
1321
1322    #[test]
1323    #[rustfmt::skip]
1324    pub fn test_new_2d() {
1325        let m1 = Mf32::new_2d(1.0, 2.0, 3.0, 4.0, 5.0, 6.0);
1326        let m2 = Mf32::new(
1327            1.0, 2.0, 0.0, 0.0,
1328            3.0, 4.0, 0.0, 0.0,
1329            0.0, 0.0, 1.0, 0.0,
1330            5.0, 6.0, 0.0, 1.0
1331        );
1332        assert_eq!(m1, m2);
1333    }
1334
1335    #[test]
1336    pub fn test_inverse_simple() {
1337        let m1 = Mf32::identity();
1338        let m2 = m1.inverse().unwrap();
1339        assert!(m1.approx_eq(&m2));
1340    }
1341
1342    #[test]
1343    pub fn test_inverse_scale() {
1344        let m1 = Mf32::scale(1.5, 0.3, 2.1);
1345        let m2 = m1.inverse().unwrap();
1346        assert!(m1.then(&m2).approx_eq(&Mf32::identity()));
1347        assert!(m2.then(&m1).approx_eq(&Mf32::identity()));
1348    }
1349
1350    #[test]
1351    pub fn test_inverse_translate() {
1352        let m1 = Mf32::translation(-132.0, 0.3, 493.0);
1353        let m2 = m1.inverse().unwrap();
1354        assert!(m1.then(&m2).approx_eq(&Mf32::identity()));
1355        assert!(m2.then(&m1).approx_eq(&Mf32::identity()));
1356    }
1357
1358    #[test]
1359    pub fn test_inverse_rotate() {
1360        let m1 = Mf32::rotation(0.0, 1.0, 0.0, rad(1.57));
1361        let m2 = m1.inverse().unwrap();
1362        assert!(m1.then(&m2).approx_eq(&Mf32::identity()));
1363        assert!(m2.then(&m1).approx_eq(&Mf32::identity()));
1364    }
1365
1366    #[test]
1367    pub fn test_inverse_transform_point_2d() {
1368        let m1 = Mf32::translation(100.0, 200.0, 0.0);
1369        let m2 = m1.inverse().unwrap();
1370        assert!(m1.then(&m2).approx_eq(&Mf32::identity()));
1371        assert!(m2.then(&m1).approx_eq(&Mf32::identity()));
1372
1373        let p1 = point2(1000.0, 2000.0);
1374        let p2 = m1.transform_point2d(p1);
1375        assert_eq!(p2, Some(point2(1100.0, 2200.0)));
1376
1377        let p3 = m2.transform_point2d(p2.unwrap());
1378        assert_eq!(p3, Some(p1));
1379    }
1380
1381    #[test]
1382    fn test_inverse_none() {
1383        assert!(Mf32::scale(2.0, 0.0, 2.0).inverse().is_none());
1384        assert!(Mf32::scale(2.0, 2.0, 2.0).inverse().is_some());
1385    }
1386
1387    #[test]
1388    pub fn test_pre_post() {
1389        let m1 = default::Transform3D::identity()
1390            .then_scale(1.0, 2.0, 3.0)
1391            .then_translate(vec3(1.0, 2.0, 3.0));
1392        let m2 = default::Transform3D::identity()
1393            .pre_translate(vec3(1.0, 2.0, 3.0))
1394            .pre_scale(1.0, 2.0, 3.0);
1395        assert!(m1.approx_eq(&m2));
1396
1397        let r = Mf32::rotation(0.0, 0.0, 1.0, rad(FRAC_PI_2));
1398        let t = Mf32::translation(2.0, 3.0, 0.0);
1399
1400        let a = point3(1.0, 1.0, 1.0);
1401
1402        assert!(r
1403            .then(&t)
1404            .transform_point3d(a)
1405            .unwrap()
1406            .approx_eq(&point3(1.0, 4.0, 1.0)));
1407        assert!(t
1408            .then(&r)
1409            .transform_point3d(a)
1410            .unwrap()
1411            .approx_eq(&point3(-4.0, 3.0, 1.0)));
1412        assert!(t.then(&r).transform_point3d(a).unwrap().approx_eq(
1413            &r.transform_point3d(t.transform_point3d(a).unwrap())
1414                .unwrap()
1415        ));
1416    }
1417
1418    #[test]
1419    fn test_size_of() {
1420        use core::mem::size_of;
1421        assert_eq!(
1422            size_of::<default::Transform3D<f32>>(),
1423            16 * size_of::<f32>()
1424        );
1425        assert_eq!(
1426            size_of::<default::Transform3D<f64>>(),
1427            16 * size_of::<f64>()
1428        );
1429    }
1430
1431    #[test]
1432    #[rustfmt::skip]
1433    pub fn test_transform_associativity() {
1434        let m1 = Mf32::new(3.0, 2.0, 1.5, 1.0,
1435                           0.0, 4.5, -1.0, -4.0,
1436                           0.0, 3.5, 2.5, 40.0,
1437                           0.0, 3.0, 0.0, 1.0);
1438        let m2 = Mf32::new(1.0, -1.0, 3.0, 0.0,
1439                           -1.0, 0.5, 0.0, 2.0,
1440                           1.5, -2.0, 6.0, 0.0,
1441                           -2.5, 6.0, 1.0, 1.0);
1442
1443        let p = point3(1.0, 3.0, 5.0);
1444        let p1 = m1.then(&m2).transform_point3d(p).unwrap();
1445        let p2 = m2.transform_point3d(m1.transform_point3d(p).unwrap()).unwrap();
1446        assert!(p1.approx_eq(&p2));
1447    }
1448
1449    #[test]
1450    pub fn test_is_identity() {
1451        let m1 = default::Transform3D::identity();
1452        assert!(m1.is_identity());
1453        let m2 = m1.then_translate(vec3(0.1, 0.0, 0.0));
1454        assert!(!m2.is_identity());
1455    }
1456
1457    #[test]
1458    pub fn test_transform_vector() {
1459        // Translation does not apply to vectors.
1460        let m = Mf32::translation(1.0, 2.0, 3.0);
1461        let v1 = vec3(10.0, -10.0, 3.0);
1462        assert_eq!(v1, m.transform_vector3d(v1));
1463        // While it does apply to points.
1464        assert_ne!(Some(v1.to_point()), m.transform_point3d(v1.to_point()));
1465
1466        // same thing with 2d vectors/points
1467        let v2 = vec2(10.0, -5.0);
1468        assert_eq!(v2, m.transform_vector2d(v2));
1469        assert_ne!(Some(v2.to_point()), m.transform_point2d(v2.to_point()));
1470    }
1471
1472    #[test]
1473    pub fn test_is_backface_visible() {
1474        // backface is not visible for rotate-x 0 degree.
1475        let r1 = Mf32::rotation(1.0, 0.0, 0.0, rad(0.0));
1476        assert!(!r1.is_backface_visible());
1477        // backface is not visible for rotate-x 45 degree.
1478        let r1 = Mf32::rotation(1.0, 0.0, 0.0, rad(PI * 0.25));
1479        assert!(!r1.is_backface_visible());
1480        // backface is visible for rotate-x 180 degree.
1481        let r1 = Mf32::rotation(1.0, 0.0, 0.0, rad(PI));
1482        assert!(r1.is_backface_visible());
1483        // backface is visible for rotate-x 225 degree.
1484        let r1 = Mf32::rotation(1.0, 0.0, 0.0, rad(PI * 1.25));
1485        assert!(r1.is_backface_visible());
1486        // backface is not visible for non-inverseable matrix
1487        let r1 = Mf32::scale(2.0, 0.0, 2.0);
1488        assert!(!r1.is_backface_visible());
1489    }
1490
1491    #[test]
1492    pub fn test_homogeneous() {
1493        #[rustfmt::skip]
1494        let m = Mf32::new(
1495            1.0, 2.0, 0.5, 5.0,
1496            3.0, 4.0, 0.25, 6.0,
1497            0.5, -1.0, 1.0, -1.0,
1498            -1.0, 1.0, -1.0, 2.0,
1499        );
1500        assert_eq!(
1501            m.transform_point2d_homogeneous(point2(1.0, 2.0)),
1502            HomogeneousVector::new(6.0, 11.0, 0.0, 19.0),
1503        );
1504        assert_eq!(
1505            m.transform_point3d_homogeneous(point3(1.0, 2.0, 4.0)),
1506            HomogeneousVector::new(8.0, 7.0, 4.0, 15.0),
1507        );
1508    }
1509
1510    #[test]
1511    pub fn test_perspective_division() {
1512        let p = point2(1.0, 2.0);
1513        let mut m = Mf32::identity();
1514        assert!(m.transform_point2d(p).is_some());
1515        m.m44 = 0.0;
1516        assert_eq!(None, m.transform_point2d(p));
1517        m.m44 = 1.0;
1518        m.m24 = -1.0;
1519        assert_eq!(None, m.transform_point2d(p));
1520    }
1521
1522    #[cfg(feature = "mint")]
1523    #[test]
1524    pub fn test_mint() {
1525        let m1 = Mf32::rotation(0.0, 0.0, 1.0, rad(FRAC_PI_2));
1526        let mm: mint::RowMatrix4<_> = m1.into();
1527        let m2 = Mf32::from(mm);
1528
1529        assert_eq!(m1, m2);
1530    }
1531}
euclid/transform3d.rs

euclid/
transform3d.rs
