Skip to main content

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}