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}