Skip to main content

ShellHost

Trait ShellHost 

Source
pub trait ShellHost {
    // Provided methods
    fn on_frame(&mut self, _app: &mut App, _frame: &Frame) { ... }
    fn paint(&mut self, app: &mut App, ctx: &mut WgpuGfxCtx, frame: &Frame) { ... }
    fn after_paint(&mut self, _ctx: &mut WgpuGfxCtx, _frame: &Frame) { ... }
    fn on_geometry_changed(&mut self, _geometry: WindowGeometry) { ... }
    fn on_close_requested(&mut self, _app: &mut App) -> bool { ... }
    fn on_idle(&mut self, _app: &mut App, _control: &mut ShellControl<'_>) { ... }
    fn on_gpu_rebuilt(&mut self, _app: &mut App, _gpu: &Gpu) { ... }
    fn on_exit(&mut self, _app: &mut App) { ... }
}
Expand description

The app side of the shell.

The host owns whatever the app needs that is not the widget tree — persistence handles, diagnostic state, GPU-readback plumbing — and the shell calls into it around each frame and each idle iteration.

Provided Methods§

Source

fn on_frame(&mut self, _app: &mut App, _frame: &Frame)

Runs at the start of every painted frame, before layout and paint. The hook for per-frame app state: advancing a wall-clock cell, pushing frame.duration into a history buffer, feeding a runaway detector.

Source

fn paint(&mut self, app: &mut App, ctx: &mut WgpuGfxCtx, frame: &Frame)

Render the frame’s contents.

The default resets the context, lays out when frame.needs_layout, and paints — which is all most apps want. Override to wrap layout/paint in app-specific plumbing (a live inspector’s edit queues, for example); the shell has already begun the frame and will call end_frame and present afterwards.

Source

fn after_paint(&mut self, _ctx: &mut WgpuGfxCtx, _frame: &Frame)

Runs after WgpuGfxCtx::end_frame and before present.

The only place a GPU copy off the surface texture can happen: wgpu’s swap chain takes ownership of that texture at present. frame is the same descriptor ShellHost::paint just saw — a read-back needs the surface size, and a capture that only fires on some frames needs the frame index.

Source

fn on_geometry_changed(&mut self, _geometry: WindowGeometry)

The OS window was resized, maximized, restored, or changed scale.

Source

fn on_close_requested(&mut self, _app: &mut App) -> bool

The user asked the OS window to close (title-bar ×, Alt+F4, taskbar close). Return true to let the shell exit the loop; return false to keep running.

This is where an unsaved-changes gate lives: prompt here (a blocking native dialog is fine — no frame is in flight), and either allow the close, or return false and finish an asynchronous save from ShellHost::on_idle, calling ShellControl::request_exit once it lands. Not called for ShellControl::request_exit / request_relaunch (the app already decided) or when a configured screenshot capture completes.

Source

fn on_idle(&mut self, _app: &mut App, _control: &mut ShellControl<'_>)

Runs once per idle iteration of the event loop, after any frame this iteration painted. The hook for app-owned auto-save, deferred work that must not run inside event dispatch, and exit/relaunch requests.

Source

fn on_gpu_rebuilt(&mut self, _app: &mut App, _gpu: &Gpu)

The wgpu device was lost (TDR, driver reset, GPU removal, RDP session change) and the shell has rebuilt it. Every GPU resource created from the old device is dead — textures, buffers, pipelines cached by custom-render widgets — so drop them here and let them be recreated from gpu on the next frame.

Source

fn on_exit(&mut self, _app: &mut App)

The loop is about to exit (window closed, exit requested, or a screenshot run finished). Last chance to flush state.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§