Module embedded_graphics::mock_display
source · [−]Expand description
Mock display for use in tests.
MockDisplay
can be used to replace a real display in tests. The internal
framebuffer wraps the color values in Option
to be able to test which
pixels were modified by drawing operations.
The from_pattern
method provides a convenient way of creating expected
test results. The same patterns are used by the implementation of Debug
and will be shown in failing tests.
The display is internally capped at 64x64px.
Assertions
MockDisplay
provides the assert_eq
and assert_pattern
methods to check if the
display is in the correct state after some drawing operations were executed. It’s recommended
to use these methods instead of the standard assert_eq!
macro, because they provide an
optional improved debug output for failing tests. If the EG_FANCY_PANIC
environment variable
is set to 1
at compile time a graphic representation of the display content and a diff of the
display and the expected output will be shown:
EG_FANCY_PANIC=1 cargo test
Enabling the advanced test output requires a terminal that supports 24 BPP colors and a font
that includes the upper half block character '\u{2580}'
.
The color code used to show the difference between the display and the expected output is shown
in the documentation of the diff
method.
Additional out of bounds and overdraw checks
MockDisplay
implements additional checks during drawing operations that will cause a panic if
any pixel is drawn outside the framebuffer or if a pixel is drawn more than once. These
stricter checks were added to help with testing and shouldn’t be implemented by normal
DrawTarget
s.
If a test relies on out of bounds drawing or overdrawing the additional checks can explicitly
be disabled by using set_allow_out_of_bounds_drawing
and set_allow_overdraw
.
Characters used in BinaryColor
patterns
The following mappings are available for BinaryColor
:
Character | Color | Description |
---|---|---|
' ' | None | No drawing operation changed the pixel |
'.' | Some(BinaryColor::Off) | Pixel was changed to BinaryColor::Off |
'#' | Some(BinaryColor::On) | Pixel was changed to BinaryColor::On |
Characters used in Gray2
patterns
The following mappings are available for Gray2
:
Character | Color | Description |
---|---|---|
' ' | None | No drawing operation changed the pixel |
'0' | Some(Gray2::new(0x0)) | Pixel was changed to Gray2::new(0x0) |
'1' | Some(Gray2::new(0x1)) | Pixel was changed to Gray2::new(0x1) |
'2' | Some(Gray2::new(0x2)) | Pixel was changed to Gray2::new(0x2) |
'3' | Some(Gray2::new(0x3)) | Pixel was changed to Gray2::new(0x3) |
Characters used in Gray4
patterns
The following mappings are available for Gray4
:
Character | Color | Description |
---|---|---|
' ' | None | No drawing operation changed the pixel |
'0' | Some(Gray4::new(0x0)) | Pixel was changed to Gray4::new(0x0) |
'1' | Some(Gray4::new(0x1)) | Pixel was changed to Gray4::new(0x1) |
⋮ | ⋮ | ⋮ |
'E' | Some(Gray4::new(0xE)) | Pixel was changed to Gray4::new(0xE) |
'F' | Some(Gray4::new(0xF)) | Pixel was changed to Gray4::new(0xF) |
Characters used in Gray8
patterns
The following mappings are available for Gray8
:
Character | Color | Description |
---|---|---|
' ' | None | No drawing operation changed the pixel |
'0' | Some(Gray8::new(0x00)) | Pixel was changed to Gray8::new(0x00) |
'1' | Some(Gray8::new(0x11)) | Pixel was changed to Gray8::new(0x11) |
⋮ | ⋮ | ⋮ |
'E' | Some(Gray8::new(0xEE)) | Pixel was changed to Gray8::new(0xEE) |
'F' | Some(Gray8::new(0xFF)) | Pixel was changed to Gray8::new(0xFF) |
Note: Gray8
uses a different mapping than Gray2
and Gray4
, by duplicating the pattern
value into the high and low nibble. This allows using a single digit to test luma values ranging
from 0 to 255.
Characters used in RGB color patterns
The following mappings are available for all RGB color types in the pixelcolor
module,
like Rgb565
or Rgb888
:
Character | Color | Description |
---|---|---|
' ' | None | No drawing operation changed the pixel |
'K' | Some(C::BLACK) | Pixel was changed to C::BLACK |
'R' | Some(C::RED) | Pixel was changed to C::RED |
'G' | Some(C::GREEN) | Pixel was changed to C::GREEN |
'B' | Some(C::BLUE) | Pixel was changed to C::BLUE |
'Y' | Some(C::YELLOW) | Pixel was changed to C::YELLOW |
'M' | Some(C::MAGENTA) | Pixel was changed to C::MAGENTA |
'C' | Some(C::CYAN) | Pixel was changed to C::CYAN |
'W' | Some(C::WHITE) | Pixel was changed to C::WHITE |
Note: The table used C
as a placeholder for the actual color type, like Rgb565::BLACK
.
Examples
Assert that a modified display matches the expected value
This example sets three pixels on the display and checks that they’re turned on.
use embedded_graphics::{mock_display::MockDisplay, pixelcolor::BinaryColor, prelude::*};
let mut display = MockDisplay::new();
Pixel(Point::new(0, 0), BinaryColor::On).draw(&mut display);
Pixel(Point::new(2, 1), BinaryColor::On).draw(&mut display);
Pixel(Point::new(1, 2), BinaryColor::On).draw(&mut display);
display.assert_pattern(&[
"# ", //
" #", //
" # ", //
]);
Load and validate a 16BPP image
This example loads the following test image (scaled 10x to make it visible) and tests the returned pixels against an expected pattern.
use embedded_graphics::{
image::{Image, ImageRaw, ImageRawBE},
mock_display::MockDisplay,
pixelcolor::{Rgb565, RgbColor},
prelude::*,
};
let data = [
0x00, 0x00, 0xF8, 0x00, 0x07, 0xE0, 0xFF, 0xE0, //
0x00, 0x1F, 0x07, 0xFF, 0xF8, 0x1F, 0xFF, 0xFF, //
];
let raw: ImageRawBE<Rgb565> = ImageRaw::new(&data, 4);
let image = Image::new(&raw, Point::zero());
let mut display: MockDisplay<Rgb565> = MockDisplay::new();
image.draw(&mut display);
display.assert_pattern(&[
"KRGY", //
"BCMW", //
]);
Structs
Mock display struct
Traits
Mapping between char
s and colors.