Skip to main content

agg_gui_shell/
lib.rs

1//! Turn-key native shell for an [`agg_gui::App`] — winit window, wgpu present,
2//! input forwarding, redraw scheduling, window-bounds persistence, and
3//! device-loss recovery.
4//!
5//! Every native agg-gui app used to hand-roll the same several hundred lines
6//! of event loop, and every copy drifted: one had key-up dispatch and surface
7//! recovery, another had touch input and the anti-flash first-paint ordering,
8//! a third had the DPI-safe window restore. This crate is the union of them.
9//!
10//! ```no_run
11//! use agg_gui_shell::{run, NoHost, ShellConfig};
12//!
13//! # fn build_my_app() -> agg_gui::App { unimplemented!() }
14//! fn main() -> Result<(), agg_gui_shell::ShellError> {
15//!     run(
16//!         ShellConfig::new("My App").with_logical_size(1280.0, 720.0),
17//!         |_init| Ok((build_my_app(), NoHost)),
18//!     )
19//! }
20//! ```
21//!
22//! # What the shell owns
23//!
24//! - Window creation with DPI-safe restore of a saved size (see
25//!   [`WindowBoundsStore`]) and the paint-first-then-show ordering that avoids
26//!   a white flash on start-up.
27//! - Mouse, wheel (including the shift→horizontal remap), keyboard **down and
28//!   up**, touch, cursor-leave, modifiers, and the OS cursor icon.
29//! - Reactive redraw scheduling: `Poll` while the app wants frames,
30//!   `WaitUntil` for a scheduled deadline, `Wait` otherwise — or
31//!   [`RedrawPolicy::Continuous`] when the app wants every frame.
32//! - The agg-gui host waker, so a background thread's
33//!   `animation::signal_async_state_change` wakes a parked loop; installed
34//!   only after the window and GPU came up and cleared on every exit path.
35//! - Surface-acquire recovery, swap-chain resize coalescing, and rebuilding
36//!   the device after a **device loss** (TDR, driver reset, GPU removal, RDP
37//!   session change) — see [`ShellHost::on_gpu_rebuilt`].
38//! - Optional deterministic screenshot capture, and fullscreen toggles
39//!   requested through `agg_gui::fullscreen`.
40//!
41//! # What the app owns
42//!
43//! Everything else, through [`ShellHost`]: per-frame state ticks, a custom
44//! frame body, GPU read-back after the render is submitted, geometry change
45//! notifications, idle-time work, exit and relaunch. Every method has a
46//! default, so [`NoHost`] is a complete implementation for an app that just
47//! wants a window.
48//!
49//! # Public API surface
50//!
51//! `winit` and `wgpu` types appear in this crate's API ([`ShellConfig`]'s
52//! present mode, [`ShellHost::paint`]'s render context, the window handed to a
53//! builder closure). Their major versions are therefore part of *this* crate's
54//! public API: a `winit` 0.31 or `wgpu` 30 will be a breaking release here,
55//! and an app must depend on the same majors this crate does.
56//!
57//! The browser equivalent of this crate is `agg-gui-web-shell`, whose
58//! `WebShellHost` mirrors [`ShellHost`] method for method.
59
60mod bounds;
61mod config;
62mod host;
63mod input;
64mod paint;
65mod redraw_schedule;
66mod run;
67mod screenshot;
68mod shell_loop;
69mod tooltip;
70mod waker;
71
72pub use bounds::{sanitize_restored_window_size, SavedBounds, WindowBoundsStore};
73pub use config::{RedrawPolicy, ScreenshotConfig, ShellConfig, WindowIcon, WindowSize};
74pub use host::{default_paint, Frame, NoHost, ShellControl, ShellHost, WindowGeometry};
75pub use run::run;
76pub use shell_loop::ShellInit;
77
78// Re-exported so a consumer can build a `ShellHost` without naming the
79// renderer crate, and so the versions can never disagree.
80pub use agg_gui_wgpu::{CopySrc, Gpu, WgpuGfxCtx};
81
82/// The `wgpu` this shell was built against.
83///
84/// Its major version is part of this crate's public API (present modes, the
85/// render context, the device behind [`Gpu`]), so an app that names `wgpu`
86/// types itself should reach them through here rather than adding its own
87/// `wgpu` dependency, where a mismatched major would silently produce two
88/// incompatible sets of types.
89pub use wgpu;
90
91/// The `winit` this shell was built against.
92///
93/// Its major version is part of this crate's public API (the window handed to
94/// the builder closure, fullscreen and monitor types), so an app that names
95/// `winit` types itself should reach them through here rather than adding its
96/// own `winit` dependency.
97pub use winit;
98
99/// Why the shell could not start, or could not finish.
100#[derive(Debug)]
101#[non_exhaustive]
102pub enum ShellError {
103    /// Creating or running the winit event loop failed.
104    EventLoop(winit::error::EventLoopError),
105    /// The OS refused to create the window.
106    CreateWindow(winit::error::OsError),
107    /// wgpu could not produce a usable device or surface — at start-up, or
108    /// when rebuilding after a device loss.
109    Gpu(agg_gui_wgpu::GpuInitError),
110    /// The window's surface stayed unusable — every swap-chain configure
111    /// retry failing — for longer than the retry budget
112    /// ([`agg_gui_wgpu::GpuConfig::surface_retry_budget`]). The shell exits
113    /// with this instead of showing a black window forever.
114    Surface(agg_gui_wgpu::SurfaceError),
115    /// A configured deterministic capture could not be produced.
116    Screenshot(String),
117    /// [`ShellControl::request_relaunch`] could not start the new process.
118    Relaunch(std::io::Error),
119    /// The app's builder closure failed. Build one with [`ShellError::app`].
120    App(Box<dyn std::error::Error + Send + Sync>),
121}
122
123impl ShellError {
124    /// Wrap an app-side start-up failure so a builder closure can use `?`.
125    pub fn app(error: impl Into<Box<dyn std::error::Error + Send + Sync>>) -> Self {
126        Self::App(error.into())
127    }
128}
129
130impl std::fmt::Display for ShellError {
131    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
132        match self {
133            Self::EventLoop(e) => write!(f, "winit event loop: {e}"),
134            Self::CreateWindow(e) => write!(f, "create window: {e}"),
135            Self::Gpu(e) => write!(f, "wgpu init: {e}"),
136            Self::Surface(e) => write!(f, "wgpu surface: {e}"),
137            Self::Screenshot(msg) => write!(f, "screenshot: {msg}"),
138            Self::Relaunch(e) => write!(f, "relaunch: {e}"),
139            Self::App(e) => write!(f, "app start-up: {e}"),
140        }
141    }
142}
143
144impl std::error::Error for ShellError {
145    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
146        match self {
147            Self::EventLoop(e) => Some(e),
148            Self::CreateWindow(e) => Some(e),
149            Self::Gpu(e) => Some(e),
150            Self::Surface(e) => Some(e),
151            Self::Relaunch(e) => Some(e),
152            Self::App(e) => Some(e.as_ref()),
153            Self::Screenshot(_) => None,
154        }
155    }
156}