Trait PixelRead

Source

pub trait PixelRead: DrawTarget {
    // Required method
    fn get_pixel(&self, point: Point) -> Self::Color;
}

Expand description

Capability trait for draw targets that can read back a pixel they’ve already written. Optional: the default opacity/blend APIs on RenderCtx only require DrawTarget and approximate translucency with ordered dithering, so they keep working on write-only displays. Implementing PixelRead additionally unlocks the *_true_alpha methods, which composite against the destination’s actual current contents instead of dithering.

Re-exported from embedded_draw_target so that a buffer implementing it once is accepted by every crate in the ecosystem that needs readback, rather than by this one alone. Readback capability for a DrawTarget.

embedded-graphics-core models displays as write-only sinks, which is the right lowest common denominator for a bare SPI panel but rules out anything that has to look at what is already on screen: true alpha compositing, analytical anti-aliasing, screen transitions that cross-fade between two frames, and read-modify-write effects generally.

Any target that keeps its pixels in RAM — a framebuffer, a scanline cache, a simulator window — can implement this trait, and doing so makes it usable by every crate in the ecosystem that needs readback, with one trait identity instead of one per library.

§Out-of-bounds reads

get_pixel is infallible by design so it can sit in a rasterizer inner loop. Implementations must not panic on out-of-bounds coordinates; return a neutral value (typically Default::default(), i.e. black) instead. Callers that need to distinguish “black” from “outside” should clip against OriginDimensions first.