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.

Defaults to RunnerCaps::default (everything supported) — appropriate for native adapters. Hosts that can land on GL or browser adapters must instead route through Self::with_caps with RunnerCaps::from_adapter, otherwise stock pipelines fail naga validation on shader-module creation.

pub fn with_caps( device: &Device, queue: &Queue, target_format: TextureFormat, sample_count: u32, caps: RunnerCaps, ) -> Self

Like Self::with_sample_count, but with the adapter caps supplied explicitly — see RunnerCaps for what each cap gates:

Runner::with_caps(&device, &queue, format, sample_count,
                  RunnerCaps::from_adapter(&adapter))

pub fn with_shared_text( device: &Device, queue: &Queue, target_format: TextureFormat, sample_count: u32, caps: RunnerCaps, shared: &SharedText, ) -> Self

Like Self::with_caps, but attached to an existing SharedText pool instead of creating a private one (issue #94). Every runner attached to the same pool shares one font system, one shaping cache, and one set of glyph/MSDF atlas pages on the GPU — a multi-window host pays glyph rasterization, warm-up, and atlas VRAM once per device instead of once per window:

let text = SharedText::new(&device);
text.warm_default_glyphs(); // once, off the open path
let runner_a = Runner::with_shared_text(&device, &queue, fmt_a, 1, caps, &text);
let runner_b = Runner::with_shared_text(&device, &queue, fmt_b, 1, caps, &text);

The pool is device-scoped and format/sample-count independent — runners with different swapchain formats or MSAA settings can share one pool. An existing runner’s pool is available via Self::shared_text. The pool must have been created on the same wgpu::Device.

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_working_color_space(&mut self, space: ColorSpace)

Set the color space the renderer composites in. Hosts call this once after negotiating a surface format with the display server (see damascene-winit-wgpu) and before the first frame. Updates the shared quad path (via RunnerCore) and this backend’s text / icon / image color recorders so every color crosses the working- space boundary consistently.

The working space must match how the swapchain interprets the pixels the renderer writes: SRGB_LINEAR for an *_unorm_srgb surface (the default), SCRGB_LINEAR / DISPLAY_P3_LINEAR for an Rgba16Float surface, etc.

pub fn working_color_space(&self) -> ColorSpace

The color space the renderer currently composites in.

pub fn set_target_format(&mut self, device: &Device, format: TextureFormat)

Rebuild every swapchain-format-bound render pipeline for a new surface format, in place, preserving all other runner state.

The damascene-winit-wgpu host calls this on live color renegotiation — when the display server hands back a different surface format than the one the runner was built with (e.g. Bgra8UnormSrgb ↔ Rgba16Float when HDR turns on or off). The swapchain format is baked into every pipeline’s ColorTargetState, so those pipelines must be recreated; everything else can stay.

What survives: all interaction state in RunnerCore (hover, focus, press, selection, scroll, hotkeys, the laid-out tree snapshot), the glyph + icon MSDF atlases and their GPU page textures, the per-image and app-texture/surface bind-group caches, the scene geometry caches and per-node offscreen targets, and every instance/uniform/vertex buffer. No atlas re-rasterization, no texture re-upload, no layout recompute.

What’s rebuilt: the four stock quad pipelines (rounded_rect, spinner, skeleton, progress_indeterminate), every retained custom shader pipeline, and the swapchain-bound pipelines inside each paint module (text color/MSDF/highlight, icon flat/relief/glass/MSDF, image, surface premul/straight/opaque, and the scene composite — the scene’s offscreen point/line/mesh + occlusion pipelines render to fixed formats and are left alone). The backdrop snapshot texture is dropped so it reallocates in the new format on the next backdrop-sampling frame.

Early-returns when format already matches the current target. sample_count and per_sample_shading are unaffected.

pub fn set_white_scale(&mut self, scale: f32)

Set the output white-level scale (default 1.0). Leave at 1.0 whenever the surface puts reference white at signal 1.0: 8-bit sRGB by definition, and Wayland float swapchains tagged as parametric ext-linear (the WSI default — the compositor anchors signal 1.0 to the output reference; scaling on top double-lifts ~2.5×). Pass damascene_core::color::WINDOWS_SCRGB_WHITE_SCALE only when the surface genuinely reads as Windows scRGB — signal 1.0 = 80 cd/m² absolute, assumed reference white at 2.5375 (203 cd/m², BT.2408) — so SDR-referred UI white lands at the reference level instead of 80 nits.

pub fn set_output_luminance(&mut self, headroom: f32, reference_nits: f32)

Set the output’s luminance frame: headroom = usable range in multiples of reference white (target_max / reference; 1.0 on SDR — the default — or f32::INFINITY when the output declared no maximum) and reference_nits = the output’s reference white in cd/m² (default 203, BT.2408). Feeds FrameUniforms.headroom/ref_nits and the per-image HDR remaster: image draws whose measured content peak exceeds their damascene_core::image::DynamicRangeLimit resolved against this headroom are rolled off (BT.2390) to fit. Hosts re-call this whenever the output’s preferred description changes.

pub fn warm_default_glyphs(&mut self)

Set the theme used to resolve implicit widget surfaces to shaders. Pre-rasterize printable ASCII for the bundled default faces (Inter Variable + JetBrains Mono Variable). Pays the ~40ms one-time MSDF-generation cost up-front so the first frame that introduces each character doesn’t take a 20-30ms paint hit. Hosts that interactively render UI text (the showcase, custom apps, etc.) should call this once after constructing the Runner and before the first frame; headless fixtures that render only static content can skip it. MSDF keys are size-independent so each character is rasterized exactly once and reused for every size + weight afterwards.

pub fn warm_glyphs(&mut self, families: &[FontFamily], chars: &[char])

Pre-rasterize a chosen set of (family, char) glyphs — the app-selectable counterpart to Self::warm_default_glyphs, for fonts you registered yourself or glyph sets beyond printable ASCII. See SharedText::warm_glyphs.

pub fn export_msdf_snapshot(&self) -> Vec<u8>

Serialize the resident outline-glyph atlas into a portable snapshot blob (keyed by font content hash). Persist it and reload with Self::import_msdf_snapshot to skip regenerating those glyphs on a later run — the app-driven equivalent of the built-in prebaked-default-fonts bake. See SharedText::export_msdf_snapshot.

pub fn import_msdf_snapshot( &mut self, bytes: &[u8], ) -> Result<usize, SnapshotError>

Load a snapshot from Self::export_msdf_snapshot, resolving fonts by content hash against those currently loaded. Returns the glyph count loaded, or an error if the blob is stale/unreadable (warm live in that case). See SharedText::import_msdf_snapshot.

pub fn shared_text(&self) -> SharedText

The SharedText pool this runner records text into. Hand it to Self::with_shared_text when constructing further runners on the same device so they share fonts, shaping, and atlases — works whether this runner was built with a shared pool or owns a private one.

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

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 damascene_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, samples_time: bool, )

Register a custom shader, with opt-in flags for backdrop sampling and time-driven motion.

samples_backdrop=true 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.

samples_time=true declares that the shader’s output depends on frame.time. The runtime ORs this into PrepareResult::needs_redraw for any frame that has at least one node bound to the shader, so the host idle loop keeps ticking without a per-El opt-in. Stock shaders self- report through damascene_core::shader::StockShader::is_continuous; this flag is the same signal for app-registered WGSL.

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 Damascene 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 Damascene’s pass.

pub fn snapshot_cursor(&self) -> Cursor

Pointer cursor resolved from the snapshot tree Self::prepare just stored. Call after prepare; paint-only frames keep the previously resolved cursor.

pub fn prepare( &mut self, device: &Device, queue: &Queue, root: 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.

Takes the tree by value: after layout it becomes the hit-test snapshot directly (no whole-tree clone). Read post-layout state through the runner (e.g. Self::snapshot_cursor).

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

Paint-only frame: rerun [RunnerCore::prepare_paint_cached] + GPU upload + frame-uniform write against the cached ops from the most recent Self::prepare call. Skips rebuild + layout

• draw_ops + snapshot — only frame.time advances.

Hosts call this when PrepareResult::next_paint_redraw_in fires (a time-driven shader needs another frame) and no input has been processed since the last full prepare. Input always upgrades to the full prepare(...) path.

viewport and scale_factor must match the values passed to the most recent prepare(...) — a resize must go through the full layout path. Returns the same shape of PrepareResult for diagnostic continuity, with both deadlines re-computed from the cached signals: next_layout_redraw_in is None (we didn’t re-evaluate), and next_paint_redraw_in is whatever the cached ops still report. The host owns the layout deadline across paint-only frames.

pub fn pointer_moved(&mut self, p: Pointer) -> PointerMove

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 p.x, p.y (logical px). Returns the events to dispatch via App::on_event plus a needs_redraw flag — see PointerMove for why hosts must gate request_redraw on the flag. The hovered node is updated on ui_state().hovered regardless. Mouse-only hosts can construct p via Pointer::moving.

pub fn pointer_left(&mut self) -> Vec<UiEvent>

Pointer left the window — clear hover/press. Returns a PointerLeave event for the previously hovered target (when there was one); hosts should route the events through App::on_event like the other pointer entry points.

pub fn pointer_cancelled(&mut self) -> Vec<UiEvent>

The platform cancelled the pointer sequence (touch cancel / pointercancel) — abandons in-flight presses and gesture captures without applying release effects. Route the events through App::on_event like the other pointer entry points.

pub fn file_hovered(&mut self, path: PathBuf, x: f32, y: f32) -> Vec<UiEvent>

File is being dragged over the window. Hosts call this from winit::WindowEvent::HoveredFile (one call per file). Returns the FileHovered event routed to the keyed leaf at the cursor (or window-level if outside any keyed surface).

pub fn file_hover_cancelled(&mut self) -> Vec<UiEvent>

File hover ended without a drop — hosts call this from winit::WindowEvent::HoveredFileCancelled. Window-level event (not routed); apps clear any drop-zone affordance.

pub fn file_dropped(&mut self, path: PathBuf, x: f32, y: f32) -> Vec<UiEvent>

File was dropped on the window. Hosts call this from winit::WindowEvent::DroppedFile (one call per file).

pub fn would_press_focus_text_input(&self, x: f32, y: f32) -> bool

Whether a primary press at (x, y) (logical px) would land on a node that opted into capture_keys — the marker the library uses for text-input-style widgets. Hosts query this from a DOM pointerdown handler to decide whether to focus a hidden textarea (so the soft keyboard can open in the user-gesture context). See [RunnerCore::would_press_focus_text_input] for details.

pub fn focused_captures_keys(&self) -> bool

Whether the currently focused node is a text-input-style widget (i.e. has capture_keys set). Hosts mirror this each frame into platform affordances such as the on-screen keyboard or IME compose-window placement.

pub fn pointer_down(&mut self, p: Pointer) -> Vec<UiEvent>

Pointer pressed at p.x, p.y (logical px) for p.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. Mouse-only hosts can construct p via Pointer::mouse.

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, p: Pointer) -> Vec<UiEvent>

Pointer released at p.x, p.y for p.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. Mouse-only hosts can construct p via Pointer::mouse.

pub fn key_down( &mut self, logical: LogicalKey, physical: PhysicalKey, modifiers: KeyModifiers, repeat: bool, ) -> Vec<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.

The registry is scoped to this Runner — in a multi-window host (one Runner per window), pass each window only its own list and feed each window’s key events only to its own Runner; chords then fire per focused window. See damascene_core::App::hotkeys for the full convention.

pub fn set_selection(&mut self, selection: Selection)

Push the app’s current selection to the runtime so the painter can draw highlight bands. Hosts call this once per frame alongside Self::set_hotkeys.

pub fn selected_text(&self) -> Option<String>

Resolve the runtime’s current selection to a text payload from the most recently laid-out tree. See [RunnerCore::selected_text] — virtual-list rows are realized during layout, so a freshly built app tree would miss them and a Ctrl+C lookup that walked it would silently come back empty.

pub fn selected_text_for(&self, selection: &Selection) -> Option<String>

Resolve an explicit damascene_core::selection::Selection against the last laid-out tree. See [RunnerCore::selected_text_for].

pub fn push_toasts(&mut self, specs: Vec<ToastSpec>)

Queue toast specs onto the runtime’s toast stack. Hosts call this once per frame with app.drain_toasts(). Each spec is stamped with a monotonic id and an expires_at deadline (now + ttl); the next prepare call drops expired entries and synthesizes a toast_stack floating layer over the rest.

pub fn dismiss_toast(&mut self, id: u64)

Programmatically dismiss a toast by id. Useful for cancelling long-TTL toasts when an external condition resolves (e.g., “reconnecting…” turning into “connected”).

pub fn push_focus_requests(&mut self, keys: Vec<String>)

Queue programmatic focus requests by widget key. Hosts call this once per frame with app.drain_focus_requests(). Each key is resolved during the next prepare against the rebuilt focus order; unmatched keys drop silently.

pub fn push_scroll_requests(&mut self, requests: Vec<ScrollRequest>)

Queue programmatic scroll-to-row requests targeting virtual lists by key. Hosts call this once per frame with app.drain_scroll_requests(). Each request is consumed during the next prepare by the layout pass for the matching list, where viewport height and row heights are known. Unmatched list keys and out-of-range row indices drop silently.

pub fn push_viewport_requests(&mut self, requests: Vec<ViewportRequest>)

pub fn push_plot_requests(&mut self, requests: Vec<PlotRequest>)

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 pointer_wheel_event( &mut self, x: f32, y: f32, dx: f32, dy: f32, ) -> Option<UiEvent>

Build a routed wheel event for the keyed target under (x, y).

Dispatch this before Self::pointer_wheel; if the app consumes the event, skip the fallback scroll call.

pub fn poll_input(&mut self, now: Instant) -> Vec<UiEvent>

Drain time-driven input events whose deadline has passed (touch long-press today; later: hold-to-repeat, etc.). Hosts call this once per frame before dispatching pointer events. now is web_time::Instant rather than std::time::Instant so the signature compiles on wasm32 — web_time aliases to std on native, so existing native callers passing Instant::now() from std still work. See [damascene_core::RunnerCore::poll_input].

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.

3D scenes need the pre-pass. Scene3D paint items composite from offscreen targets that must be rendered before the host’s pass begins — call Self::encode_scene_prepass on the encoder first, or every scene in the frame samples a never-rendered target and composites blank.

pub fn encode_scene_prepass( &mut self, device: &Device, encoder: &mut CommandEncoder, )

Encode the offscreen pre-pass for any 3D scenes in this frame’s paint stream: each Scene3D renders into its own offscreen target, and label-bearing scenes capture depth for next frame’s label occlusion. No-op when the frame has no scenes.

Self::render calls this automatically. Hosts using Self::draw must call it on their encoder after Self::prepare and before beginning the render pass that draw records into.

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.