font_shape/lib.rs
1//! Glyph rasterization and text measurement — scanline fill, stroke expansion,
2//! advance/kerning layout, and bidirectional reordering.
3//!
4//! `font-shape` is the estate's **L2 shaping layer**: the half of a font
5//! toolchain that turns a [`font_model::Font`] into pixels and into measured
6//! text. It sits on [`font-model`] (L1), which sits on [`font-parse`] (L0).
7//!
8//! ```
9//! use font_model::{Font, Glyph, GlyphId, Outline, Path};
10//! use font_shape::{rasterize_glyph, shape_line, Hinting};
11//!
12//! // A 1000-upem font with one square glyph, 500 units wide.
13//! let mut outline = Outline::new();
14//! let mut p = Path::starting_at(50.0, 0.0);
15//! p.line_to(450.0, 0.0);
16//! p.line_to(450.0, 700.0);
17//! p.line_to(50.0, 700.0);
18//! p.close();
19//! outline.push_contour(p);
20//!
21//! let font = Font::builder()
22//! .units_per_em(1000)
23//! .glyph(Glyph::empty(GlyphId::NOTDEF, 500))
24//! .glyph(Glyph::new(GlyphId::new(1), 500, 50, outline))
25//! .build()
26//! .expect("a one-glyph font is valid");
27//!
28//! // Rasterize at 20 px: an 8x14 block, 20 rows above the baseline.
29//! let bmp = rasterize_glyph(&font, GlyphId::new(1), 20.0, Hinting::None)?;
30//! assert_eq!((bmp.width(), bmp.height()), (8, 14));
31//! assert_eq!(bmp.top(), 14);
32//! assert!(bmp.ink() > 100.0);
33//!
34//! // Measure the run: one glyph, 500 units at 20 px = 10 px.
35//! let line = shape_line(&font, "A", 20.0)?;
36//! assert_eq!(line.len(), 1);
37//! assert!((line.advance_px() - 10.0).abs() < 1e-4);
38//! # Ok::<(), font_shape::ShapeError>(())
39//! ```
40//!
41//! # What is in here
42//!
43//! | Area | Entry points |
44//! |---|---|
45//! | transforms | [`Affine2D`] |
46//! | paths | [`Path2D`], [`PathBuilder`] with a transform stack |
47//! | filling | [`fill_path`] — exact analytic coverage, [`FillRule`] |
48//! | stroking | [`stroke_path`] — expand to an outline, then fill |
49//! | glyphs | [`rasterize_glyph`], [`rasterize_outline`], [`Hinting`], [`GlyphBitmap`] |
50//! | text | [`shape_line`], [`measure_run`], [`measure_glyph`], [`resolve_bidi`] |
51//!
52//! # The rasterizer
53//!
54//! [`fill_path`] computes the **exact area** each pixel covers, integrating the
55//! span coverage analytically rather than supersampling. Two properties follow,
56//! and both are asserted in the test suite:
57//!
58//! - An axis-aligned rectangle on integer boundaries is *exactly* `255` in its
59//! interior and `0` outside; shifted half a pixel it is *exactly* `128` on
60//! each edge.
61//! - A mask's total coverage equals the polygon it came from: for a 64-unit
62//! right triangle, the ink matches `½·64·64` to within 0.1 %. That single
63//! number bounds every antialiasing claim this crate makes.
64//!
65//! Device space is **y down**, pixel `(x, y)` covering `[x, x+1) × [y, y+1)`.
66//! [`rasterize_glyph`] flips a font's y-up outline into that space and carries
67//! all intermediate arithmetic in 26.6 fixed point, so a glyph lands on the
68//! pixel grid the same way at 12 px and 144 px.
69//!
70//! ```
71//! use font_shape::{fill_path, FillRule, PathBuilder};
72//!
73//! let mut b = PathBuilder::new();
74//! b.rect(0.5, 0.0, 4.0, 1.0);
75//! let mask = fill_path(&b.build(), FillRule::NonZero, 8, 1)?;
76//!
77//! assert_eq!(mask[0], 128, "half a pixel of coverage is exactly 128");
78//! assert_eq!(mask[1], 255);
79//! assert_eq!(mask[4], 128);
80//! assert_eq!(mask[5], 0);
81//! # Ok::<(), font_shape::ShapeError>(())
82//! ```
83//!
84//! # Layer
85//!
86//! L2 — domain. Its only estate-internal dependency is `font-model` (L1).
87//! `libm` supplies the `no_std` transcendentals and `thiserror` the error
88//! taxonomy. There is deliberately **no** image or rasterizer dependency: the
89//! scanline filler is the point of the crate.
90//!
91//! [`font-parse`]: https://docs.rs/font-parse
92
93#![cfg_attr(not(feature = "std"), no_std)]
94#![deny(missing_docs)]
95#![forbid(unsafe_code)]
96
97extern crate alloc;
98
99mod affine;
100mod error;
101mod glyph;
102mod measure;
103mod path;
104mod raster;
105mod stroke;
106
107pub use affine::Affine2D;
108pub use error::{message, Result, ShapeError};
109pub use glyph::{
110 em_size_px, fixed_scale, from_fixed, glyph_path, glyph_path_from_outline, grid_fit,
111 rasterize_glyph, rasterize_outline, scaled_metrics, to_26_6, to_fixed, DeviceMetrics,
112 GlyphBitmap, Hinting, PIXEL, PIXEL_FP_BITS,
113};
114pub use measure::{
115 ascii_cmap, bidi_class, describe_run, is_rtl_level, measure_glyph, measure_run,
116 reorder_indices, resolve_bidi, resolve_bidi_chars, set_explicit_levels, shape_line,
117 shape_line_with, BidiClass, BidiLevels, GlyphPlacement, LayoutDirection, ShapedLine,
118};
119pub use path::{Path2D, PathBuilder, PathCommand, Rect};
120pub use raster::{fill_path, mask_coverage, path_pixel_bounds, FillRule, MAX_MASK_ELEMENTS};
121pub use stroke::{stroke_path, LineCap, LineJoin, StrokeStyle, DEFAULT_MITER_LIMIT};
122
123/// The crate's version, for callers that report it.
124pub const VERSION: &str = env!("CARGO_PKG_VERSION");