9 releases

0.3.0-beta.2 May 4, 2021
0.3.0-alpha.2 Feb 5, 2021
0.2.1 Jul 29, 2020
0.2.0 Mar 20, 2020
0.2.0-alpha.1 Jul 23, 2019

#120 in Embedded development

Download history 53/week @ 2021-01-21 58/week @ 2021-01-28 115/week @ 2021-02-04 209/week @ 2021-02-11 204/week @ 2021-02-18 327/week @ 2021-02-25 57/week @ 2021-03-04 107/week @ 2021-03-11 36/week @ 2021-03-18 70/week @ 2021-03-25 30/week @ 2021-04-01 50/week @ 2021-04-08 151/week @ 2021-04-15 177/week @ 2021-04-22 148/week @ 2021-04-29 33/week @ 2021-05-06

502 downloads per month
Used in 5 crates


564 lines

Embedded graphics simulator

Build Status Crates.io Docs.rs embedded-graphics on Matrix


It can display all sorts of embedded-graphics test code.

The simulator can be used to test and debug embedded-graphics code, or produce examples and interactive demos to show off embedded graphics features.


More simulator examples can be found in the examples repository.

Simulate a 128x64 SSD1306 OLED

use embedded_graphics::{
    primitives::{Circle, Line, Rectangle, PrimitiveStyle},
    mono_font::{ascii::FONT_6X9, MonoTextStyle},
use embedded_graphics_simulator::{BinaryColorTheme, SimulatorDisplay, Window, OutputSettingsBuilder};

fn main() -> Result<(), core::convert::Infallible> {
    let mut display = SimulatorDisplay::<BinaryColor>::new(Size::new(128, 64));

    let line_style = PrimitiveStyle::with_stroke(BinaryColor::On, 1);
    let text_style = MonoTextStyle::new(&FONT_6X9, BinaryColor::On);

    Circle::new(Point::new(72, 8), 48)
        .draw(&mut display)?;

    Line::new(Point::new(48, 16), Point::new(8, 16))
        .draw(&mut display)?;

    Line::new(Point::new(48, 16), Point::new(64, 32))
        .draw(&mut display)?;

    Rectangle::new(Point::new(79, 15), Size::new(34, 34))
        .draw(&mut display)?;

    Text::new("Hello World!", Point::new(5, 5), text_style).draw(&mut display)?;

    let output_settings = OutputSettingsBuilder::new()
    Window::new("Hello World", &output_settings).show_static(&display);



The simulator uses SDL2 and its development libraries which must be installed to build and run it.

Linux (apt)

sudo apt install libsdl2-dev

macOS (brew)

brew install sdl2


The Windows install process is a bit more involved, but it does work. See the Rust-SDL2 crate's README for instructions. There are multiple ways to get it working, but probably the simplest method is copying the binaries as shown here.

Creating screenshots

Screenshots of programs, that use Window to display a simulated display, can be created by setting the EG_SIMULATOR_DUMP environment variable:

EG_SIMULATOR_DUMP=screenshot.png cargo run

By setting the variable the display passed to the first Window::update call gets exported as a PNG file to the specified path. After the file is exported the process is terminated.

Exporting images

If a program doesn't require to display a window and only needs to export one or more images, a SimulatorDisplay can also be converted to an image crate ImageBuffer by using the to_image_buffer method. The resulting buffer can then be used to save the display content to any format supported by image.

Usage without SDL2

When the simulator is used in headless/CI environments that don't require showing a window, SDL2 support can be disabled. This removes the requirement of SDL2 being installed on the target machine, but still allows the simulator to be used to generate images.

The with-sdl feature is enabled by default and can be disabled by adding default-features = false to the dependency:

version = "0.2.0"
default-features = false

See the Choosing Features Cargo manifest documentation for more details.


Licensed under either of

at your option.


Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.


~94K SLoC