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 ;
use ReadbackTarget;
/// Blend `fg` over one scanline run at the given per-pixel coverage.
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:
= { = "0.1", = ["framebuffer"] }
let mut fb = }>new;
fb.bounding_box
.into_styled
.draw?;
assert_eq!;
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:
It shares its signature with GetPixel::pixel, so a target that already
implements the standard trait delegates in one line:
A reader that returns a bare colour needs a bounds guard, since read_pixel
answers None outside the bounding box:
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:
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 ReadbackTargetExt;
let mut layer = fb.shifted;
let mut view = layer.masked;
composite_run;
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.