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 ;
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 —
Pollwhile the app wants frames,WaitUntilfor a scheduled deadline,Waitotherwise; orRedrawPolicy::Continuousfor 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
Resizedfrom 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
WindowBoundsStorethe 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