font_model/lib.rs
1//! Typed, owned, editable font model — outlines, character maps, metrics,
2//! validation, and subsetting.
3//!
4//! `font-model` is the estate's **L1 font substrate**: the resolved, owned,
5//! mutable form of a typeface that sits directly on [`font-parse`]'s L0
6//! byte-level views. A parser gives you borrowed table views over `&[u8]`; an
7//! editor needs owned glyphs it can reshape, a writer needs metrics it can
8//! serialise, and a subsetter needs a codepoint set it can intersect against.
9//! That is what this crate is.
10//!
11//! ```
12//! use font_model::{Font, Glyph, GlyphId, Outline, Path};
13//!
14//! // Build a font from parts.
15//! let mut outline = Outline::new();
16//! let mut p = Path::starting_at(80.0, 0.0);
17//! p.line_to(520.0, 0.0);
18//! p.line_to(520.0, 700.0);
19//! p.line_to(80.0, 700.0);
20//! p.close();
21//! outline.push_contour(p);
22//!
23//! let mut cmap = font_model::Cmap::format4();
24//! cmap.subtables_mut()[0] =
25//! font_model::cmap::insert_entry(&cmap.subtables()[0], 'A' as u32, GlyphId::new(1));
26//!
27//! let font = Font::builder()
28//! .units_per_em(1000)
29//! .glyph(Glyph::new(GlyphId::NOTDEF, 600, 80, outline.clone()))
30//! .glyph(Glyph::new(GlyphId::new(1), 600, 80, outline))
31//! .cmap(cmap)
32//! .build()?;
33//!
34//! assert_eq!(font.glyph_for('A' as u32), Some(GlyphId::new(1)));
35//!
36//! // Subset to 'A' plus .notdef.
37//! let mut keep = font_model::CodePointSet::new();
38//! keep.insert('A' as u32);
39//! let sub = font.subset(&keep)?;
40//! assert_eq!(sub.glyph_count(), 2);
41//! assert!(sub.validate().is_ok());
42//! # Ok::<(), font_model::ModelError>(())
43//! ```
44//!
45//! # Model, not parser
46//!
47//! [`font-parse`] reads bytes in place: zero-copy, allocation-free, total.
48//! This crate owns its data. [`Font::from_sfnt`] is the bridge — it runs the
49//! L0 parser and resolves its borrowed views into this model — and it is the
50//! only function here that takes foreign bytes.
51//!
52//! # Invariants
53//!
54//! [`Font::validate`] is the single gate, and every error variant names the
55//! offending glyph and field:
56//!
57//! | Invariant | Error |
58//! |---|---|
59//! | `units_per_em` in `16..=16384` | [`ModelError::InvalidUnitsPerEm`] |
60//! | ink implies non-zero advance | [`ModelError::ZeroAdvance`] |
61//! | contours closed | [`ModelError::UnclosedContour`] |
62//! | coordinates finite | [`ModelError::NonFiniteCoordinate`] |
63//! | `cmap` strictly increasing | [`ModelError::NonMonotonicCmap`] |
64//! | every glyph reference resolves | [`ModelError::UnknownGlyph`] |
65//!
66//! # Layer
67//!
68//! L1 — substrate. Its only estate-internal dependency is `font-parse` (L0);
69//! `thiserror` carries the error taxonomy, `serde` is optional and off by
70//! default so a model can round-trip through a config format without forcing
71//! the dependency on everyone.
72//!
73//! [`font-parse`]: https://docs.rs/font-parse
74
75#![cfg_attr(not(feature = "std"), no_std)]
76#![deny(missing_docs)]
77#![forbid(unsafe_code)]
78
79extern crate alloc;
80
81pub mod cmap;
82mod error;
83pub mod font;
84pub mod glyph;
85pub mod metrics;
86pub mod name;
87mod num;
88pub mod os2;
89pub mod outline;
90pub mod parse;
91
92#[cfg(feature = "serde")]
93mod serde_impls;
94
95pub use cmap::{from_entries, insert_entry, Cmap, CmapSubtable, CodePointSet, Segment};
96pub use error::ModelError;
97pub use font::{
98 build_stub_font, name_value, Font, FontBuilder, KernPair, Kerning, TableTag, MAX_UNITS_PER_EM,
99 MIN_UNITS_PER_EM, TAG_CMAP, TAG_GPOS, TAG_GSUB, TAG_KERN,
100};
101pub use glyph::{Glyph, GlyphId};
102pub use metrics::{FontMetrics, Metrics, MetricsBuilder, VerticalMetrics};
103pub use name::{name_id, platform, preferred_record, NameRecord};
104pub use os2::{fs_type, weight_class, width_class, Os2Metrics};
105pub use outline::{Bbox, Command, FlatSegment, Outline, Path, Subpath, Winding};
106pub use parse::{from_font_ref, from_sfnt, hmtx_rows, to_outline};