Module offscreen 

Headless offscreen render harness: renders a Vello Scene into a GPU texture with no window, reads the bytes back and optionally writes a PNG.

The row pitch is padded to COPY_BYTES_PER_ROW_ALIGNMENT (256) and stripped on readback.

Two renders of the same scene are not byte-identical: vello sums path segments in tile completion order, so coverage on a quantisation boundary can land one unit either way (measured: ≤4 pixels of 57 600, always ±1, ink unchanged). VELLO_CANONICAL_SEGMENT_ORDER=1 fixes the order for a capture, but a scene’s order also follows its encoding, so two scenes differing in a distant path can still differ by one unit. Compare frames with OffscreenRenderer::pixels_differing_beyond_aa, never byte equality; retained paint matches a full render within the same ±1. Stored pixels are straight alpha: RGB in fully transparent pixels is invisible, any nonzero alpha keeps the tolerance in every channel, and exact untouched-pixel assertions are separate byte-preservation checks.

Never cache one in a thread_local!: dropping wgpu resources touches wgpu’s own thread-local, and TLS destructors run in reverse registration order, so a cache registered before the first wgpu call is torn down after wgpu’s — SIGABRT. Use a process-wide static (never drops); the type is Send to allow that.

Modules

pixels

The pixels of a scene, for an app that reads them: the colour under an eyedropper, a picture being exported.

Structs

CpuSurface

A surface’s frames kept in memory and drawn on the CPU: what a host shows on a machine where the toolkit has no GPU adapter to draw them on, exactly as it draws a normal app’s frame there. Kept between frames, so damage costs only what it changed.

OffscreenMemoryStats

OffscreenRenderTiming

Host-side phases of one completed offscreen render, populated only by OffscreenRenderer::render_damage_regions_gpu_wait_profiled: vello_submit_us covers scene resolution, uploads and the shared queue submission; copy_submit_us only dirty-copy encoding in Vello’s post-render callback; settle_wait_us the blocking GPU-complete wait for bump counters.

OffscreenRenderer

An offscreen wgpu + vello pipeline sized at width × height. Reuse one instance across renders: adapter and device creation is the expensive part.

PathAttemptAccounting

Opt-in render passes recorded since an explicit measured-workload reset, full passes and sparse ones apart. Counters describe synchronous route attempts only, including retries, not completion or speed.

SharedGpu

Handles to the process-wide shared wgpu device every OffscreenRenderer draws through: an app doing its own headless GPU work (the video editor’s compositor) borrows these rather than standing up a second wgpu::Instance, which is why the shared context exists. Both handles are Arc-backed inside wgpu, so they stay valid once the lock is released.

SparseSubmissionAccounting

Lightweight accounting for actual sparse submissions. Unlike OffscreenRenderTiming, this is updated for every sparse attempt, including one that later overflows into dense recovery.

Enums

OffscreenError

Why an OffscreenRenderer could not be built: every variant is an environment failure. Bad arguments (a zero width or height) stay an assert! in the constructors — a caller bug.

Constants

MAX_CAPTURE_DEVICE_SCALE

The largest device scale a capture draws at: a glyph sheet enlarged from the outlines (16x); --device-scale itself stops at 4.

Functions

capture_device_scale

The device scale captures draw at (set_capture_device_scale).

disable_gpu

Make every following shared_gpu and OffscreenRenderer answer OffscreenError::NoAdapter without probing, so callers take their CPU fallback. For a process confined where the GPU driver cannot start (a sandbox denying IOKit and Mach lookups), where probing fails slowly or aborts inside the driver. Cannot be undone.

gpu_disabled

Whether disable_gpu was called in this process.

render_picture

What scene draws over bg at width x height, as straight-alpha RGBA8. Drawn on the GPU when a renderer can be built, else on the CPU with tilo-cpu-raster; a browser page, which has no CPU rasterizer, gets an error. Each call builds a fresh renderer: a caller drawing many pictures of one size keeps its own OffscreenRenderer.

set_capture_device_scale

Draw following capture frames at scale device pixels per logical pixel, as a HiDPI display does: laid out at its logical size and drawn with the live host’s window scale transform, so text is rasterised from the outlines rather than enlarged afterwards. Clamped to 1..=MAX_CAPTURE_DEVICE_SCALE.

shared_adapter_info

The adapter the toolkit’s shared device draws on, for a frame path to ask before it builds a renderer. Opens the device on the first call, as shared_gpu does.

shared_gpu

Borrow the shared device/queue, initialising the process-wide context on first call.

Type Aliases

AreaPpt8AttemptAccounting

Actual Area PPT8 passes.

CanonicalSegmentOrderAttemptAccounting

Actual canonical-segment-order passes.

ClipSingleGroupAttemptAccounting

Actual single-workgroup clip leaf passes.