Mousefood - a no-std embedded-graphics backend for Ratatui!

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, EmbeddedBackendConfig::default());
    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.

Bold and italic fonts

Bold and italic modifiers are supported, but this requires providing fonts through EmbeddedBackendConfig. If only regular font is provided, it serves as a fallback. All fonts must be of the same size.

use mousefood::{EmbeddedBackend, EmbeddedBackendConfig, fonts};

let config = EmbeddedBackendConfig {
    font_regular: fonts::MONO_6X13,
    font_bold: Some(fonts::MONO_6X13_BOLD),
    font_italic: Some(fonts::MONO_6X13_ITALIC),
    ..Default::default()
};
let backend = EmbeddedBackend::new(&mut display, config);

Simulator

Mousefood can be run in a simulator using embedded-graphics-simulator crate.

Run simulator example:

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

For more details, view the simulator example.

EPD support

Support for EPD (e-ink displays) produced by WeAct Studio (weact-studio-epd driver) can be enabled using epd-weact feature. This driver requires some additional configuration:

use mousefood::prelude::*;
use weact_studio_epd::graphics::Display290BlackWhite;
use weact_studio_epd::WeActStudio290BlackWhiteDriver;

// Configure SPI
// (...)

let mut driver = WeActStudio290BlackWhiteDriver::new(spi_interface, busy, rst, delay);
let mut display = Display290BlackWhite::new();

driver.init().unwrap();

let config = EmbeddedBackendConfig {
    flush_callback: Box::new(move |d| { driver.full_update(d).unwrap(); }),
    ..Default::default()
};
let backend = EmbeddedBackend::new(&mut display, config);

Support for epd_waveshare driver is planned in the future.

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