Expand description
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.
use agg_gui_shell::{run, NoHost, ShellConfig};
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:
Pollwhile the app wants frames,WaitUntilfor a scheduled deadline,Waitotherwise — orRedrawPolicy::Continuouswhen the app wants every frame. - The agg-gui host waker, so a background thread’s
animation::signal_async_state_changewakes 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.
Re-exports§
Structs§
- Frame
- What the shell knows about the frame it is about to paint.
- Gpu
- wgpu device + surface bundle for one OS window.
- NoHost
- A host with nothing to add —
run(config, |_| Ok((app, NoHost))). - Saved
Bounds - A persisted window geometry. Sizes are physical pixels.
- Screenshot
Config - Deterministic frame capture: after
settle_framespainted frames, read the frame back, write it topathas a PNG, and leave the event loop. - Shell
Config - Everything
crate::runneeds before the app exists. - Shell
Control - Steering handle passed to
ShellHost::on_idle. - Shell
Init - Everything the shell knows once the window and GPU exist but before the app is built — what a builder closure needs to size its first layout or share the device with an app-owned renderer.
- Wgpu
GfxCtx - A
DrawCtxthat renders viawgpu(Vulkan / DX12 / Metal / WebGL2). - Window
Geometry - Window geometry as the OS last reported it. Sizes are physical pixels.
- Window
Icon - An RGBA8 window icon, as the OS taskbar / title bar wants it.
Enums§
- CopySrc
- How badly the caller needs
COPY_SRCon the surface texture. - Redraw
Policy - How hard the shell drives the event loop when the app is not asking for frames.
- Shell
Error - Why the shell could not start, or could not finish.
- Window
Size - A size in either DPI-independent (logical) or device (physical) pixels.
Traits§
- Shell
Host - The app side of the shell.
- Window
Bounds Store - Where the shell restores window bounds from and saves them to.
Functions§
- default_
paint - The default frame body: reset, lay out if anything that feeds layout
changed, paint. Exposed so a host that overrides
ShellHost::paintto add work around the frame can still delegate the frame itself. - run
- Open a window, bring up wgpu, build the app, and run the event loop until the window closes.
- sanitize_
restored_ window_ size - Clamp a saved (physical-px) window size into a usable, GPU-safe range.