nalgebra/geometry/
perspective.rs

1#[cfg(feature = "arbitrary")]
2use quickcheck::{Arbitrary, Gen};
3#[cfg(feature = "rand-no-std")]
4use rand::{
5    distributions::{Distribution, Standard},
6    Rng,
7};
8
9#[cfg(feature = "serde-serialize-no-std")]
10use serde::{Deserialize, Deserializer, Serialize, Serializer};
11use std::fmt;
12
13use simba::scalar::RealField;
14
15use crate::base::dimension::U3;
16use crate::base::storage::Storage;
17use crate::base::{Matrix4, Vector, Vector3};
18
19use crate::geometry::{Point3, Projective3};
20
21#[cfg(feature = "rkyv-serialize")]
22use rkyv::bytecheck;
23
24/// A 3D perspective projection stored as a homogeneous 4x4 matrix.
25#[repr(C)]
26#[cfg_attr(
27    feature = "rkyv-serialize-no-std",
28    derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize),
29    archive(
30        as = "Perspective3<T::Archived>",
31        bound(archive = "
32        T: rkyv::Archive,
33        Matrix4<T>: rkyv::Archive<Archived = Matrix4<T::Archived>>
34    ")
35    )
36)]
37#[cfg_attr(feature = "rkyv-serialize", derive(bytecheck::CheckBytes))]
38#[derive(Copy, Clone)]
39pub struct Perspective3<T> {
40    matrix: Matrix4<T>,
41}
42
43impl<T: RealField> fmt::Debug for Perspective3<T> {
44    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> Result<(), fmt::Error> {
45        self.matrix.fmt(f)
46    }
47}
48
49impl<T: RealField> PartialEq for Perspective3<T> {
50    #[inline]
51    fn eq(&self, right: &Self) -> bool {
52        self.matrix == right.matrix
53    }
54}
55
56#[cfg(feature = "bytemuck")]
57unsafe impl<T> bytemuck::Zeroable for Perspective3<T>
58where
59    T: RealField + bytemuck::Zeroable,
60    Matrix4<T>: bytemuck::Zeroable,
61{
62}
63
64#[cfg(feature = "bytemuck")]
65unsafe impl<T> bytemuck::Pod for Perspective3<T>
66where
67    T: RealField + bytemuck::Pod,
68    Matrix4<T>: bytemuck::Pod,
69{
70}
71
72#[cfg(feature = "serde-serialize-no-std")]
73impl<T: RealField + Serialize> Serialize for Perspective3<T> {
74    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
75    where
76        S: Serializer,
77    {
78        self.matrix.serialize(serializer)
79    }
80}
81
82#[cfg(feature = "serde-serialize-no-std")]
83impl<'a, T: RealField + Deserialize<'a>> Deserialize<'a> for Perspective3<T> {
84    fn deserialize<Des>(deserializer: Des) -> Result<Self, Des::Error>
85    where
86        Des: Deserializer<'a>,
87    {
88        let matrix = Matrix4::<T>::deserialize(deserializer)?;
89
90        Ok(Self::from_matrix_unchecked(matrix))
91    }
92}
93
94impl<T> Perspective3<T> {
95    /// Wraps the given matrix to interpret it as a 3D perspective matrix.
96    ///
97    /// It is not checked whether or not the given matrix actually represents a perspective
98    /// projection.
99    #[inline]
100    pub const fn from_matrix_unchecked(matrix: Matrix4<T>) -> Self {
101        Self { matrix }
102    }
103}
104
105impl<T: RealField> Perspective3<T> {
106    /// Creates a new perspective matrix from the aspect ratio, y field of view, and near/far planes.
107    pub fn new(aspect: T, fovy: T, znear: T, zfar: T) -> Self {
108        assert!(
109            relative_ne!(zfar, znear),
110            "The near-plane and far-plane must not be superimposed."
111        );
112        assert!(
113            !relative_eq!(aspect, T::zero()),
114            "The aspect ratio must not be zero."
115        );
116
117        let matrix = Matrix4::identity();
118        let mut res = Self::from_matrix_unchecked(matrix);
119
120        res.set_fovy(fovy);
121        res.set_aspect(aspect);
122        res.set_znear_and_zfar(znear, zfar);
123
124        res.matrix[(3, 3)] = T::zero();
125        res.matrix[(3, 2)] = -T::one();
126
127        res
128    }
129
130    /// Retrieves the inverse of the underlying homogeneous matrix.
131    #[inline]
132    #[must_use]
133    pub fn inverse(&self) -> Matrix4<T> {
134        let mut res = self.clone().to_homogeneous();
135
136        res[(0, 0)] = T::one() / self.matrix[(0, 0)].clone();
137        res[(1, 1)] = T::one() / self.matrix[(1, 1)].clone();
138        res[(2, 2)] = T::zero();
139
140        let m23 = self.matrix[(2, 3)].clone();
141        let m32 = self.matrix[(3, 2)].clone();
142
143        res[(2, 3)] = T::one() / m32.clone();
144        res[(3, 2)] = T::one() / m23.clone();
145        res[(3, 3)] = -self.matrix[(2, 2)].clone() / (m23 * m32);
146
147        res
148    }
149
150    /// Computes the corresponding homogeneous matrix.
151    #[inline]
152    #[must_use]
153    pub fn to_homogeneous(self) -> Matrix4<T> {
154        self.matrix.clone_owned()
155    }
156
157    /// A reference to the underlying homogeneous transformation matrix.
158    #[inline]
159    #[must_use]
160    pub fn as_matrix(&self) -> &Matrix4<T> {
161        &self.matrix
162    }
163
164    /// A reference to this transformation seen as a `Projective3`.
165    #[inline]
166    #[must_use]
167    pub fn as_projective(&self) -> &Projective3<T> {
168        unsafe { &*(self as *const Perspective3<T> as *const Projective3<T>) }
169    }
170
171    /// This transformation seen as a `Projective3`.
172    #[inline]
173    #[must_use]
174    pub fn to_projective(self) -> Projective3<T> {
175        Projective3::from_matrix_unchecked(self.matrix)
176    }
177
178    /// Retrieves the underlying homogeneous matrix.
179    #[inline]
180    pub fn into_inner(self) -> Matrix4<T> {
181        self.matrix
182    }
183
184    /// Retrieves the underlying homogeneous matrix.
185    /// Deprecated: Use [`Perspective3::into_inner`] instead.
186    #[deprecated(note = "use `.into_inner()` instead")]
187    #[inline]
188    pub fn unwrap(self) -> Matrix4<T> {
189        self.matrix
190    }
191
192    /// Gets the `width / height` aspect ratio of the view frustum.
193    #[inline]
194    #[must_use]
195    pub fn aspect(&self) -> T {
196        self.matrix[(1, 1)].clone() / self.matrix[(0, 0)].clone()
197    }
198
199    /// Gets the y field of view of the view frustum.
200    #[inline]
201    #[must_use]
202    pub fn fovy(&self) -> T {
203        (T::one() / self.matrix[(1, 1)].clone()).atan() * crate::convert(2.0)
204    }
205
206    /// Gets the near plane offset of the view frustum.
207    #[inline]
208    #[must_use]
209    pub fn znear(&self) -> T {
210        let ratio =
211            (-self.matrix[(2, 2)].clone() + T::one()) / (-self.matrix[(2, 2)].clone() - T::one());
212
213        self.matrix[(2, 3)].clone() / (ratio * crate::convert(2.0))
214            - self.matrix[(2, 3)].clone() / crate::convert(2.0)
215    }
216
217    /// Gets the far plane offset of the view frustum.
218    #[inline]
219    #[must_use]
220    pub fn zfar(&self) -> T {
221        let ratio =
222            (-self.matrix[(2, 2)].clone() + T::one()) / (-self.matrix[(2, 2)].clone() - T::one());
223
224        (self.matrix[(2, 3)].clone() - ratio * self.matrix[(2, 3)].clone()) / crate::convert(2.0)
225    }
226
227    // TODO: add a method to retrieve znear and zfar simultaneously?
228
229    // TODO: when we get specialization, specialize the Mul impl instead.
230    /// Projects a point. Faster than matrix multiplication.
231    #[inline]
232    #[must_use]
233    pub fn project_point(&self, p: &Point3<T>) -> Point3<T> {
234        let inverse_denom = -T::one() / p[2].clone();
235        Point3::new(
236            self.matrix[(0, 0)].clone() * p[0].clone() * inverse_denom.clone(),
237            self.matrix[(1, 1)].clone() * p[1].clone() * inverse_denom.clone(),
238            (self.matrix[(2, 2)].clone() * p[2].clone() + self.matrix[(2, 3)].clone())
239                * inverse_denom,
240        )
241    }
242
243    /// Un-projects a point. Faster than multiplication by the matrix inverse.
244    #[inline]
245    #[must_use]
246    pub fn unproject_point(&self, p: &Point3<T>) -> Point3<T> {
247        let inverse_denom =
248            self.matrix[(2, 3)].clone() / (p[2].clone() + self.matrix[(2, 2)].clone());
249
250        Point3::new(
251            p[0].clone() * inverse_denom.clone() / self.matrix[(0, 0)].clone(),
252            p[1].clone() * inverse_denom.clone() / self.matrix[(1, 1)].clone(),
253            -inverse_denom,
254        )
255    }
256
257    // TODO: when we get specialization, specialize the Mul impl instead.
258    /// Projects a vector. Faster than matrix multiplication.
259    #[inline]
260    #[must_use]
261    pub fn project_vector<SB>(&self, p: &Vector<T, U3, SB>) -> Vector3<T>
262    where
263        SB: Storage<T, U3>,
264    {
265        let inverse_denom = -T::one() / p[2].clone();
266        Vector3::new(
267            self.matrix[(0, 0)].clone() * p[0].clone() * inverse_denom.clone(),
268            self.matrix[(1, 1)].clone() * p[1].clone() * inverse_denom,
269            self.matrix[(2, 2)].clone(),
270        )
271    }
272
273    /// Updates this perspective matrix with a new `width / height` aspect ratio of the view
274    /// frustum.
275    #[inline]
276    pub fn set_aspect(&mut self, aspect: T) {
277        assert!(
278            !relative_eq!(aspect, T::zero()),
279            "The aspect ratio must not be zero."
280        );
281        self.matrix[(0, 0)] = self.matrix[(1, 1)].clone() / aspect;
282    }
283
284    /// Updates this perspective with a new y field of view of the view frustum.
285    #[inline]
286    pub fn set_fovy(&mut self, fovy: T) {
287        let old_m22 = self.matrix[(1, 1)].clone();
288        let new_m22 = T::one() / (fovy / crate::convert(2.0)).tan();
289        self.matrix[(1, 1)] = new_m22.clone();
290        self.matrix[(0, 0)] *= new_m22 / old_m22;
291    }
292
293    /// Updates this perspective matrix with a new near plane offset of the view frustum.
294    #[inline]
295    pub fn set_znear(&mut self, znear: T) {
296        let zfar = self.zfar();
297        self.set_znear_and_zfar(znear, zfar);
298    }
299
300    /// Updates this perspective matrix with a new far plane offset of the view frustum.
301    #[inline]
302    pub fn set_zfar(&mut self, zfar: T) {
303        let znear = self.znear();
304        self.set_znear_and_zfar(znear, zfar);
305    }
306
307    /// Updates this perspective matrix with new near and far plane offsets of the view frustum.
308    #[inline]
309    pub fn set_znear_and_zfar(&mut self, znear: T, zfar: T) {
310        self.matrix[(2, 2)] = (zfar.clone() + znear.clone()) / (znear.clone() - zfar.clone());
311        self.matrix[(2, 3)] = zfar.clone() * znear.clone() * crate::convert(2.0) / (znear - zfar);
312    }
313}
314
315#[cfg(feature = "rand-no-std")]
316impl<T: RealField> Distribution<Perspective3<T>> for Standard
317where
318    Standard: Distribution<T>,
319{
320    /// Generate an arbitrary random variate for testing purposes.
321    fn sample<R: Rng + ?Sized>(&self, r: &mut R) -> Perspective3<T> {
322        use crate::base::helper;
323        let znear = r.gen();
324        let zfar = helper::reject_rand(r, |x: &T| !(x.clone() - znear.clone()).is_zero());
325        let aspect = helper::reject_rand(r, |x: &T| !x.is_zero());
326
327        Perspective3::new(aspect, r.gen(), znear, zfar)
328    }
329}
330
331#[cfg(feature = "arbitrary")]
332impl<T: RealField + Arbitrary> Arbitrary for Perspective3<T> {
333    fn arbitrary(g: &mut Gen) -> Self {
334        use crate::base::helper;
335        let znear: T = Arbitrary::arbitrary(g);
336        let zfar = helper::reject(g, |x: &T| !(x.clone() - znear.clone()).is_zero());
337        let aspect = helper::reject(g, |x: &T| !x.is_zero());
338
339        Self::new(aspect, Arbitrary::arbitrary(g), znear, zfar)
340    }
341}
342
343impl<T: RealField> From<Perspective3<T>> for Matrix4<T> {
344    #[inline]
345    fn from(pers: Perspective3<T>) -> Self {
346        pers.into_inner()
347    }
348}
nalgebra/geometry/perspective.rs

nalgebra/geometry/
perspective.rs
