Trait RasterBackend 

pub trait RasterBackend {
    type Device: RenderDevice;

    // Required methods
    fn new_target(&self, w: u32, h: u32, clear: Color) -> Self::Device;
    fn new_target_with_backdrop(&self, base: &Pixmap) -> Self::Device;
    fn snapshot(&self, d: &Self::Device) -> Pixmap;
    fn finish(&self, d: Self::Device) -> Pixmap;

    // Provided methods
    fn snapshot_rect(
        &self,
        d: &Self::Device,
        origin_x: u32,
        origin_y: u32,
        width: u32,
        height: u32,
    ) -> Pixmap { ... }
    fn composite_isolated_groups_as_layers(&self) -> bool { ... }
}

The factory that lets the engine rasterize offscreen: soft masks, transparency groups, pattern cells and the fill+stroke knockout buffer all need a second target.

Required Associated Types

type Device: RenderDevice

The device this backend produces.

Required Methods

fn new_target(&self, w: u32, h: u32, clear: Color) -> Self::Device

A fresh target of the given size, every pixel set to clear.

Both axes must be at most MAX_TARGET_DIMENSION: vello_cpu sizes its scenes, pixmaps and masks with u16. The engine enforces the bound before calling.

fn new_target_with_backdrop(&self, base: &Pixmap) -> Self::Device

A fresh target seeded with base’s pixels.

This is a non-isolated transparency group’s backdrop (ISO 32000 §11.4.6) and the fill+stroke knockout buffer’s saved destination.

fn snapshot(&self, d: &Self::Device) -> Pixmap

The device’s current pixels, without consuming it.

Only valid with every RenderDevice::push_layer matched by a RenderDevice::pop — vello_cpu asserts it. On a retained-scene backend this costs a full rasterization of the scene so far, not a rectangle copy, which is why the engine renders each group into its own target rather than snapshotting sub-rectangles of a shared one.

fn finish(&self, d: Self::Device) -> Pixmap

Consume the device, yielding its premultiplied RGBA8 pixels.

Provided Methods

fn snapshot_rect( &self, d: &Self::Device, origin_x: u32, origin_y: u32, width: u32, height: u32, ) -> Pixmap

snapshot cropped to (origin_x, origin_y, width, height).

The default is a full snapshot and a host crop. A retained-scene GPU backend still has to rasterize the scene so far — that is the structural cost — but can copy only this rectangle off the device, which is the whole of a non-isolated group’s backdrop.

use pdfrum_raster_vello_cpu::VelloCpuBackend;
use pdfrum_render::RasterBackend;

let backend = VelloCpuBackend;
let device = backend.new_target(4, 4, peniko::Color::WHITE);
let crop = backend.snapshot_rect(&device, 1, 1, 2, 2);
assert_eq!((crop.width(), crop.height()), (2, 2));

fn composite_isolated_groups_as_layers(&self) -> bool

Whether isolated groups should composite as native layers instead of an offscreen pixmap round trip.

The pixmap path is the CPU goldens: finish, multiply_alpha_mask, remove_backdrop. Native layers skip that host stall, which is the GPU win, but they are not bit-identical to the pixmap arithmetic — so the default is false and only a backend that has opted in (the GPU one) takes it. CPU backends keep the board still.

use pdfrum_raster_vello_cpu::VelloCpuBackend;
use pdfrum_render::RasterBackend;

assert!(!VelloCpuBackend.composite_isolated_groups_as_layers());
assert!(!(&VelloCpuBackend).composite_isolated_groups_as_layers());

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementations on Foreign Types

impl<T: RasterBackend + ?Sized> RasterBackend for &T

A reference to a backend is a backend.

Stateless CPU backends are unit structs, so a caller writes page.render(VelloCpuBackend). A backend that holds a device is passed by reference, page.render(&gpu), through this impl — the rasterizer is still named, and nothing is moved.

type Device = <T as RasterBackend>::Device

fn new_target(&self, w: u32, h: u32, clear: Color) -> Self::Device

fn new_target_with_backdrop(&self, base: &Pixmap) -> Self::Device

fn snapshot(&self, d: &Self::Device) -> Pixmap

fn finish(&self, d: Self::Device) -> Pixmap

fn snapshot_rect( &self, d: &Self::Device, origin_x: u32, origin_y: u32, width: u32, height: u32, ) -> Pixmap

fn composite_isolated_groups_as_layers(&self) -> bool

Implementors