Struct OffscreenRenderer 

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

An offscreen wgpu + vello pipeline sized at width × height. Reuse one instance across renders: adapter and device creation 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

Do not soften that with std::panic::catch_unwind — the release profile sets panic = "abort", so a panic kills the process at its site. A soft-fail caller uses try_new.

Panics

Whenever try_new returns an OffscreenError.

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

For a code path that must survive a GPU-less machine, since catch_unwind can’t (see new).

Errors

OffscreenError::NoAdapter with no wgpu adapter (a headless machine typically needs llvmpipe/lavapipe), Renderer when vello cannot build a renderer for it, [ContextPoisoned] when another thread poisoned the shared context, [CannotWait] on a thread that cannot wait for the GPU (a browser page).

Panics

Panics if width or height is zero — a caller bug, not an environment failure.

The renderer is a capture’s: it sums segments in a fixed order, so one scene renders to the same pixels every time. Frames only shown, never kept or compared, use try_new_live.

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

try_new for frames that are shown and replaced, as a headless desktop’s or a window preview’s: segments sum in the order tiles finish, which may move an antialiased edge by one unit. It builds no segment-ordering pipelines, which lavapipe keeps in the heap for the renderer’s lifetime — several MiB of an idle desktop.

Errors

As try_new.

Panics

On zero dimensions, as try_new.

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

Stable CPU segment ordering with Vello’s production GPU fine rasterizer, per instance, so an exact pixel comparison changes no process-wide renderer setting.

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 scenes rendered from now on over backdrop, the frame their host recorded with them; None draws them opaque.

pub fn backdrop_stats(&self) -> BackdropStats

What the backdrop pass did for the last render: regions substituted, and how many of those came from the kept sample.

pub fn readback_into( &mut self, origin: (u32, u32), size: (u32, u32), into: &mut [u8], )

Copy size pixels at origin of the target as last drawn into into, packed as Self::readback_current returns them. Only that part leaves the GPU and nothing outside it in into is touched, so a frame that changed a part costs the part.

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.

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, so a performance harness measures Vello rather than readback and row repacking. Screenshot and visual-regression callers use Self::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, keeping pixels outside damage exactly. Returns the number of pixels rasterized; an invalid or full-size rectangle falls back to a complete target render.

Panics

Panics if the shared GPU context is unavailable or Vello rejects the render: a timing sample after either is invalid anyway.

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 once at the scene’s own coordinates into a scratch target from the native origin through the damage bounds (keeping native coordinates preserves full-render text coverage), then copy only dirty regions. Damage or a scratch extent over half the output falls back to a full render to bound scratch memory.

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 no bump-allocated geometry was dropped, up to a strict attempt limit: its GPU counters catch partially missing glyphs as reliably as a transparent frame.

Panics

When Vello cannot produce two consecutive valid submissions within the bounded count: 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.

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: an interactive renderer gets a next frame after the reservation grows, a screenshot does not.

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

where P: AsRef<Path>,

Render scene and write it to path as a PNG, creating parent dirs.

Panics

If the file cannot be created or PNG encoding fails — dev-environment problems this test-only helper has no action for.

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

The (r, g, b, a) at (x, y) in a buffer packed at 4 * width bytes per row.

Panics

If (x, y) is outside rgba: every caller is a test asserting known-valid coordinates, so an out-of-range sample is a test bug that should fail loudly, not read back 0.

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

Compare stored straight-alpha RGBA8 pixels with the module’s ±1 tolerance. RGB in fully transparent pixels is invisible; with either alpha nonzero every channel participates. Buffers of different lengths differ everywhere they do not overlap.

pub fn differing_beyond_aa( a: &[u8], b: &[u8], width: usize, ) -> (usize, Option<(usize, usize, usize, usize)>)

How many pixels differ and the rectangle they fall in, for frames width pixels wide: (left, top, right, bottom), far edges exclusive, or None. Frames of different lengths are compared where they overlap and the rest is counted.

pub fn positions_differing_beyond_aa( a: &[u8], b: &[u8], width: usize, ) -> Vec<(usize, usize)>

Where Self::pixels_differing_beyond_aa finds two equally long frames width pixels wide differ, as (x, y).