lovyangfx_fonts/lib.rs
1//! `no_std` runtime for the bitmap fonts that ship inside
2//! [LovyanGFX](https://github.com/lovyan03/LovyanGFX) (u8g2 wire format), plus a
3//! tool that extracts those glyph blobs out of LovyanGFX' C sources.
4//!
5//! Two halves:
6//!
7//! * [`Font`] — a zero-copy decoder over a `&'static [u8]` blob. No heap, no
8//! framebuffer, no `extern C`: hand it a glyph blob and a `plot(x, y)` closure
9//! and it rasterises text for you. Metrics are baseline-corrected, so mixed
10//! CJK / ASCII lines line up.
11//! * [`cstr`] + the `lgyf-gen` binary — LovyanGFX stores its fonts as
12//! `PROGMEM const uint8_t lgfx_efont_cn_14[262233] = "\0\376\6..." ;`, i.e. as
13//! *octal-escaped C string literals*. This crate decodes that into a raw
14//! `.bin` you can `include_bytes!`.
15//!
16//! * `fonts` module — zero-copy handles over the bundled eFont CN blobs
17//! (feature `efont-cn-*`). The data lives in the companion crate
18//! [`lovyangfx-fonts-efont-cn`](https://crates.io/crates/lovyangfx-fonts-efont-cn);
19//! default features carry no fonts, so decoder-only users download nothing
20//! extra.
21//!
22//! # Getting a blob
23//!
24//! Three routes, pick one:
25//!
26//! * **Bundled (0.2+)** — enable a font feature and call `fonts::efont_cn_14()`
27//! (see [`fonts`]). The blobs live in the companion data crate, byte-identical
28//! to the LovyanGFX arrays, with the upstream notices shipped alongside.
29//! * **Extract it yourself**:
30//!
31//! ```text
32//! cargo install --path . # or: cargo run --bin lgyf-gen -- ...
33//! lgyf-gen lgfx_efont_cn.c -o fonts --only lgfx_efont_cn_14 --report
34//! ```
35//!
36//! * **Your own u8g2 blob** from any source — `Font::new(your_blob)`.
37//!
38//! Blobs you extract from a LovyanGFX checkout (PlatformIO keeps one under
39//! `.pio/libdeps/<env>/LovyanGFX/`, Arduino under its `libraries` folder) carry
40//! the same upstream notices as the source. See `NOTICE` and `licenses/` in the
41//! repository.
42//!
43//! # Using it on a device
44//!
45//! ```no_run
46//! use lovyangfx_fonts::Font;
47//!
48//! // 嵌入式侧一般是 `static FONT: &[u8] = include_bytes!("fonts/efont_cn_14.bin");`
49//! // (blob 由 lgyf-gen 从你自己的 LovyanGFX 检出里生成,本 crate 不附带字库)
50//! let blob = std::fs::read("fonts/efont_cn_14.bin").unwrap();
51//! let font = Font::new(&blob).expect("blob too short to be a u8g2 font");
52//!
53//! let width = font.text_width("你好AI");
54//! font.for_each_pixel("你好AI", 232, |x, y| {
55//! /* draw_pixel(x, y); */
56//! });
57//! # let _ = width;
58//! ```
59//!
60//! # What this crate will not do
61//!
62//! It does not talk to a display, does not do font fallback across multiple
63//! blobs (loop over your own list and use [`Font::has_glyph`]), and does not
64//! handle anti-aliased or outline fonts — u8g2 blobs are 1-bit.
65#![no_std]
66#![forbid(unsafe_code)]
67#![warn(missing_docs)]
68
69#[cfg(feature = "gen")]
70extern crate alloc;
71
72mod font;
73
74pub use font::{Font, FontError, Glyph, Metric, BLOB_HEADER};
75
76#[cfg(feature = "gen")]
77pub mod cstr;
78
79pub mod fonts;