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