agg-gui-shell 0.5.2

Turn-key native shell for agg-gui — winit event loop, wgpu present, input forwarding, window-bounds persistence, and device-loss recovery
Documentation

agg-gui-shell

Turn-key native shell for agg-gui: a winit window, the agg-gui-wgpu renderer presenting to it, and the event loop in between.

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)),
    )
}

The app is built by a closure that runs after the window and GPU exist, so the widget tree sees the real device scale and surface size while it is being constructed.

What the shell owns

  • Window — title, logical or physical initial size, minimum size, RGBA icon, maximized, borderless fullscreen. The first frame is painted into the still-hidden window and the window is shown afterwards, so start-up never flashes an OS-default white background.
  • Input — mouse move/down/up, cursor-leave, modifiers, wheel (with the shift→horizontal remap and no sign flipping, so the OS scroll-direction preference is respected), keyboard down and up, and raw touch forwarded to agg-gui's gesture aggregation.
  • Redraw scheduling — Poll while the app wants frames, WaitUntil for a scheduled deadline, Wait otherwise; or RedrawPolicy::Continuous for an app that wants every frame. The agg-gui host waker is installed so a background thread can wake a parked loop, and cleared on every exit path.
  • Surface health — acquire recovery, resize coalescing (winit can deliver Resized from a modal drag-resize loop), present-mode fallback, and rebuilding the device after a device loss (TDR, driver reset, GPU removal, RDP session change), with a hook telling the app to drop its cached GPU resources.
  • Window-bounds persistence — restores the saved size through a WindowBoundsStore the app implements, sanitised against the real monitor and the GPU's maximum texture dimension. Sizes round-trip in physical pixels; restoring them as logical ones is the DPI ratchet that eventually grows the window past what the GPU can allocate.
  • Deterministic screenshots — paint N settle frames, read the surface back, write a PNG, exit. Failures come back as a ShellError; the shell never exits the process itself.

What the app owns

Everything else, through the ShellHost trait: per-frame state ticks, a custom frame body, GPU read-back between end_frame and present, geometry-change notifications, idle-time work, and exit or relaunch. Every method has a default, so NoHost is a complete implementation.

Versioning note

winit and wgpu types appear in this crate's public API (present mode, the render context, the window handed to the builder closure). Their major versions are therefore part of this crate's public API: a winit 0.31 or wgpu 30 is a breaking release here, and an app must use the same majors this crate does.

License

MIT