Expand description
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.
It is a thin, dependency-light contract over embedded-graphics-core:
read_pixel is the one required method, and
read_area copies a region out row-major in
one call — defaulting to a read_pixel loop, overridable with a block copy.
§Layers
Because the capability belongs to the target, a wrapper carries it forward
by delegating both methods. adapters ships the three that matter —
Shifted, Windowed and
Masked — 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, /* ... */);embedded-graphics’ own DrawTargetExt adapters hold their parent in a
private field with no accessor, so readback cannot be delegated through
them — these are read-capable equivalents with the same write semantics.
§Implementing it
read_pixel shares its signature with
GetPixel::pixel, so a
target that already implements that trait delegates in one line. A reader
that hands back a bare colour needs a bounds guard instead, since
read_pixel answers None outside the bounding box:
use embedded_graphics_core::{
draw_target::DrawTarget,
geometry::{Dimensions, Point},
image::GetPixel,
pixelcolor::Rgb565,
};
use embedded_graphics_readback::ReadbackTarget;
// Already a `GetPixel`: delegate.
impl ReadbackTarget for Fb {
fn read_pixel(&self, point: Point) -> Option<Self::Color> {
GetPixel::pixel(self, point)
}
}
// Hands back a bare colour: guard on the bounding box.
impl ReadbackTarget for Sim {
fn read_pixel(&self, point: Point) -> Option<Self::Color> {
self.bounding_box()
.contains(point)
.then(|| self.0.get_pixel(point))
}
}§embedded-graphics framebuffers
embedded_graphics::framebuffer::Framebuffer is supported out of the box
under the framebuffer feature:
embedded-graphics-readback = { version = "0.1", features = ["framebuffer"] }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.
§Who implements it
Framebuffers and canvases — anything holding pixels in RAM, where a read is a slice index — are the natural implementors, along with buffered display drivers that expose their buffer and simulators wrapped in a newtype. Streaming drivers hold no pixels, so they leave the trait unimplemented and callers keep the write-only path.
Re-exports§
pub use adapters::ReadbackTargetExt;
Modules§
- adapters
- Adapters that carry
ReadbackTargetdown a pipeline.
Traits§
- Readback
Target - A
DrawTargetthat can read back the pixels it has drawn.