Skip to main content

Crate agg_gui_shell

Crate agg_gui_shell 

Source
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: 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.

Re-exports§

pub use wgpu;
pub use winit;

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))).
SavedBounds
A persisted window geometry. Sizes are physical pixels.
ScreenshotConfig
Deterministic frame capture: after settle_frames painted frames, read the frame back, write it to path as a PNG, and leave the event loop.
ShellConfig
Everything crate::run needs before the app exists.
ShellControl
Steering handle passed to ShellHost::on_idle.
ShellInit
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.
WgpuGfxCtx
A DrawCtx that renders via wgpu (Vulkan / DX12 / Metal / WebGL2).
WindowGeometry
Window geometry as the OS last reported it. Sizes are physical pixels.
WindowIcon
An RGBA8 window icon, as the OS taskbar / title bar wants it.

Enums§

CopySrc
How badly the caller needs COPY_SRC on the surface texture.
RedrawPolicy
How hard the shell drives the event loop when the app is not asking for frames.
ShellError
Why the shell could not start, or could not finish.
WindowSize
A size in either DPI-independent (logical) or device (physical) pixels.

Traits§

ShellHost
The app side of the shell.
WindowBoundsStore
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::paint to 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.