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(state:h);
175 self.m12.hash(state:h);
176 self.m13.hash(state:h);
177 self.m14.hash(state:h);
178 self.m21.hash(state:h);
179 self.m22.hash(state:h);
180 self.m23.hash(state:h);
181 self.m24.hash(state:h);
182 self.m31.hash(state:h);
183 self.m32.hash(state:h);
184 self.m33.hash(state:h);
185 self.m34.hash(state:h);
186 self.m41.hash(state:h);
187 self.m42.hash(state:h);
188 self.m43.hash(state:h);
189 self.m44.hash(state: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, approx_epsilon:eps) && self.m12.approx_eq_eps(&other.m12, approx_epsilon:eps) &&
1141 self.m13.approx_eq_eps(&other.m13, approx_epsilon:eps) && self.m14.approx_eq_eps(&other.m14, approx_epsilon:eps) &&
1142 self.m21.approx_eq_eps(&other.m21, approx_epsilon:eps) && self.m22.approx_eq_eps(&other.m22, approx_epsilon:eps) &&
1143 self.m23.approx_eq_eps(&other.m23, approx_epsilon:eps) && self.m24.approx_eq_eps(&other.m24, approx_epsilon:eps) &&
1144 self.m31.approx_eq_eps(&other.m31, approx_epsilon:eps) && self.m32.approx_eq_eps(&other.m32, approx_epsilon:eps) &&
1145 self.m33.approx_eq_eps(&other.m33, approx_epsilon:eps) && self.m34.approx_eq_eps(&other.m34, approx_epsilon:eps) &&
1146 self.m41.approx_eq_eps(&other.m41, approx_epsilon:eps) && self.m42.approx_eq_eps(&other.m42, approx_epsilon:eps) &&
1147 self.m43.approx_eq_eps(&other.m43, approx_epsilon:eps) && self.m44.approx_eq_eps(&other.m44, approx_epsilon: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}
1532