trackball/
scope.rs

1use crate::Fixed;
2use nalgebra::{Matrix4, Point2, RealField, convert};
3use simba::scalar::SubsetOf;
4
5/// Scope defining enclosing viewing frustum.
6///
7/// Implements [`Default`] and can be created with `Scope::default()`.
8#[derive(Debug, Clone, Copy, PartialEq, Eq)]
9#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
10pub struct Scope<N: Copy + RealField> {
11	/// Fixed quantity wrt field of view.
12	///
13	/// Default is fixed vertical field of view of π/4.
14	fov: Fixed<N>,
15	/// Clip plane distances.
16	///
17	/// Near and far clip plane distances from either target or eye whether [`Self::oim`]. Default
18	/// is `(1e-1, 1e+3)` measured from eye.
19	zcp: (N, N),
20	/// Object inspection mode.
21	///
22	/// Scales clip plane distances by measuring from target instead of eye. Default is `false`.
23	oim: bool,
24	/// Orthographic projection mode.
25	///
26	/// Computes scale-identical orthographic instead of perspective projection. Default is `false`.
27	opm: bool,
28}
29
30impl<N: Copy + RealField> Default for Scope<N> {
31	fn default() -> Self {
32		Self {
33			fov: Fixed::default(),
34			zcp: (convert(1e-1), convert(1e+3)),
35			oim: false,
36			opm: false,
37		}
38	}
39}
40
41impl<N: Copy + RealField> Scope<N> {
42	/// Fixed quantity wrt field of view, see [`Self::set_fov()`].
43	#[must_use]
44	pub const fn fov(&self) -> Fixed<N> {
45		self.fov
46	}
47	/// Sets fixed quantity wrt field of view.
48	///
49	/// Default is fixed vertical field of view of π/4.
50	///
51	/// ```
52	/// use nalgebra::Point2;
53	/// use trackball::Scope;
54	///
55	/// // Current screen size.
56	/// let max = Point2::new(800, 600);
57	/// // Default scope with fixed vertical field of view of π/4:
58	/// //
59	/// //   * Increasing width increases horizontal field of view (more can be seen).
60	/// //   * Increasing height scales scope zooming in as vertical field of view is fixed.
61	/// let mut scope = Scope::default();
62	/// // Unfix vertical field of view by fixing current unit per pixel on focus plane at distance
63	/// // from eye of one, that is effectively `upp` divided by `zat` to make it scale-independant:
64	/// //
65	/// //   * Increasing width increases horizontal field of view (more can be seen).
66	/// //   * Increasing height increases vertical field of view (more can be seen).
67	/// scope.set_fov(scope.fov().to_upp(&max.cast::<f32>()));
68	/// ```
69	pub fn set_fov(&mut self, fov: impl Into<Fixed<N>>) {
70		self.fov = fov.into();
71	}
72	/// Clip plane distances from eye regardless of [`Self::scale()`] wrt to distance between eye
73	/// and target.
74	///
75	/// Default is `(1e-1, 1e+3)` measured from eye.
76	#[must_use]
77	pub fn clip_planes(&self, zat: N) -> (N, N) {
78		if self.oim {
79			let (znear, zfar) = self.zcp;
80			(zat - znear, zat + zfar)
81		} else {
82			self.zcp
83		}
84	}
85	/// Sets clip plane distances from target or eye whether [`Self::scale()`].
86	///
87	/// Default is `(1e-1, 1e+3)` measured from eye.
88	pub const fn set_clip_planes(&mut self, znear: N, zfar: N) {
89		self.zcp = (znear, zfar);
90	}
91	/// Object inspection mode.
92	///
93	/// Scales clip plane distances by measuring from target instead of eye. Default is `false`.
94	#[must_use]
95	pub const fn scale(&self) -> bool {
96		self.oim
97	}
98	/// Sets object inspection mode.
99	///
100	/// Scales clip plane distances by measuring from target instead of eye. Default is `false`.
101	pub const fn set_scale(&mut self, oim: bool) {
102		self.oim = oim;
103	}
104	/// Orthographic projection mode.
105	///
106	/// Computes scale-identical orthographic instead of perspective projection. Default is `false`.
107	#[must_use]
108	pub const fn ortho(&self) -> bool {
109		self.opm
110	}
111	/// Sets orthographic projection mode.
112	///
113	/// Computes scale-identical orthographic instead of perspective projection. Default is `false`.
114	pub const fn set_ortho(&mut self, opm: bool) {
115		self.opm = opm;
116	}
117	/// Projection transformation and unit per pixel on focus plane wrt distance between eye and
118	/// target and maximum position in screen space.
119	#[must_use]
120	pub fn projection_and_upp(&self, zat: N, max: &Point2<N>) -> (Matrix4<N>, N) {
121		let (znear, zfar) = self.clip_planes(zat);
122		if self.opm {
123			let (max, upp) = self.fov.max_and_upp(zat, max);
124			let mat = Matrix4::new_orthographic(-max.x, max.x, -max.y, max.y, znear, zfar);
125			(mat, upp)
126		} else {
127			let fov = self.fov.to_ver(max).into_inner();
128			let (max, upp) = self.fov.max_and_upp(zat, max);
129			let mat = Matrix4::new_perspective(max.x / max.y, fov, znear, zfar);
130			(mat, upp)
131		}
132	}
133	/// Casts components to another type, e.g., between [`f32`] and [`f64`].
134	#[must_use]
135	pub fn cast<M: Copy + RealField>(self) -> Scope<M>
136	where
137		N: SubsetOf<M>,
138	{
139		let (near, far) = self.zcp;
140		Scope {
141			fov: self.fov.cast(),
142			zcp: (near.to_superset(), far.to_superset()),
143			oim: self.oim,
144			opm: self.opm,
145		}
146	}
147}
148
149#[cfg(feature = "rkyv")]
150impl<N: Copy + RealField> rkyv::Archive for Scope<N> {
151	type Archived = Self;
152	type Resolver = ();
153
154	#[inline]
155	#[allow(unsafe_code)]
156	unsafe fn resolve(&self, _: usize, (): Self::Resolver, out: *mut Self::Archived) {
157		unsafe {
158			out.write(rkyv::to_archived!(*self as Self));
159		}
160	}
161}
162
163#[cfg(feature = "rkyv")]
164impl<Ser: rkyv::Fallible + ?Sized, N: Copy + RealField> rkyv::Serialize<Ser> for Scope<N> {
165	#[inline]
166	fn serialize(&self, _: &mut Ser) -> Result<Self::Resolver, Ser::Error> {
167		Ok(())
168	}
169}
170
171#[cfg(feature = "rkyv")]
172impl<De: rkyv::Fallible + ?Sized, N: Copy + RealField> rkyv::Deserialize<Self, De> for Scope<N> {
173	#[inline]
174	fn deserialize(&self, _: &mut De) -> Result<Self, De::Error> {
175		Ok(rkyv::from_archived!(*self))
176	}
177}
trackball/scope.rs

trackball/
scope.rs
