embedded-graphics-readback 0.1.0

A ReadbackTarget capability trait for embedded-graphics — sample the pixels already on a draw target. no_std.
Documentation

embedded-graphics-readback

A pixel-readback capability for embedded-graphics draw targets.

Compositing needs to know what is already on the target before it writes. Antialiased edges, translucent fills, blend modes and every other read-modify-write effect blend a foreground colour into a backdrop, and the backdrop is whatever the target currently holds. ReadbackTarget is the capability that says a target can answer that question, so rendering code can require it generically:

use embedded_graphics_core::{draw_target::DrawTarget, primitives::Rectangle};
use embedded_graphics_readback::ReadbackTarget;

/// Blend `fg` over one scanline run at the given per-pixel coverage.
fn composite_run<D: ReadbackTarget>(
    target: &mut D,
    run: &Rectangle,
    fg: D::Color,
    coverage: &[u8],
    scratch: &mut [D::Color],
) {
    target.read_area(run, scratch);
    for (px, &cov) in scratch.iter_mut().zip(coverage) {
        *px = blend_over(fg, *px, cov);
    }
    let _ = target.fill_contiguous(run, scratch.iter().copied());
}

ReadbackTarget: DrawTarget, so a single bound supplies both halves of that loop and a single Self::Color names the pixel type throughout. The immutable read finishes before the mutable write begins, so one &mut D carries the whole operation — no staging buffer for the shape's bounding box, just a scratch run.

embedded-graphics framebuffers

Framebuffer is supported out of the box under the framebuffer feature:

embedded-graphics-readback = { version = "0.1", features = ["framebuffer"] }
let mut fb = Framebuffer::<Rgb565, _, LittleEndian, 64, 64, {buffer_size::<Rgb565>(64, 64)}>::new();

fb.bounding_box()
    .into_styled(PrimitiveStyle::with_fill(Rgb565::RED))
    .draw(&mut fb)?;

assert_eq!(fb.read_pixel(Point::new(10, 10)), Some(Rgb565::RED));

The impl covers every colour type and data order embedded-graphics makes drawable, and overrides read_area to build the backing image once per region. Draw into a Framebuffer, hand it to any ReadbackTarget renderer, and flush it to the panel — which also makes it the shortest route to readback for a streaming driver.

Implementing it

For your own target, implement read_pixel and the rest follows:

impl ReadbackTarget for MyFramebuffer {
    fn read_pixel(&self, point: Point) -> Option<Self::Color> {
        self.index(point).map(|i| self.pixels[i])
    }
}

It shares its signature with GetPixel::pixel, so a target that already implements the standard trait delegates in one line:

fn read_pixel(&self, point: Point) -> Option<Self::Color> {
    GetPixel::pixel(self, point)
}

A reader that returns a bare colour needs a bounds guard, since read_pixel answers None outside the bounding box:

fn read_pixel(&self, p: Point) -> Option<Rgb888> {
    self.bounding_box().contains(p).then(|| self.0.get_pixel(p))
}

Bulk reads

read_area copies a region out row-major in one call. The default loops read_pixel; override it whenever the target can hand over a slice, which is the case for most framebuffers:

fn read_area(&self, area: &Rectangle, out: &mut [Self::Color]) -> usize {
    // one memcpy per row instead of one call per pixel
}

Layers

Because the capability belongs to the target, a wrapper carries it forward by delegating both methods. The adapters module ships the three that matter, so a pipeline keeps readback end to end:

use embedded_graphics_readback::ReadbackTargetExt;

let mut layer = fb.shifted(Point::new(2, 2));
let mut view = layer.masked(&Rectangle::new(Point::zero(), Size::new(4, 4)));

composite_run(&mut view, /* ... */);

Shifted, Windowed and Masked each implement DrawTarget with the same write semantics as their embedded-graphics counterparts — Translated, Cropped and Clipped — plus ReadbackTarget. They exist because embedded-graphics' own DrawTargetExt adapters hold their parent in a private field with no accessor, so readback cannot be delegated through those. The names differ deliberately: DrawTargetExt is blanket-implemented for every DrawTarget and sits in the embedded-graphics prelude, so a shared name would leave both candidates applicable at every call site that glob-imports it. Each method is shorthand for a constructor — Shifted::new(&mut fb, offset) — for code that would rather not import the trait.

read_area hands a whole region to the parent when it falls inside the layer, so a parent with a block copy keeps it, and falls back to a per-pixel walk only where the region straddles an edge. Unlike writes, reads honour the layer's bounding box: a point outside it is None even where the parent still holds a pixel.

Who implements it

  • Framebuffers and canvases — anything holding pixels in RAM, where a read is a slice index. The natural implementors.
  • Buffered display drivers that expose their buffer.
  • Simulators and test harnesses, via a newtype.

Streaming drivers hold no pixels — they forward straight to the bus — so they leave the trait unimplemented and callers keep the write-only path.

Cost contract

Renderers call read_area once per run on the hot path and assume a read costs about what a write costs. That holds for RAM-backed framebuffers, where a read is slice arithmetic. Implement this trait where reads are cheap, and override read_area with a block copy whenever the target allows it.

no_std

#![no_std], with embedded-graphics-core as its only required dependency. The framebuffer feature adds embedded-graphics itself.

License

Licensed under either of MIT or Apache-2.0 at your option.