Embedded graphics

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

Embedded Graphics Simulator example screenshots

Getting help/reporting an issue

If you think you've found a bug, or would like to suggest a new feature to add to embedded-graphics, please open an issue.

If you need more deeper/more personalised help, please check out the embedded-graphics Matrix channel.

Documentation

A small 2D graphics library to draw things on embedded graphical LCDs, like the SSD1306 OLED display.

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

More information and up to date docs can be found on docs.rs.

Example usage can be found in the simulator:

```rust use embeddedgraphics::fonts::{Font6x8, Text}; use embeddedgraphics::pixelcolor::Rgb565; use embeddedgraphics::prelude::*; use embeddedgraphics::primitives::{Circle, Line}; use embedded_graphics::style::{PrimitiveStyle, TextStyle};

// Only used for examples - this would be replaced by the driver for your chosen display use embeddedgraphics::mockdisplay::MockDisplay as Display;

fn main() { // Create a display object to draw into // This will be whichever display driver you decide to use, like the SSD1306, SSD1351, etc let mut display = Display::new();

// Draw a circle centered at (64, 64) with a radius of 64 and a white 1px stroke
Circle::new(Point::new(64, 64), 64)
    .into_styled(PrimitiveStyle::with_stroke(Rgb565::WHITE, 1))
    .draw(&mut display);

// Draw a white 1px thick line from (64, 64) to (0, 64)
Line::new(Point::new(64, 64), Point::new(0, 64))
    .into_styled(PrimitiveStyle::with_stroke(Rgb565::WHITE, 1))
    .draw(&mut display);

// Draw a red 1px line from (64, 64) to (80, 80)
Line::new(Point::new(64, 64), Point::new(80, 80))
    .into_styled(PrimitiveStyle::with_stroke(Rgb565::RED, 1))
    .draw(&mut display);

// Print "Hello world!" in a white 6x8 pixel font with the top left corner positioned at (5, 50)
Text::new("Hello World!", Point::new(5, 50))
    .into_styled(TextStyle::new(Font6x8, Rgb565::WHITE))
    .draw(&mut display);

} ```

Macros are also supported for text and primitives:

```rust use embeddedgraphics::fonts::Font6x8; use embeddedgraphics::pixelcolor::Rgb565; use embeddedgraphics::prelude::*; use embeddedgraphics::{ egcircle, egline, egrectangle, egtext, egtriangle, primitivestyle, textstyle, };

// Only used for examples - this would be replaced by the driver for your chosen display use embeddedgraphics::mockdisplay::MockDisplay as Display;

fn main() { // Create a display object to draw into // This will be whichever display driver you decide to use, like the SSD1306, SSD1351, etc let mut display = Display::new();

// Draw a circle centered at (64, 64) with a radius of 64 and a white 1px stroke
egcircle!(
    center = (64, 64),
    radius = 64,
    style = primitive_style!(stroke_color = Rgb565::WHITE)
)
.draw(&mut display);

// Draw a 1px thick white line from (64, 64) to (0, 64)
egline!(
    start = (64, 64),
    end = (0, 64),
    style = primitive_style!(stroke_color = Rgb565::WHITE)
)
.draw(&mut display);

// Draw a 1px red line from (64, 64) to (80, 80)
egline!(
    start = (64, 64),
    end = (80, 80),
    style = primitive_style!(stroke_color = Rgb565::RED)
)
.draw(&mut display);

// Draw a rectangle from (64, 64) to (80, 80) with a black fill
egrectangle!(
    top_left = (64, 64),
    bottom_right = (80, 80),
    style = primitive_style!(fill_color = Rgb565::BLACK)
)
.draw(&mut display);

// Print "Hello world!" in a white 6x8 pixel font with the top left corner positioned at (5, 50)
egtext!(
    text = "Hello world!",
    top_left = (5, 50),
    style = text_style!(font = Font6x8, text_color = Rgb565::WHITE)
)
.draw(&mut display);

} ```

Cargo Features

Display drivers with embedded-graphics support

Some drivers may not support the latest version of embedded-graphics.

There may be other drivers out there we don't know about yet. If you know of a driver to add to this list, please open an issue!

Development setup

Minimum supported Rust version

The minimum supported Rust version for embedded-graphics is 1.40.0 or greater. Ensure you have the latest stable version of Rust installed, preferably through https://rustup.rs.

Ubuntu/Linux Mint

```bash

Update to latest stable version of Rust

rustup update

Ensure rustfmt is installed

rustup component add rustfmt

Install SDL2 for simulator and PIP to install linkchecker

sudo apt install libsdl2-dev python-pip

Install linkchecker so doc links can be checked

sudo pip install linkchecker ```

Attribution

All source font PNGs are taken from the excellent Uzebox Wiki page.

License

Licensed under either of

at your option.

Contribution

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.