nalgebra/geometry/
perspective.rs

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

nalgebra/geometry/
perspective.rs
