[][src]Crate embedded_graphics

This crate aims to make drawing 2D graphics primitives super easy. It currently supports the following built in items:

Additional functionality provided by external crates:

If you know of a crate that is not in this list, please open an issue.

Note that some of these crates may not support the latest version of embedded-graphics.

You can also add your own objects by implementing Drawable on them. Additionally, all iterators over pixels (Iterator<Item = Pixel<C>>) have a default Drawable implementation already created.

A core goal of embedded-graphics is to draw graphics without using any buffers; the crate is no_std compatible and works without a dynamic memory allocator, and without pre-allocating large chunks of memory. To achieve this, it takes an Iterator based approach, where pixel values and positions are calculated on the fly, with the minimum of saved state. This allows the consuming application to use far less RAM at little to no performance penalty.

Supported displays

These are just some of the displays the community has added embedded_graphics support to. This list is taken from the dependent crates list on crates.io so might be missing some unpublished entries. Please open an issue if there's a display driver that should be added to this list.

Note that some drivers may not support the latest version of embedded-graphics.

  • hub75: A rust driver for hub75 rgb matrix displays
  • ili9341: A platform agnostic driver to interface with the ILI9341 (and ILI9340C) TFT LCD display
  • ls010b7dh01: A platform agnostic driver for the LS010B7DH01 memory LCD display
  • sh1106: I2C driver for the SH1106 OLED display
  • ssd1306: I2C and SPI (4 wire) driver for the SSD1306 OLED display
  • ssd1322: Pure Rust driver for the SSD1322 OLED display chip
  • ssd1331: SPI (4 wire) driver for the SSD1331 OLED display
  • ssd1351: SSD1351 driver
  • ssd1675: Rust driver for the Solomon Systech SSD1675 e-Paper display (EPD) controller
  • st7735-lcd: Rust library for displays using the ST7735 driver
  • st7920: ST7920 LCD driver in Rust

Simulator

Embedded graphics comes with a simulator!

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

Take a look at the simulator examples to see what embedded_graphics can do, and how it might look on a display. You can run the examples like this:

git clone https://github.com/jamwaffles/embedded-graphics.git
cd embedded-graphics

cargo run -p embedded-graphics-simulator --example hello

Crate features

Add these to your Cargo.toml to turn on extra bits of functionality.

  • nalgebra_support - use the Nalgebra crate with no_std support to enable conversions from nalgebra::Vector2 to Point and Size.

Examples

Draw a circle and some text

This example uses the Circle primitive and the Font6x8 font to draw a filled circle and some text over it on the screen.

use embedded_graphics::{
    fonts::{Font6x8, Text},
    mock_display::MockDisplay,
    pixelcolor::Rgb565,
    prelude::*,
    primitives::Circle,
    style::{PrimitiveStyle, TextStyle},
};

// Create a draw target using the builtin MockDisplay. In real applications this would be
// replaced by a draw target that is provided by a display driver crate.
let mut display = MockDisplay::default();

let c = Circle::new(Point::new(20, 20), 8).into_styled(PrimitiveStyle::with_fill(Rgb565::RED));
let t = Text::new("Hello Rust!", Point::new(20, 16))
    .into_styled(TextStyle::new(Font6x8, Rgb565::GREEN));

c.draw(&mut display)?;
t.draw(&mut display)?;

Draw a circle and some text

To make life even easier, some handy macros are provided for drawing styled primitives and text. Converting the example above, we get this:

use embedded_graphics::{
    egcircle, egtext, fonts::Font6x8, mock_display::MockDisplay, pixelcolor::Rgb565,
    prelude::*, primitive_style, text_style,
};

// Create a draw target using the builtin MockDisplay. In real applications this would be
// replaced by a draw target that is provided by a display driver crate.
let mut display = MockDisplay::default();

let c = egcircle!(
    center = (20, 20),
    radius = 8,
    style = primitive_style!(fill_color = Rgb565::RED)
);
let t = egtext!(
    text = "Hello Rust!",
    top_left = (20, 16),
    style = text_style!(font = Font6x8, text_color = Rgb565::GREEN)
);

c.draw(&mut display)?;
t.draw(&mut display)?;

Chaining

Items can be chained to build more complex graphics objects.

use embedded_graphics::{
    egcircle, egrectangle, egtext, fonts::Font6x8, mock_display::MockDisplay,
    pixelcolor::Rgb565, prelude::*, primitive_style, text_style,
};

// Create a draw target using the builtin MockDisplay. In real applications this would be
// replaced by a draw target that is provided by a display driver crate.
let mut display: MockDisplay<Rgb565> = MockDisplay::default();

fn build_thing(text: &'static str) -> impl Iterator<Item = Pixel<Rgb565>> {
    egrectangle!(top_left = (0, 0), bottom_right = (40, 40))
        .into_iter()
        .chain(&egcircle!(
            center = (20, 20),
            radius = 8,
            style = primitive_style!(fill_color = Rgb565::RED)
        ))
        .chain(&egtext!(
            text = text,
            top_left = (20, 16),
            style = text_style!(font = Font6x8, text_color = Rgb565::GREEN)
        ))
}

build_thing("Hello Rust!").draw(&mut display)?;

Implementing embedded_graphics in a driver

To add support for embedded_graphics to a display driver, DrawTarget should be implemented. This allows all embedded_graphics objects to be rendered by the display. See the DrawTarget documentation for implementation details.

Modules

drawable

Drawable trait and helpers

fonts

Monospaced bitmap fonts.

geometry

Geometry module.

image

Image support for embedded-graphics

mock_display

Mock display for use in tests.

pixelcolor

Pixel color types.

prelude

Prelude

primitives

Graphics primitives

style

Styling struct to customize the look of objects.

transform

Transformations for graphics objects

Macros

egcircle

Create a Circle with optional styling using a convenient macro.

egline

Create a Line with optional styling using a convenient macro.

egrectangle

Create a Rectangle with optional styling using a convenient macro.

egtext

Creates a styled text.

egtriangle

Create a Triangle with optional styling using a convenient macro.

primitive_style

Create a PrimitiveStyle

text_style

Create a TextStyle

Traits

DrawTarget

Defines a display that can be used to render Drawable objects.