viewport-lib-input 0.4.0

Input handling for viewport-lib: the event resolver, the camera controllers, and the optional winit/egui adapters. A replaceable layer on viewport-lib-types - resolve events into an ActionFrame, then apply it to a Camera however you like.
Documentation
//! Input handling for `viewport-lib`: a replaceable layer, not baked-in core.
//!
//! The design intent is that a consumer can bring their own. Input handling
//! splits into two halves, and either is usable on its own:
//!
//! 1. **Resolve**: [`input::ViewportInput`] turns `ViewportEvent`s into a single
//!    [`ActionFrame`](viewport_lib_types::input::ActionFrame) per frame.
//! 2. **Apply**: a camera controller takes that `ActionFrame` and a
//!    `&mut Camera` and produces a new pose. This is the half a custom controller
//!    replaces; see [`CameraController`].
//!
//! The built-in [`controllers`] (orbit, first/third-person, turntable, the flat
//! 2D camera, and the `dt`-driven animator) are the batteries-included
//! defaults. The winit/egui [adapters](input::adapters) that translate native
//! events are optional features (`winit-adapter`, `egui-adapter`), so the crate
//! builds with no framework dependency by default.
//!
//! This crate carries no `wgpu` and no renderer. It stands on
//! `viewport-lib-types` (the input vocabulary and the `Camera` type) plus `glam`.
//! `viewport-lib` re-exports it, so `viewport_lib::OrbitCameraController` and
//! friends keep working.

#![allow(deprecated)]

// Re-exported so controllers can name `crate::Camera` and consumers can get the
// camera type from this crate.
pub use viewport_lib_types::camera::{Camera, LookAngles};

/// The batteries-included camera controllers.
pub mod controllers;
/// The event resolver, the legacy query model, and the native-event adapters.
pub mod input;

/// A camera controller: the "apply" half of input handling.
///
/// Implement this to drive a `Camera` from a resolved
/// [`ActionFrame`](viewport_lib_types::input::ActionFrame) however you like - the
/// built-in controllers (`OrbitCameraController`, ...) are one set of policies,
/// not the only ones. Resolve the frame with [`input::ViewportInput`], then hand
/// it to your controller each frame.
///
/// The built-in controllers implement this, but the trait is not required to use
/// them: their inherent `apply` methods and free-function forms still work. It
/// exists so a custom controller has a concrete shape to fill and so controllers
/// are interchangeable by type where a consumer wants that.
pub trait CameraController {
    /// Apply one frame of resolved input to the camera. `dt` is the frame time
    /// in seconds, for input that is held rather than moved (a key held to fly,
    /// a stick held over): such input moves the camera at a rate, and needs the
    /// time to turn that rate into a distance. Drags and the wheel arrive in the
    /// frame as deltas already.
    fn apply(
        &mut self,
        camera: &mut Camera,
        frame: &viewport_lib_types::input::ActionFrame,
        dt: f32,
    );

    /// The size the scene draws at, in logical pixels, and its device pixels
    /// per point. A runner calls this before each [`apply`](Self::apply), for
    /// controllers whose motion depends on the viewport (dragging by pixels,
    /// zooming about the cursor). For a viewport presented at a reference
    /// size it is the reference size with one pixel per point. The default
    /// ignores it.
    fn set_viewport(&mut self, viewport_size: [f32; 2], pixels_per_point: f32) {
        let _ = (viewport_size, pixels_per_point);
    }

    /// The controller as [`Any`](std::any::Any), so a host that handed it to
    /// a runner as a trait object can reach its concrete type again. The
    /// default returns `None`; return `Some(self)` to allow it.
    fn as_any_mut(&mut self) -> Option<&mut dyn std::any::Any> {
        None
    }
}

impl CameraController for controllers::OrbitCameraController {
    fn apply(
        &mut self,
        camera: &mut Camera,
        frame: &viewport_lib_types::input::ActionFrame,
        dt: f32,
    ) {
        // Delegate to the inherent apply, which drives the camera per the
        // controller's `navigation_mode`.
        controllers::OrbitCameraController::apply(self, camera, frame, dt)
    }

    fn set_viewport(&mut self, viewport_size: [f32; 2], _pixels_per_point: f32) {
        self.set_viewport_size(viewport_size);
    }

    fn as_any_mut(&mut self) -> Option<&mut dyn std::any::Any> {
        Some(self)
    }
}
// The first/third-person controllers take an extra per-frame position (eye /
// target), so they do not fit this two-argument shape; use their inherent
// `apply` methods directly. See `controllers`.

pub mod prelude {
    //! The input types most code reaches for, in one glob import:
    //! `use viewport_lib_input::prelude::*;`.
    //!
    //! The common set, not the whole surface. Reach into [`crate::input`] and
    //! [`crate::controllers`] for the rest.
    pub use crate::CameraController;
    pub use crate::controllers::{
        Camera2d, Camera2dControl, Camera2dController, CameraAnimator, FirstPersonCameraController,
        OrbitCameraController, Plane2d, ThirdPersonCameraController, TurntableController,
    };
    pub use crate::input::ViewportInput;
    pub use viewport_lib_types::camera::Camera;
    pub use viewport_lib_types::input::{Action, ActionFrame, ViewportContext, ViewportEvent};
}