Mousefood - embedded-graphics backend for Ratatui!

Important

Currently works only with std-enabled targets, such as Espressif's ESP32 MCU series. Support for "bare-metal" (no_std) targets is planned, but this would require upstream changes - discussed here.

Quickstart

Add mousefood as a dependency:

cargo add mousefood

Exemplary setup:

use mousefood::prelude::*;

fn main() -> Result<(), std::io::Error> {
    // Any embedded_graphics DrawTarget
    let mut display = MyDrawTarget::new();
    
    let backend = EmbeddedBackend::new(&mut display);
    let mut terminal = Terminal::new(backend)?;

    loop {
        terminal.draw(...)?;
    }
}

Special characters

Embedded-graphics includes bitmap fonts that have a very limited set of characters to save space (ASCII, ISO 8859 or JIS X0201). This makes it impossible to draw most of Ratatui's widgets, which heavily use box-drawing glyphs, Braille, and other special characters.

Mousefood by default uses embedded-graphics-unicodefonts, which provides embedded-graphics fonts with a much larger set of characters.

Alternatives

In order to save space and speed up rendering, the fonts feature can be disabled by turning off the default crate features. ibm437 is a good alternative that includes some drawing characters, but is not as large as embedded-graphics-unicodefonts.

Simulator

Mousefood can be run in a simulator (requires SDL2 to be installed). The simulator mode can be enabled using the simulator feature and utilizes the embedded-graphics-simulator crate.

Run simulator example:

git clone https://github.com/j-g00da/mousefood.git
cd mousefood
cargo run --example=simulator --features=simulator

Exemplary setup using simulator:

use mousefood::prelude::*;
use mousefood::embedded_graphics::geometry;
use mousefood::simulator::SimulatorDisplay;

fn main() -> Result<(), std::io::Error> {
    let mut display = SimulatorDisplay::<Bgr565>::new(geometry::Size::new(128, 64));
    let backend: EmbeddedBackend<SimulatorDisplay<_>, _>
        = EmbeddedBackend::new(&mut display);
    let mut terminal = Terminal::new(backend)?;

    loop {
        terminal.draw(...)?;
    }
}

Performance and hardware support

Flash memory on most embedded devices is very limited. Additionally, to achieve high frame rate when using the fonts feature, it is recommended to use opt-level = 3, which can make the resulting binary even larger.

Mousefood is hardware-agnostic, but requires a std-enabled target. Successfully tested on:

• esp32 (base model, 4MB flash)
• esp32c6 (16MB flash)

Docs

Full API docs are available on docs.rs.

License

Mousefood is dual-licensed under Apache 2.0 and MIT terms.