retroglyph_window/lib.rs
1//! A shared layer for window-based backends (software, GL, wgpu).
2//!
3//! # Architecture
4//!
5//! [`Backend`](retroglyph_core::Backend) fuses input (`poll_event`/
6//! `push_event`) and output (`draw_layers`/`flush`/...), which fits a
7//! terminal process but not a window: there, an event loop owns input and a
8//! renderer owns output. This crate splits the two apart and reassembles
9//! them into one `Backend`:
10//!
11//! ```text
12//! ┌─────────────────────────────┐
13//! │ event loop (winit or │
14//! │ a custom driver) │
15//! └──────────────┬───────────────┘
16//! translated events
17//! │
18//! v
19//! ┌────────────────────────────────────────────────────┐
20//! │ WindowBackend<P: Presenter> │
21//! │ (implements Backend: owns the input event queue, │
22//! │ delegates output to P) │
23//! └───────────────────────┬──────────────────────────────┘
24//! │ draw / flush / resize / present
25//! v
26//! ┌───────────────────────────────┐
27//! │ P: Presenter │
28//! │ (retroglyph-software today; │
29//! │ wgpu/GL renderers planned) │
30//! └───────────────────────────────┘
31//! ```
32//!
33//! - [`Presenter`] is the output half: rasterization plus the surface
34//! lifecycle (`init_surface`/`resize_surface`/`present`/`cell_size`).
35//! Renderer crates implement only this trait.
36//! - <code>[WindowBackend]<P: Presenter></code> implements `Backend`
37//! generically, holding the input event queue and delegating output to
38//! `P`.
39//! - The `winit` module (feature-gated, see below) drives the event loop
40//! that fills that queue and calls `Presenter::present` each frame.
41//!
42//! # Feature flags
43//!
44//! [`Presenter`], [`WindowBackend`], and [`WindowHandle`] depend only on
45//! [`raw-window-handle`](raw_window_handle) and are always available. The
46//! `winit` feature (default on) additionally provides the `winit` module:
47//! the event loop, event translation, and the `run_windowed`/`run_app`
48//! drivers. Disable it to implement or drive `Presenter` with a different
49//! windowing library (SDL2, tao, a custom loop) without pulling in winit.
50
51/// The generic [`Backend`](retroglyph_core::Backend) for windowed presenters.
52pub mod backend;
53/// The [`Presenter`] trait and [`WindowHandle`](presenter::WindowHandle).
54pub mod presenter;
55/// The winit event loop, event translation, and app drivers.
56#[cfg(feature = "winit")]
57pub mod winit;
58
59pub use backend::WindowBackend;
60pub use presenter::{Presenter, WindowHandle};
61
62// Re-exported so presenters can name the handle traits without adding their
63// own raw-window-handle dependency (and so versions can't drift apart).
64pub use raw_window_handle;