viewport_lib_input/lib.rs
1//! Input handling for `viewport-lib`: a replaceable layer, not baked-in core.
2//!
3//! The design intent is that a consumer can bring their own. Input handling
4//! splits into two halves, and either is usable on its own:
5//!
6//! 1. **Resolve**: [`input::ViewportInput`] turns `ViewportEvent`s into a single
7//! [`ActionFrame`](viewport_lib_types::input::ActionFrame) per frame.
8//! 2. **Apply**: a camera controller takes that `ActionFrame` and a
9//! `&mut Camera` and produces a new pose. This is the half a custom controller
10//! replaces; see [`CameraController`].
11//!
12//! The built-in [`controllers`] (orbit, first/third-person, turntable, the flat
13//! 2D camera, and the `dt`-driven animator) are the batteries-included
14//! defaults. The winit/egui [adapters](input::adapters) that translate native
15//! events are optional features (`winit-adapter`, `egui-adapter`), so the crate
16//! builds with no framework dependency by default.
17//!
18//! This crate carries no `wgpu` and no renderer. It stands on
19//! `viewport-lib-types` (the input vocabulary and the `Camera` type) plus `glam`.
20//! `viewport-lib` re-exports it, so `viewport_lib::OrbitCameraController` and
21//! friends keep working.
22
23#![allow(deprecated)]
24
25// Re-exported so controllers can name `crate::Camera` and consumers can get the
26// camera type from this crate.
27pub use viewport_lib_types::camera::{Camera, LookAngles};
28
29/// The batteries-included camera controllers.
30pub mod controllers;
31/// The event resolver, the legacy query model, and the native-event adapters.
32pub mod input;
33
34/// A camera controller: the "apply" half of input handling.
35///
36/// Implement this to drive a `Camera` from a resolved
37/// [`ActionFrame`](viewport_lib_types::input::ActionFrame) however you like - the
38/// built-in controllers (`OrbitCameraController`, ...) are one set of policies,
39/// not the only ones. Resolve the frame with [`input::ViewportInput`], then hand
40/// it to your controller each frame.
41///
42/// The built-in controllers implement this, but the trait is not required to use
43/// them: their inherent `apply` methods and free-function forms still work. It
44/// exists so a custom controller has a concrete shape to fill and so controllers
45/// are interchangeable by type where a consumer wants that.
46pub trait CameraController {
47 /// Apply one frame of resolved input to the camera. `dt` is the frame time
48 /// in seconds, for input that is held rather than moved (a key held to fly,
49 /// a stick held over): such input moves the camera at a rate, and needs the
50 /// time to turn that rate into a distance. Drags and the wheel arrive in the
51 /// frame as deltas already.
52 fn apply(
53 &mut self,
54 camera: &mut Camera,
55 frame: &viewport_lib_types::input::ActionFrame,
56 dt: f32,
57 );
58
59 /// The size the scene draws at, in logical pixels, and its device pixels
60 /// per point. A runner calls this before each [`apply`](Self::apply), for
61 /// controllers whose motion depends on the viewport (dragging by pixels,
62 /// zooming about the cursor). For a viewport presented at a reference
63 /// size it is the reference size with one pixel per point. The default
64 /// ignores it.
65 fn set_viewport(&mut self, viewport_size: [f32; 2], pixels_per_point: f32) {
66 let _ = (viewport_size, pixels_per_point);
67 }
68
69 /// The controller as [`Any`](std::any::Any), so a host that handed it to
70 /// a runner as a trait object can reach its concrete type again. The
71 /// default returns `None`; return `Some(self)` to allow it.
72 fn as_any_mut(&mut self) -> Option<&mut dyn std::any::Any> {
73 None
74 }
75}
76
77impl CameraController for controllers::OrbitCameraController {
78 fn apply(
79 &mut self,
80 camera: &mut Camera,
81 frame: &viewport_lib_types::input::ActionFrame,
82 dt: f32,
83 ) {
84 // Delegate to the inherent apply, which drives the camera per the
85 // controller's `navigation_mode`.
86 controllers::OrbitCameraController::apply(self, camera, frame, dt)
87 }
88
89 fn set_viewport(&mut self, viewport_size: [f32; 2], _pixels_per_point: f32) {
90 self.set_viewport_size(viewport_size);
91 }
92
93 fn as_any_mut(&mut self) -> Option<&mut dyn std::any::Any> {
94 Some(self)
95 }
96}
97// The first/third-person controllers take an extra per-frame position (eye /
98// target), so they do not fit this two-argument shape; use their inherent
99// `apply` methods directly. See `controllers`.
100
101pub mod prelude {
102 //! The input types most code reaches for, in one glob import:
103 //! `use viewport_lib_input::prelude::*;`.
104 //!
105 //! The common set, not the whole surface. Reach into [`crate::input`] and
106 //! [`crate::controllers`] for the rest.
107 pub use crate::CameraController;
108 pub use crate::controllers::{
109 Camera2d, Camera2dControl, Camera2dController, CameraAnimator, FirstPersonCameraController,
110 OrbitCameraController, Plane2d, ThirdPersonCameraController, TurntableController,
111 };
112 pub use crate::input::ViewportInput;
113 pub use viewport_lib_types::camera::Camera;
114 pub use viewport_lib_types::input::{Action, ActionFrame, ViewportContext, ViewportEvent};
115}