Struct embedded_graphics::image::Image

pub struct Image<'a, C, BO = BigEndian> where
    C: PixelColor + From<<C as PixelColor>::Raw>,
    BO: ByteOrder,  { /* fields omitted */ }

An image constructed from a slice.

The Image struct can be used to construct an image drawable from a slice of raw image data. The storage format is determined by the PixelColor type C and the ByteOrder BO. The byteorder doesn't need to be specified for colors which aren't stored in multiple bytes.

For color types with less than 8 bits per pixels the start of each row is aligned to the next whole byte.

Details about the conversion of raw data to color types are explained in the raw module documentation.

Examples

This example creates an image from 1 bit per pixel data:

use embedded_graphics::prelude::*;
use embedded_graphics::pixelcolor::BinaryColor;

/// Image data with 12 x 5 pixels.
/// The data for each row is 12 bits long and is padded with zeros on the
/// end because each row needs to contain a whole number of bytes.
const DATA: &[u8] = &[
    0b11101111, 0b0101_0000,
    0b10001000, 0b0101_0000,
    0b11101011, 0b0101_0000,
    0b10001001, 0b0101_0000,
    0b11101111, 0b0101_0000,
];

fn main() {
    // The type annotation `Image<BinaryColor>` is used to specify the format
    // of the stored raw data (`PixelColor::Raw`) and which color type the
    // raw data gets converted into.
    let image: Image<BinaryColor> = Image::new(DATA, 12, 5);

    let mut display = Display::default();
    display.draw(&image);
}

Colors with more than one byte per pixel need an additional type annotation for the byte order. The ImageBE and ImageLE type aliases can be used to abbreviate the type.

use embedded_graphics::prelude::*;
use embedded_graphics::image::{ImageLE, ImageBE};
use embedded_graphics::pixelcolor::{Rgb565, Rgb888};
use embedded_graphics::pixelcolor::raw::{BigEndian, LittleEndian};

// Rgb888 image with 24 bits per pixel and big endian byte order
let image1: ImageBE<Rgb888> = Image::new(DATA, 8, 8);
// or:
let image2: Image<Rgb888, BigEndian> = Image::new(DATA, 8, 8);

// Rgb565 image with 16 bits per pixel and little endian byte order
let image1: ImageLE<Rgb565> = Image::new(DATA, 16, 6);
// or:
let image2: Image<Rgb565, LittleEndian> = Image::new(DATA, 16, 6);

Methods

impl<'a, C, BO> Image<'a, C, BO> where
    C: PixelColor + From<<C as PixelColor>::Raw>,
    BO: ByteOrder, 

pub fn new(data: &'a [u8], width: u32, height: u32) -> Self

Creates a new image.

Panics

If data doesn't have the correct length.

pub fn offset(&self) -> Point

Returns the offset.

Trait Implementations

impl<'a, C, BO> Drawable for Image<'a, C, BO> where
    C: PixelColor + From<<C as PixelColor>::Raw>,
    BO: ByteOrder, 

impl<'a, C, BO> Dimensions for Image<'a, C, BO> where
    C: PixelColor + From<<C as PixelColor>::Raw>,
    BO: ByteOrder, 

fn top_left(&self) -> Point

Get the top left corner of the bounding box for an object

fn bottom_right(&self) -> Point

Get the bottom right corner of the bounding box for an object

fn size(&self) -> Size

Get the width and height for an object

impl<'a, C, BO> Transform for Image<'a, C, BO> where
    C: PixelColor + From<<C as PixelColor>::Raw>,
    BO: ByteOrder, 

fn translate(&self, by: Point) -> Self

Translate the image from its current position to a new position by (x, y) pixels, returning a new Image. For a mutating transform, see translate_mut.

// 8px x 1px test image
let image: Image<BinaryColor> = Image::new(&[ 0xff ], 8, 1);
let moved = image.translate(Point::new(25, 30));

assert_eq!(image.offset(), Point::new(0, 0));
assert_eq!(moved.offset(), Point::new(25, 30));

fn translate_mut(&mut self, by: Point) -> &mut Self

Translate the image from its current position to a new position by (x, y) pixels.

let mut image: Image<BinaryColor> = Image::new(&[ 0xff ], 8, 1);
image.translate_mut(Point::new(25, 30));

assert_eq!(image.offset(), Point::new(25, 30));

impl<'a, C: Debug, BO: Debug> Debug for Image<'a, C, BO> where
    C: PixelColor + From<<C as PixelColor>::Raw>,
    BO: ByteOrder, 

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<'a, C: PartialEq, BO: PartialEq> PartialEq<Image<'a, C, BO>> for Image<'a, C, BO> where
    C: PixelColor + From<<C as PixelColor>::Raw>,
    BO: ByteOrder, 

fn eq(&self, other: &Image<'a, C, BO>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Image<'a, C, BO>) -> bool

This method tests for !=.

impl<'a, C: Eq, BO: Eq> Eq for Image<'a, C, BO> where
    C: PixelColor + From<<C as PixelColor>::Raw>,
    BO: ByteOrder, 

impl<'a, C, BO> IntoIterator for &'a Image<'a, C, BO> where
    C: PixelColor + From<<C as PixelColor>::Raw>,
    BO: ByteOrder,
    RawDataIter<'a, C::Raw, BO>: Iterator<Item = C::Raw>, 

type Item = Pixel<C>

The type of the elements being iterated over.

type IntoIter = ImageIterator<'a, C, BO>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.