Struct Frame2d 

pub struct Frame2d<const W: usize, const H: usize>(pub [[RGB8; W]; H]);

2D pixel array used for general graphics on LED panels (includes examples).

This page provides the primary documentation for drawing onto LED panels.

Read the examples below first. After that, keep these details in mind:

• Use a frame to prepare an image before sending it to the panel.
• Coordinates are (x, y) with (0, 0) at the top-left. The x-axis increases to the right, and the y-axis increases downward.
• Set pixels using tuple indexing: frame[(x, y)] = colors::RED;.
• For shapes, lines, and text rendering, use the embedded-graphics crate.
• Frames are rendered by a panel type generated with led2d!. See Led2dGenerated for the full API of the generated panel type.
• For animation, call animate with a sequence of (Frame2d, Duration) pairs. See the led2d module for an example.

Indexing and storage

Frame2d supports both:

• (x, y) tuple indexing: frame[(x, y)]
• Row-major array indexing: frame[y][x]

Tuple indexing matches display coordinates. Array indexing matches the underlying storage.

Rendering pipeline (what happens when you display a frame)

Frame2d is only pixel storage. When you render a frame through a generated panel type, the device abstraction:

• Maps (x, y) pixels to the physical LED wiring order
• Applies gamma correction
• Scales brightness to respect the configured electrical current budget

These steps are implemented using two compile-time–generated lookup tables. Writing a frame performs only indexed memory reads and writes.

Example: Draw pixels both directly and with embedded-graphics:

use device_envoy::{led2d::Frame2d, led_strip::ToRgb888};
use embedded_graphics::{
    prelude::*,
    primitives::{Circle, PrimitiveStyle, Rectangle},
};
use smart_leds::colors;

type Frame = Frame2d<12, 8>;

/// Calculate the top-left corner position to center a shape within a bounding box.
const fn centered_top_left(width: usize, height: usize, size: usize) -> Point {
    assert!(size <= width);
    assert!(size <= height);
    Point::new(((width - size) / 2) as i32, ((height - size) / 2) as i32)
}

// Create a frame to draw on. This is just an in-memory 2D pixel buffer.
let mut frame = Frame::new();

// Use the embedded-graphics crate to draw a red rectangle border around the edge of the frame.
// We use `to_rgb888()` to convert from smart-leds RGB8 to embedded-graphics Rgb888.
Rectangle::new(Frame::TOP_LEFT, Frame::SIZE)
    .into_styled(PrimitiveStyle::with_stroke(colors::RED.to_rgb888(), 1))
    .draw(&mut frame)
    .expect("rectangle draw must succeed");

// Direct pixel access: set the upper-left LED pixel (x = 0, y = 0).
// Frame2d stores LED colors directly, so we write an LED color here.
frame[(0, 0)] = colors::CYAN;

// Use the embedded-graphics crate to draw a green circle centered in the frame.
const DIAMETER: u32 = 6;
const CIRCLE_TOP_LEFT: Point = centered_top_left(Frame::WIDTH, Frame::HEIGHT, DIAMETER as usize);
Circle::new(CIRCLE_TOP_LEFT, DIAMETER)
    .into_styled(PrimitiveStyle::with_stroke(colors::LIME.to_rgb888(), 1))
    .draw(&mut frame)
    .expect("circle draw must succeed");

Tuple Fields

0: [[RGB8; W]; H]

Implementations

impl<const W: usize, const H: usize> Frame2d<W, H>

pub const WIDTH: usize = W

The width of the frame.

pub const HEIGHT: usize = H

The height of the frame.

pub const LEN: usize

Total pixels in this frame (width × height).

pub const SIZE: Size

Frame dimensions as a Size.

For embedded-graphics drawing operation.

pub const TOP_LEFT: Point

Top-left corner coordinate as a Point.

For embedded-graphics drawing operation.

pub const TOP_RIGHT: Point

Top-right corner coordinate as a Point.

For embedded-graphics drawing operation.

pub const BOTTOM_LEFT: Point

Bottom-left corner coordinate as a Point.

For embedded-graphics drawing operation.

pub const BOTTOM_RIGHT: Point

Bottom-right corner coordinate as a Point.

For embedded-graphics drawing operation.

pub const fn new() -> Self

Create a new blank (all black) frame.

pub const fn filled(color: RGB8) -> Self

Create a frame filled with a single color.

Trait Implementations

impl<const W: usize, const H: usize> Clone for Frame2d<W, H>

fn clone(&self) -> Frame2d<W, H>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<const W: usize, const H: usize> Debug for Frame2d<W, H>

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

Formats the value using the given formatter.

impl<const W: usize, const H: usize> Default for Frame2d<W, H>

fn default() -> Self

Returns the “default value” for a type.

impl<const W: usize, const H: usize> Deref for Frame2d<W, H>

type Target = [[Rgb<u8>; W]; H]

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<const W: usize, const H: usize> DerefMut for Frame2d<W, H>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<const W: usize, const H: usize> DrawTarget for Frame2d<W, H>

type Color = Rgb888

The pixel color type the targetted display supports.

type Error = Infallible

Error type to return when a drawing operation fails.

fn draw_iter<I>(&mut self, pixels: I) -> Result<(), Self::Error>

where I: IntoIterator<Item = Pixel<Self::Color>>,

Draw individual pixels to the display without a defined order.

fn fill_contiguous<I>( &mut self, area: &Rectangle, colors: I, ) -> Result<(), Self::Error>

where I: IntoIterator<Item = Self::Color>,

Fill a given area with an iterator providing a contiguous stream of pixel colors.

fn fill_solid( &mut self, area: &Rectangle, color: Self::Color, ) -> Result<(), Self::Error>

Fill a given area with a solid color.

fn clear(&mut self, color: Self::Color) -> Result<(), Self::Error>

Fill the entire display with a solid color.

impl<const W: usize, const H: usize> From<[[Rgb<u8>; W]; H]> for Frame2d<W, H>

fn from(array: [[RGB8; W]; H]) -> Self

Converts to this type from the input type.

impl<const W: usize, const H: usize> From<Frame2d<W, H>> for [[RGB8; W]; H]

fn from(frame: Frame2d<W, H>) -> Self

Converts to this type from the input type.

impl<const W: usize, const H: usize> Index<(usize, usize)> for Frame2d<W, H>

type Output = Rgb<u8>

The returned type after indexing.

fn index(&self, (x_index, y_index): (usize, usize)) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<const W: usize, const H: usize> IndexMut<(usize, usize)> for Frame2d<W, H>

fn index_mut(&mut self, (x_index, y_index): (usize, usize)) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<const W: usize, const H: usize> OriginDimensions for Frame2d<W, H>

fn size(&self) -> Size

Returns the size of the bounding box.

impl<const W: usize, const H: usize> Copy for Frame2d<W, H>