mplusfonts 0.1.4

Parametrized bitmap font family for embedded-graphics
Documentation

mplusfonts

Parametrized bitmap fonts for embedded-graphics, with font rasterization powered by swash.

Adds an optimal subset of M+ FONTS to your next embedded Rust project.[^1]

Screenshot with English and Japanese text

[^1]: Rust 2024 is required to build this crate

Features

  • A family of variable-width and monospaced fonts - mplusfonts allows you to choose between three typefaces, with font properties that you will want to specify. Using this crate, you can have font anti-aliasing and font-based kerning on embedded devices, in a no_std environment.
  • No font files needed in your project - The mplus! macro generates Rust code for your bitmap font. After expanding the macro and compiling your code, the TrueType fonts that come with this crate are no longer used.
  • Includes only the glyphs that you want - The strings attribute helps you find and add characters and character clusters to your bitmap font. You can also specify ranges of characters to include as parameters for the mplus! macro.
  • Japanese scripts - Designed by Coji Morishita and licensed under the SIL Open Fonts License (LICENSE), M+ FONTS has support for over 5 700 kanji glyphs.^2 Since this crate is based on M+ FONTS, you gain access to all of its features.

Usage

  1. Make sure you have added mplusfonts as a dependency.
  2. Enable static text rendering by applying an attribute to your function with string definitions.
  3. Create a bitmap font inside your function so that #[strings] can find its helper attributes.
  4. Apply #[strings::emit] to the bitmap font definition.
  5. Include any additional character ranges in the bitmap font that you need.
  6. Have a character style use the bitmap font.
  7. You can now start drawing text.
  8. Exclude any string literals in your function that are not drawn by using #[strings::skip].

Examples

[dependencies]
mplusfonts = "0.1"

#[mplusfonts::strings]
pub fn main() -> Result<(), Infallible> {
    const KB_OK: &str = "KB OK";

    let text = format!("{} {KB_OK}", 16 * 40);

    let mut display: SimulatorDisplay<Rgb565> = SimulatorDisplay::new(Size::new(320, 240));

    #[strings::emit]
    let bitmap_font = mplus!(code(115), BOLD, code_line_height(24), true, 1, 4, '0'..='9');

    let character_style = BitmapFontStyle::new(&bitmap_font, Rgb565::GREEN);

    Text::new(&text, Point::new(20, 20), character_style).draw(&mut display)?;

    let output_settings = OutputSettingsBuilder::new().scale(3).build();

    #[strings::skip]
    Window::new("Simulator", &output_settings).show_static(&display);

    Ok(())
}

For more examples, see the examples folder.

Limitations

  • The strings attribute ignores format!, concat!, or any other macro invocation as a source of string literals. Since this crate is intended for no_std use, this should be less of an issue, but it still requires a workaround for concat!.
  • BitmapFontStyle does not have underline and strikethrough settings; these are not supported.
  • Rendering combining characters with characters for which no single code point exists, is a hit-or-miss.
  • Transparent backgrounds are not supported. Alpha compositing is not available; this crate does not have an alloc feature.

Minimum supported Rust version

The minimum supported Rust version for mplusfonts is 1.85.

License

The source code of mplusfonts is dual-licensed under:

at your option.