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