Skip to main content

embedded_graphics_readback/
framebuffer.rs

1//! [`ReadbackTarget`] for [`embedded_graphics::framebuffer::Framebuffer`].
2//!
3//! Enabled by the `framebuffer` feature. `Framebuffer` keeps its pixels in a
4//! `[u8; N]` and already implements [`GetPixel`], so it satisfies the whole
5//! contract: reads are slice arithmetic, and
6//! [`read_area`](ReadbackTarget::read_area) builds the backing image once per
7//! region rather than once per pixel.
8//!
9//! The impl covers every `Framebuffer` that is both drawable and readable —
10//! every colour type and data order for which `embedded-graphics` provides
11//! those impls — so enabling the feature is all that is required:
12//!
13//! ```
14//! use embedded_graphics::{
15//!     framebuffer::{buffer_size, Framebuffer},
16//!     pixelcolor::{raw::LittleEndian, Rgb565},
17//!     prelude::*,
18//!     primitives::PrimitiveStyle,
19//! };
20//! use embedded_graphics_readback::ReadbackTarget;
21//!
22//! let mut fb =
23//!     Framebuffer::<Rgb565, _, LittleEndian, 64, 64, { buffer_size::<Rgb565>(64, 64) }>::new();
24//!
25//! fb.bounding_box()
26//!     .into_styled(PrimitiveStyle::with_fill(Rgb565::RED))
27//!     .draw(&mut fb)?;
28//!
29//! assert_eq!(fb.read_pixel(Point::new(10, 10)), Some(Rgb565::RED));
30//! # Ok::<(), core::convert::Infallible>(())
31//! ```
32
33use embedded_graphics::{
34    draw_target::DrawTarget,
35    framebuffer::Framebuffer,
36    geometry::Point,
37    image::GetPixel,
38    iterator::raw::RawDataSlice,
39    pixelcolor::{PixelColor, raw::ByteOrder},
40    primitives::{PointsIter, Rectangle},
41};
42
43use crate::ReadbackTarget;
44
45impl<C, BO, const WIDTH: usize, const HEIGHT: usize, const N: usize> ReadbackTarget
46    for Framebuffer<C, C::Raw, BO, WIDTH, HEIGHT, N>
47where
48    Self: DrawTarget<Color = C>,
49    C: PixelColor + From<C::Raw>,
50    BO: ByteOrder,
51    for<'a> RawDataSlice<'a, C::Raw, BO>: IntoIterator<Item = C::Raw>,
52{
53    fn read_pixel(&self, point: Point) -> Option<C> {
54        GetPixel::pixel(self, point)
55    }
56
57    fn read_area(&self, area: &Rectangle, out: &mut [C]) -> usize {
58        // Hoist the backing image out of the loop: one construction per region
59        // instead of one per pixel.
60        let image = self.as_image();
61        let mut written = 0;
62        for (slot, point) in out.iter_mut().zip(area.points()) {
63            if let Some(color) = image.pixel(point) {
64                *slot = color;
65                written += 1;
66            }
67        }
68        written
69    }
70}
71
72#[cfg(test)]
73mod tests {
74    use super::*;
75    use embedded_graphics::{
76        Pixel,
77        framebuffer::buffer_size,
78        geometry::Size,
79        pixelcolor::{
80            Rgb565,
81            raw::{LittleEndian, RawU16},
82        },
83        prelude::*,
84    };
85
86    type Fb = Framebuffer<Rgb565, RawU16, LittleEndian, 4, 4, { buffer_size::<Rgb565>(4, 4) }>;
87
88    #[test]
89    fn read_pixel_round_trips_a_write() {
90        let mut fb = Fb::new();
91        Pixel(Point::new(1, 2), Rgb565::RED).draw(&mut fb).unwrap();
92
93        assert_eq!(fb.read_pixel(Point::new(1, 2)), Some(Rgb565::RED));
94        assert_eq!(fb.read_pixel(Point::new(0, 0)), Some(Rgb565::BLACK));
95    }
96
97    #[test]
98    fn read_pixel_out_of_bounds_is_none() {
99        let fb = Fb::new();
100
101        assert_eq!(fb.read_pixel(Point::new(-1, 0)), None);
102        assert_eq!(fb.read_pixel(Point::new(4, 0)), None);
103        assert_eq!(fb.read_pixel(Point::new(0, 4)), None);
104    }
105
106    #[test]
107    fn read_area_override_matches_read_pixel() {
108        let mut fb = Fb::new();
109        Pixel(Point::new(0, 0), Rgb565::RED).draw(&mut fb).unwrap();
110        Pixel(Point::new(1, 0), Rgb565::GREEN)
111            .draw(&mut fb)
112            .unwrap();
113        Pixel(Point::new(0, 1), Rgb565::BLUE).draw(&mut fb).unwrap();
114
115        let area = Rectangle::new(Point::zero(), Size::new(2, 2));
116        let mut out = [Rgb565::WHITE; 4];
117        let n = fb.read_area(&area, &mut out);
118
119        assert_eq!(n, 4);
120        assert_eq!(
121            out,
122            [Rgb565::RED, Rgb565::GREEN, Rgb565::BLUE, Rgb565::BLACK]
123        );
124
125        // The override must agree with the trait's per-pixel default.
126        let by_pixel: [Rgb565; 4] = core::array::from_fn(|i| {
127            fb.read_pixel(Point::new(i as i32 % 2, i as i32 / 2))
128                .unwrap()
129        });
130        assert_eq!(out, by_pixel);
131    }
132
133    #[test]
134    fn read_area_counts_only_in_bounds() {
135        let fb = Fb::new();
136        // Straddling the right edge: only the in-bounds column counts.
137        let area = Rectangle::new(Point::new(3, 0), Size::new(2, 2));
138        let mut out = [Rgb565::WHITE; 4];
139
140        assert_eq!(fb.read_area(&area, &mut out), 2);
141    }
142}