Module embedded_graphics::image

Image support for embedded-graphics

The two main types used to draw images are ImageDrawable and Image.

ImageDrawable is implemented to add support for different image formats. This crate includes an implementation for raw pixel data. Additional implementations for other image formats are provided by external crates like tinybmp and tinytga.

The Image object is used to specify the location at which an ImageDrawable is drawn. Images are drawn relative to their top-left corner.

Examples

Display an RGB565 raw data image

This example displays a small image created from a raw data array. The image is RGB565 encoded, so it uses the Rgb565 color type.

use embedded_graphics::{
    image::{Image, ImageRaw, ImageRawBE},
    pixelcolor::Rgb565,
    prelude::*,
};

let mut display: Display<Rgb565> = Display::default();

// Raw big endian image data for demonstration purposes. A real image would likely be much
// larger.
let data = [
    0x00, 0x00, 0xF8, 0x00, 0x07, 0xE0, 0xFF, 0xE0, //
    0x00, 0x1F, 0x07, 0xFF, 0xF8, 0x1F, 0xFF, 0xFF, //
];

// Create a raw image instance. Other image formats will require different code to load them.
// All code after loading is the same for any image format.
let raw: ImageRawBE<Rgb565> = ImageRaw::new(&data, 4);

// Create an `Image` object to position the image at `Point::zero()`.
let image = Image::new(&raw, Point::zero());

// Draw the image to the display.
image.draw(&mut display)?;

Sub images

SubImages are used to split a larger image drawables into multiple parts, e.g. to draw a single sprite from a sprite atlas as in this example. Use the sub_image method provided by ImageDrawableExt to get a sub image from an image drawable. ImageDrawableExt is included in the prelude, which this example takes advantage of.

use embedded_graphics::{
    image::{Image, ImageRaw, ImageRawBE},
    pixelcolor::Rgb565,
    prelude::*,
    primitives::Rectangle,
};

let mut display: Display<Rgb565> = Display::default();

let data = [ 0xF8, 0x00, 0x07, 0xE0, 0xFF, 0xE0, /* ... */ ];
// or: let data = include_bytes!("sprite_atlas.raw");

let sprite_atlas: ImageRawBE<Rgb565> = ImageRaw::new(&data, 32);

// Create individual sub images for each sprite in the sprite atlas.
// The position and size of the sub images is defined by a `Rectangle`.
let sprite_1 = sprite_atlas.sub_image(&Rectangle::new(Point::new(0, 0), Size::new(16, 16)));
let sprite_2 = sprite_atlas.sub_image(&Rectangle::new(Point::new(16, 0), Size::new(16, 16)));

// Create `Image` objects to draw the sprites at different positions on the display.
Image::new(&sprite_1, Point::new(10, 10)).draw(&mut display)?;
Image::new(&sprite_2, Point::new(40, 30)).draw(&mut display)?;

Implementing new image formats

To add embedded-graphics support for an new image format the ImageDrawable and OriginDimensions traits must be implemented. See the ImageDrawable documentation for more information.

Structs

Image

Image object.

ImageRaw

An image constructed from a slice of raw pixel data.

SubImage

Sub image.

Traits

ImageDrawable

Image drawable.

ImageDrawableExt

Extension trait for image drawables.

Type Definitions

ImageRawBE

Image with big endian data.

ImageRawLE

Image with little endian data.