Skip to main content

trackball/
bound.rs

1use crate::{Clamp, Frame, Plane, Rigid, float};
2use glam::{Quat, Vec3};
3
4/// Orthogonal boundary conditions implementing [`Clamp`].
5///
6/// Implements [`Default`] and can be created with `Bound::default()`.
7#[derive(Debug, Clone, Copy, PartialEq)]
8#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
9#[cfg_attr(
10    feature = "rkyv-08",
11    derive(rkyv_08::Archive, rkyv_08::Serialize, rkyv_08::Deserialize),
12    rkyv(crate = rkyv_08)
13)]
14pub struct Bound {
15    /// Isometry in world space of bound inversely transforming target and eye positions.
16    pub transform: Rigid,
17    /// Minimum components of target position in world space. Default splats `f32::MIN`.
18    pub min_target: Vec3,
19    /// Maximum components of target position in world space. Default splats `f32::MAX`.
20    pub max_target: Vec3,
21    /// Minimum components of eye position in world space. Default splats `f32::MIN`.
22    pub min_eye: Vec3,
23    /// Maximum components of eye position in world space. Default splats `f32::MAX`.
24    pub max_eye: Vec3,
25    /// Minimum components of up axis in bound space following yaw. Default splats `f32::MIN`.
26    ///
27    /// See [`Clamp::up()`] implementation of [`Bound`].
28    pub min_up: Vec3,
29    /// Maximum components of up axis in bound space following yaw. Default splats `f32::MAX`.
30    ///
31    /// See [`Clamp::up()`] implementation of [`Bound`].
32    pub max_up: Vec3,
33    /// Minimum distance of eye from target. Default is `0.0`.
34    pub min_distance: f32,
35    /// Maximum distance of eye from target. Default is `f32::MAX`.
36    pub max_distance: f32,
37    /// Epsilon allowing clamped [`Delta`] to more likely pass revalidation.
38    ///
39    /// Default is <code>[f32::EPSILON].sqrt()</code>.
40    ///
41    /// [`Delta`]: crate::Delta
42    pub hysteresis: f32,
43}
44
45impl Default for Bound {
46    fn default() -> Self {
47        Self {
48            transform: Rigid::IDENTITY,
49            hysteresis: float::sqrt(f32::EPSILON),
50            min_target: Vec3::MIN,
51            max_target: Vec3::MAX,
52            min_eye: Vec3::MIN,
53            max_eye: Vec3::MAX,
54            min_up: Vec3::MIN,
55            max_up: Vec3::MAX,
56            min_distance: 0.0,
57            max_distance: f32::MAX,
58        }
59    }
60}
61
62impl Clamp for Bound {
63    /// Using lower loop limit for flat boundary conditions.
64    fn loops(&self) -> usize {
65        10
66    }
67    /// Find any boundary plane exceeded by target position.
68    fn target(&self, frame: Frame) -> Option<Plane> {
69        let target = self.transform.inverse() * frame.target();
70        self.exceeded(target, self.min_target, self.max_target, Quat::IDENTITY)
71            .map(|plane| plane.transform_by(self.transform))
72    }
73    /// Find any boundary plane exceeded by eye position.
74    ///
75    /// Distance planes are orthogonal to the roll axis at minimum or maximum distance from target.
76    fn eye(&self, frame: Frame) -> Option<Plane> {
77        let distance = frame.distance();
78        let (target, roll_axis) = (frame.target(), frame.roll_axis());
79        if (self.min_distance - distance) > self.hysteresis {
80            return Some(Plane::with_point(
81                roll_axis,
82                target + roll_axis * self.min_distance,
83            ));
84        }
85        if (self.max_distance - distance) < -self.hysteresis {
86            return Some(Plane::with_point(
87                roll_axis,
88                target + roll_axis * self.max_distance,
89            ));
90        }
91        let eye = self.transform.inverse() * frame.eye();
92        self.exceeded(eye, self.min_eye, self.max_eye, Quat::IDENTITY)
93            .map(|plane| plane.transform_by(self.transform))
94    }
95    /// Find any boundary plane exceeded by up position.
96    ///
97    /// Up position is expressed in bound space following yaw, i.e., rotated around y-axis by the
98    /// heading whose x-axis is the horizontal pitch axis. Its y-component bounds the tilt (e.g.,
99    /// `min_up.y = 0.0` prevents turning upside down but allows rolling sideways over the pole)
100    /// whereas its x-component bounds the roll (e.g., `min_up.x = max_up.x = 0.0` prevents rolling
101    /// and stops at the pole like a turntable) and its z-component bounds the forward tilt.
102    fn up(&self, frame: Frame) -> Option<Plane> {
103        let rotation = self.transform.rotation;
104        let pitch_axis = rotation.inverse() * frame.pitch_axis();
105        let heading = Quat::from_rotation_y(float::atan2(-pitch_axis.z, pitch_axis.x));
106        let up = heading.inverse() * rotation.inverse() * frame.yaw_axis();
107        self.exceeded(up, self.min_up, self.max_up, rotation * heading)
108    }
109}
110
111impl Bound {
112    /// Find any boundary plane exceeded by position in bound space and rotate it by `rotation`.
113    fn exceeded(&self, position: Vec3, min: Vec3, max: Vec3, rotation: Quat) -> Option<Plane> {
114        let axes = [Vec3::X, Vec3::Y, Vec3::Z];
115        for (index, axis) in axes.into_iter().enumerate() {
116            let min_plane = Plane::new(axis, min[index]);
117            if min_plane.distance_from(position) > self.hysteresis {
118                return Some(min_plane.rotate_by(rotation));
119            }
120            let max_plane = Plane::new(axis, max[index]);
121            if max_plane.distance_from(position) < -self.hysteresis {
122                return Some(max_plane.rotate_by(rotation));
123            }
124        }
125        None
126    }
127}