Skip to main content

Crate embedded_graphics_readback

Crate embedded_graphics_readback 

Source
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 ReadbackTarget down a pipeline.

Traits§

ReadbackTarget
A DrawTarget that can read back the pixels it has drawn.