Struct OffscreenRenderer 

pub struct OffscreenRenderer {
    pub width: u32,
    pub height: u32,
    /* private fields */
}

An offscreen wgpu + vello pipeline sized at width × height. Reuse a single instance for multiple renders to amortise adapter / device creation (which is the expensive part).

Fields

width: u32

height: u32

Implementations

impl OffscreenRenderer

pub fn memory_stats(&self) -> OffscreenMemoryStats

pub fn new(width: u32, height: u32) -> OffscreenRenderer

Panics if no suitable adapter exists. Do not try to soften that with std::panic::catch_unwind — the shipping release profile sets panic = "abort", under which a panic kills the process at the panic site and catch_unwind never sees it. Callers that need a soft-fail path must use try_new.

Panics

Panics if try_new returns an OffscreenError — see its variants for exactly when that happens.

pub fn try_new( width: u32, height: u32, ) -> Result<OffscreenRenderer, OffscreenError>

For any code path that has to survive a GPU-less machine, since catch_unwind can’t (see new). Still asserts on a zero width or height — that’s a caller bug, not an environment one.

Errors

Returns OffscreenError::NoAdapter when no wgpu adapter is available (a headless machine typically needs llvmpipe/lavapipe installed), OffscreenError::Renderer when vello fails to build a renderer for the adapter, and OffscreenError::ContextPoisoned when the shared RenderContext mutex was poisoned by a panic on another thread.

Panics

Panics if width or height is zero — that’s a caller bug, not a recoverable environment failure.

pub fn try_new_with_cpu_preprocessing( width: u32, height: u32, ) -> Result<OffscreenRenderer, OffscreenError>

Use stable CPU segment ordering with Vello’s production GPU fine rasterizer. Exact pixel comparisons can select this per instance without changing process-wide renderer settings.

Errors

Returns the same adapter and renderer errors as Self::try_new.

Panics

Panics on zero dimensions, as Self::try_new does.

pub fn set_backdrop(&mut self, backdrop: Option<Arc<BackdropFrame>>)

Draw the floating surfaces of the scenes rendered from now on over backdrop, the frame their host recorded with them (for the shell, FrameBuilder::take_backdrop). None draws them opaque.

pub fn render(&mut self, scene: &Scene, bg: AlphaColor<Srgb>) -> Vec<u8>

pub fn readback_current(&mut self) -> Vec<u8>

Read the already-rendered retained target without submitting another Vello frame. Used to verify partial-damage composition pixel-for-pixel.

Panics

Panics if the shared GPU context or target readback fails.

pub fn render_gpu_wait(&mut self, scene: &Scene, bg: AlphaColor<Srgb>)

Submit a render and wait for its GPU work without copying the target back to CPU memory.

Performance harnesses use this to measure Vello rather than PCIe/shared memory readback plus row repacking. Screenshot and visual-regression callers should continue to use Self::render.

Panics

If shared GPU state is poisoned/missing or Vello rejects the render.

pub fn render_damage_gpu_wait( &mut self, scene: &Scene, bg: AlphaColor<Srgb>, damage: Rect, ) -> u64

Update one native-resolution rectangle in the retained target and wait for completion. Pixels outside damage are preserved exactly; no resizing or upscaling is involved.

Returns the number of pixels actually rasterized. An invalid or full-size damage rectangle falls back to a complete target render.

Panics

Panics if the shared GPU context is unavailable or Vello rejects the render. This is a benchmark/test primitive and cannot produce a valid timing sample after either failure.

pub fn render_damage_regions_gpu_wait( &mut self, scene: &Scene, bg: AlphaColor<Srgb>, damage: &[Rect], ) -> u64

Batched form of Self::render_damage_gpu_wait. Render the scene once at its original coordinates into a scratch target extending from the native origin through the damage bounds, then copy only dirty regions. Keeping native coordinates preserves full-render text coverage. If either the damage or this scratch extent covers at least half the output, use a full render to bound scratch memory. The final wait and reported raster work include any overflow-recovery passes.

Panics

Panics under the same conditions as Self::render_damage_gpu_wait.

pub fn render_copies_and_damage_gpu_wait( &mut self, scene: &Scene, bg: AlphaColor<Srgb>, copies: &[DeviceCopy], damage: &[Rect], ) -> u64

Self::render_damage_regions_gpu_wait after moving pixels within the retained target by copies, in order, as a window presents a scroll (crate::scroll_copy). With no valid target, or a copy that would leave it, the frame renders whole.

Panics

Panics under the same conditions as Self::render_damage_gpu_wait.

pub fn render_damage_regions_gpu_wait_profiled( &mut self, scene: &Scene, bg: AlphaColor<Srgb>, damage: &[Rect], ) -> (u64, OffscreenRenderTiming)

Profile the existing damage render without adding GPU work or readback. This opt-in path alone reads host clocks around submission and the existing final settle wait.

pub fn render_rgba(&mut self, scene: &Scene) -> Vec<u8>

render with a transparent background.

pub fn render_resilient( &mut self, scene: &Scene, bg: AlphaColor<Srgb>, ) -> Vec<u8>

Render until Vello confirms that no bump-allocated geometry was dropped, up to a strict attempt limit. This checks the renderer’s GPU counters, so partially missing glyphs are caught as reliably as a completely transparent failed frame.

Panics

Panics when Vello cannot produce two consecutive valid submissions within the bounded retry count. Returning partial screenshot pixels would make visual-regression output silently untrustworthy.

pub fn try_render_resilient( &mut self, scene: &Scene, bg: AlphaColor<Srgb>, ) -> Result<Vec<u8>, String>

Self::render_resilient for a caller that can answer a failure instead of stopping: an app rendering a picture someone asked for.

Errors

Returns why no two consecutive overflow-free renders came within the bounded retry count.

pub fn render_rgba_resilient(&mut self, scene: &Scene) -> Vec<u8>

Render a one-shot scene without accepting Vello’s transparent bump-buffer warm-up frame. Interactive rendering naturally gets a next frame after the reservation grows; screenshots, first recording frames and deterministic visual snapshots do not, so they retry here.

pub fn render_png<P>(&mut self, scene: &Scene, bg: AlphaColor<Srgb>, path: P)

where P: AsRef<Path>,

Convenience: render scene and write the result to path as a PNG. Creates parent dirs if they don’t exist.

Panics

Panics if path’s file cannot be created or PNG encoding fails — both are dev/test-environment problems (disk full, bad permissions) with no recoverable action for this infallible, shots/test-only helper to take.

pub fn sample(rgba: &[u8], width: u32, x: u32, y: u32) -> (u8, u8, u8, u8)

Sample the RGBA at (x, y) from a tight-packed buffer (4 * width bytes per row). Returns (r, g, b, a).

Panics

Panics if (x, y) is outside rgba. Every real call site is test code asserting against known-valid coordinates (see the crate’s render tests), so an out-of-range sample is a test bug that should fail loudly rather than silently read back 0.

pub fn pixels_differing_beyond_aa(a: &[u8], b: &[u8]) -> usize

Compares stored straight-alpha RGBA8 pixels with the ±1 antialiasing tolerance described in the module docs. RGB in fully transparent pixels is invisible; if either pixel has nonzero alpha, every channel participates in the tolerance. Buffers of different lengths count as differing everywhere they don’t overlap.