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 DrawTargets.

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:

CharacterColorDescription
' 'NoneNo 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:

CharacterColorDescription
' 'NoneNo 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:

CharacterColorDescription
' 'NoneNo 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:

CharacterColorDescription
' 'NoneNo 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:

CharacterColorDescription
' 'NoneNo 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.

Test image, scaled 1000%

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

Traits