Struct Runner 

pub struct Runner { /* private fields */ }

Wgpu runtime owned by the host. One instance per surface/format.

All backend-agnostic state — interaction state, paint-stream scratch, per-stage layout/animation hooks — lives in core: RunnerCore and is shared with the vulkano backend. The fields below are wgpu-specific resources only.

Implementations

impl Runner

pub fn new(device: &Device, queue: &Queue, target_format: TextureFormat) -> Self

Create a runner for the given target color format. The host passes its swapchain/render-target format here so pipelines and the glyph atlas are built compatible.

pub fn with_sample_count( device: &Device, _queue: &Queue, target_format: TextureFormat, sample_count: u32, ) -> Self

Like Self::new, but builds all pipelines with sample_count MSAA samples. The host must provide a matching multisampled render target and a single-sample resolve target. sample_count of 1 is the non-MSAA default.

pub fn set_surface_size(&mut self, width: u32, height: u32)

Tell the runner the swapchain texture size in physical pixels. Call this once after surface.configure(...) and again on every WindowEvent::Resized. The runner uses this as the canonical viewport_px for scissor math; without it, the value is derived from viewport.w * scale_factor, which can drift by one pixel when scale_factor is fractional and trip wgpu’s set_scissor_rect validation.

pub fn set_theme(&mut self, theme: Theme)

Set the theme used to resolve implicit widget surfaces to shaders.

pub fn theme(&self) -> &Theme

pub fn set_icon_material(&mut self, material: IconMaterial)

Select the stock material used by the vector-icon painter. Prefer Theme::with_icon_material for app-level routing; this remains useful for low-level render fixtures.

pub fn icon_material(&self) -> IconMaterial

pub fn register_shader( &mut self, device: &Device, name: &'static str, wgsl: &str, )

Register a custom shader. name is the same string passed to aetna_core::shader::ShaderBinding::custom; nodes bound to it via El::shader paint through this pipeline.

The WGSL source must use the shared (rect, vec_a, vec_b, vec_c) instance layout and the FrameUniforms bind group described in the module docs. Compilation happens at register time — invalid WGSL panics here, not mid-frame.

Re-registering the same name replaces the previous pipeline (useful for hot-reload during development).

pub fn register_shader_with( &mut self, device: &Device, name: &'static str, wgsl: &str, samples_backdrop: bool, )

Register a custom shader, with an opt-in flag for backdrop sampling. When samples_backdrop is true, the renderer schedules the shader’s draws into Pass B (after a snapshot of Pass A’s rendered content) and binds the snapshot texture as @group(2) binding=0 (backdrop_tex) plus a sampler at binding=1 (backdrop_smp). See docs/SHADER_VISION.md §“Backdrop sampling architecture”.

Backdrop depth is capped at 1: glass-on-glass shows the same underlying content, not a second snapshot of the first glass composited.

pub fn ui_state(&self) -> &UiState

Borrow the internal UiState — primarily for headless fixtures that want to look up a node’s rect after prepare (e.g., to simulate a pointer at a specific button’s center).

pub fn debug_summary(&self) -> String

One-line diagnostic snapshot of interactive state — passes through to UiState::debug_summary. Intended for per-frame logging (e.g., console.log from the wasm host while debugging hover / animation glitches).

pub fn rect_of_key(&self, key: &str) -> Option<Rect>

Return the most recently laid-out rectangle for a keyed node.

Call after Self::prepare. This is the host-composition hook: reserve a keyed Aetna element in the UI tree, ask for its rect here, then record host-owned rendering into that region using the same encoder / render flow that surrounds Aetna’s pass.

pub fn prepare( &mut self, device: &Device, queue: &Queue, root: &mut El, viewport: Rect, scale_factor: f32, ) -> PrepareResult

Lay out the tree, resolve to draw ops, and upload per-frame buffers (quad instances + glyph atlas). Must be called before Self::draw and outside of any render pass.

viewport is in logical pixels — the units the layout pass works in. scale_factor is the HiDPI multiplier (1.0 on a regular display, 2.0 on most modern HiDPI, can be fractional). The host’s render-pass target should be sized at physical pixels (viewport × scale_factor); the runner maps logical → physical internally so layout, fonts, and SDF math stay device-independent.

pub fn pointer_moved(&mut self, x: f32, y: f32) -> Option<UiEvent>

Update pointer position and recompute the hovered key. Returns the new hovered key, if any (host can use it for cursor styling or to decide whether to call request_redraw). Pointer moved to (x, y) (logical px). Returns a Drag event when the primary button is held; the host should dispatch it via App::on_event. The hovered node is updated on ui_state().hovered regardless.

pub fn pointer_left(&mut self)

Pointer left the window — clear hover/press.

pub fn pointer_down( &mut self, x: f32, y: f32, button: PointerButton, ) -> Option<UiEvent>

Mouse button down at (x, y) (logical px) for the given button. For Primary, records the pressed key for press- visual feedback, updates focus, and returns a PointerDown event so widgets that need to react at down-time (text input selection anchor, draggable handles) can do so. For Secondary / Middle, records on a side channel and returns None. The actual click event fires on pointer_up.

pub fn set_modifiers(&mut self, modifiers: KeyModifiers)

Replace the tracked modifier mask. Hosts call this from their platform’s “modifiers changed” hook so subsequent pointer events (PointerDown, Drag, Click, …) stamp the current mask into UiEvent.modifiers.

pub fn pointer_up( &mut self, x: f32, y: f32, button: PointerButton, ) -> Vec<UiEvent>

Mouse button up at (x, y) for the given button. Returns the events the host should dispatch in order: for Primary, always a PointerUp (when there was a corresponding down) followed by an optional Click (when the up landed on the down’s node). For Secondary / Middle, an optional SecondaryClick / MiddleClick on the same-node match.

pub fn key_down( &mut self, key: UiKey, modifiers: KeyModifiers, repeat: bool, ) -> Option<UiEvent>

pub fn text_input(&mut self, text: String) -> Option<UiEvent>

Forward an OS-composed text-input string (winit’s keyboard event .text field, or an Ime::Commit) to the focused element as a TextInput event.

pub fn set_hotkeys(&mut self, hotkeys: Vec<(KeyChord, String)>)

Replace the hotkey registry. Call once per frame, after app.build(), passing app.hotkeys() so chords stay in sync with state.

pub fn set_animation_mode(&mut self, mode: AnimationMode)

Switch animation pacing. Default is AnimationMode::Live. Headless render binaries should call this with AnimationMode::Settled so a single-frame snapshot reflects the post-animation visual without depending on integrator timing.

pub fn pointer_wheel(&mut self, x: f32, y: f32, dy: f32) -> bool

Apply a wheel delta in logical pixels at (x, y). Routes to the deepest scrollable container under the cursor in the last laid-out tree. Returns true if the event landed on a scrollable (host should request_redraw so the next frame applies the new offset).

pub fn draw<'pass>(&'pass self, pass: &mut RenderPass<'pass>)

Record draws into the host-managed render pass. Call after Self::prepare. Paint order follows the draw-op stream.

No backdrop sampling. This entry point cannot honor pass boundaries (the host owns the pass lifetime), so any BackdropSnapshot items in the paint stream are no-ops and any shader bound with samples_backdrop=true reads an undefined backdrop binding. Use Self::render for backdrop-aware rendering.

pub fn render( &mut self, device: &Device, encoder: &mut CommandEncoder, target_tex: &Texture, target_view: &TextureView, msaa_view: Option<&TextureView>, load_op: LoadOp<Color>, )

Record draws into a host-supplied encoder, owning pass lifetimes ourselves so backdrop-sampling shaders can sample a snapshot of Pass A’s content.

The host hands us:

• the encoder (we record into it),
• the color target’s wgpu::Texture (used as copy_src when we snapshot it; must include COPY_SRC in its usage flags),
• the corresponding wgpu::TextureView (we attach it to every render pass we begin), and
• the LoadOp to use on the first pass — Clear(color) to clear behind us, Load to composite onto whatever was already in the target.

Multi-pass schedule when the paint stream contains a BackdropSnapshot:

1. Pass A — every paint item before the snapshot, with the caller-supplied LoadOp.
2. copy_texture_to_texture — target → snapshot.
3. Pass B — paint items from the snapshot onward, with LoadOp::Load so Pass A’s pixels remain underneath.

Without a snapshot, this collapses to a single pass and is equivalent to Self::draw called inside a host-managed pass with the same LoadOp.