Skip to main content

trackball/
lib.rs

1//! Virtual Trackball Orbiting via the Exponential Map
2//!
3//! This is an alternative trackball technique using the exponential map for inducing coherent and
4//! intuitive trackball rotations.[^1] Displacements on straight radial lines through the screen's
5//! center are carried to arcs of the same length on great circles of the trackball, whose half
6//! circumference is the maximum of the screen's width and height. This is in contrast to
7//! state-of-the-art techniques using orthogonal projection which distorts radial distances further
8//! away from the screen's center. Each rotation carries the trackball's point under the previous
9//! cursor/finger position along the shortest arc to the one under the current position, keeping the
10//! grabbed point under the cursor/finger. This follows the paper's differential of the exponential
11//! map rather than its recipe, which takes the differential to be parallel transport, preserving
12//! the lengths of displacements but letting the grabbed point drift. Screen corners beyond the
13//! trackball's border are mapped beyond its equator, keeping radial displacements linear.
14//!
15//! [^1]: G. Stantchev, “Virtual Trackball Modeling and the Exponential Map”, [S2CID 44199608 (2004)
16//! ](https://api.semanticscholar.org/CorpusID:44199608), [Archived PDF
17//! ](https://web.archive.org/web/2/http://www.math.umd.edu:80/~gogo/Papers/trackballExp.pdf)
18//!
19//! # Features
20//!
21//!   * Common trackball operations split into several operation handlers.
22//!   * Coherent and intuitive orbiting via the exponential map, see [`Orbit`] operation handler.
23//!   * Identical C11 implementation for [`Orbit`] operation handler behind `cc` feature gate.
24//!   * Coherent [`First`] person view aka free look or mouse look wrt [`Orbit`] operation handler.
25//!   * Observer [`Frame`] with [`Frame::slide()`], [`Frame::orbit()`], [`Frame::scale()`]
26//!     operations in world space and their local complements in camera space and with orbit and
27//!     slide operations around arbitrary points in either world or camera space.
28//!   * Gliding [`Clamp`] operation handler trait ensuring boundary conditions of observer
29//!     [`Frame`]. When [`Delta`] between initial and final [`Frame`] is not orthogonal to a
30//!     boundary [`Plane`], [`Delta`] is changed in such a way that the clamped movement glides
31//!     along the plane.
32//!   * [`Rigid`] transformation as direct isometry of [`Frame::view()`] and [`Bound::transform`].
33//!   * [`Bound`] implementing [`Clamp`] providing customizable orthogonal boundary conditions.
34//!   * Object inspection mode scaling clip plane distances by measuring from target instead of eye.
35//!   * Scale-preserving transitioning between orthographic and perspective projection mode.
36//!   * Converting between [`Fixed`] quantities wrt to field of view, see [`Scope::set_fov()`].
37//!   * Time-free [`Touch`] gesture recognition for slide, orbit, scale, and focus operations.
38//!
39//! # Math Backend
40//!
41//! Like `glam`, this crate requires one of the following math backends, forwarded to `glam`:
42//!
43//!   * `std` (default) for using the math functions of the standard library.
44//!   * `libm` for using `libm` instead of `std`, e.g., for consistent results across platforms.
45//!   * `nostd-libm` for using `libm` only if `std` is disabled, e.g., in `no_std` environments.
46//!
47//! This crate is `no_std` with `default-features = false` and `libm` or `nostd-libm` enabled.
48//!
49//! # Optional Features
50//!
51//! Following features are disabled unless their corresponding feature gate is enabled:
52//!
53//!   * `serde` for `serde` support of various structures of this crate and its dependencies.
54//!   * `rkyv-08` for `rkyv` 0.8 support of various structures of this crate and its dependencies.
55//!   * `cc` for testing the behaviorally identical C implementation of the exponential map.
56//!
57//! # Example
58//!
59//! A trackball camera mode implementation can be as easy as this by delegating events of your 3D
60//! graphics library of choice to the [`Orbit`] operation handler along with other handlers.
61//!
62//! ```
63//! use trackball::{Frame, Image, Orbit, glam::Vec2};
64//!
65//! /// Trackball camera mode.
66//! pub struct Trackball {
67//!     // Frame wrt camera eye and target.
68//!     frame: Frame,
69//!     // Image as projection of `Scope` wrt `Frame`.
70//!     image: Image,
71//!     // Orbit induced by displacement on screen.
72//!     orbit: Orbit,
73//! }
74//!
75//! impl Trackball {
76//!     // Usually, a cursor position event with left mouse button being pressed.
77//!     fn handle_left_button_displacement(&mut self, pos: Vec2) {
78//!         // Maximum position as screen's width and height.
79//!         let max = self.image.max();
80//!         // Induced rotation in camera space.
81//!         let rot = self.orbit.compute(pos, max).unwrap_or_default();
82//!         // Apply induced rotation to local observer frame.
83//!         self.frame.local_orbit(rot);
84//!     }
85//!     // Event when left mouse button is released again.
86//!     fn handle_left_button_release(&mut self) {
87//!         // Can also or instead be invoked on `Self::handle_left_button_press()`.
88//!         self.orbit.discard();
89//!     }
90//! }
91//! ```
92
93#![cfg_attr(any(feature = "rkyv-08", feature = "cc"), deny(unsafe_code))]
94#![cfg_attr(not(any(feature = "rkyv-08", feature = "cc")), forbid(unsafe_code))]
95#![cfg_attr(not(feature = "std"), no_std)]
96
97#[cfg(all(
98    not(feature = "std"),
99    not(feature = "libm"),
100    not(feature = "nostd-libm")
101))]
102compile_error!(
103    "You must specify a math backend. Consider enabling either `std`, `libm`, or `nostd-libm`."
104);
105
106pub use glam;
107
108mod bound;
109mod clamp;
110mod delta;
111mod first;
112mod fixed;
113mod float;
114mod frame;
115mod image;
116mod orbit;
117mod plane;
118mod rigid;
119mod scale;
120mod scope;
121mod slide;
122mod touch;
123
124pub use bound::*;
125pub use clamp::*;
126pub use delta::*;
127pub use first::*;
128pub use fixed::*;
129pub use frame::*;
130pub use image::*;
131pub use orbit::*;
132pub use plane::*;
133pub use rigid::*;
134pub use scale::*;
135pub use scope::*;
136pub use slide::*;
137pub use touch::*;