Crate pdfrum_font

Expand description

§pdfrum-font

Font dictionaries and the glyph pipeline (ISO 32000-1 §9): Type 1, TrueType, Type 0 composite, Type 3 procedure and CID fonts; simple and /Differences encodings, CMaps, /ToUnicode, the base-14 substitutes, and the widths ladder.

use pdfrum_common::{Diagnostics, Limits};
use pdfrum_font::{FontCache, load};
use pdfrum_object::NoResolve;

let Some(font) = load(
    dict,
    &NoResolve,
    &FontCache::default(),
    &Limits::default(),
    &mut Diagnostics::default(),
) else {
    return;
};
for item in font.decode(b"Hello") {
    let _ = (item.code, item.gid, item.width, &item.unicode);
}

Which glyph a byte selects, what character it stands for, and how wide it is are three different ladders, and a font can answer any one of them without the others. The glyph comes from the encoding and the font program; the character comes from /ToUnicode, then the encoding’s glyph names, then a CID-to-Unicode table; the width comes from /Widths or /W, then the program’s own metrics, then a default. A file routinely disagrees with itself across the three — text that draws correctly but copies as mojibake is exactly that disagreement. Font::decode answers all three at once, per code, so a caller never has to re-derive one from another.

A simple font always constructs. Only Type0 can fail to load, because only it depends on a CMap that may be unresolvable; everything else falls back — a missing program becomes a base-14 substitute, a missing width becomes the default — because a page with an unloadable font still has to draw. FontCache is shared across pages, since a document’s fonts are per-document and re-parsing an embedded program per page is the difference between a fast and a slow render.

Feature system-fonts adds host font fallback via fontdb; it is not available on wasm32, where the bundled base-14 faces carry the text.

Part of pdfrum. #![forbid(unsafe_code)].

MIT OR Apache-2.0

Structs§

CharCode: A character code: one unit of a PDF string as split by a CMap’s decoder (ISO 32000-1 §9.7.5). Between 1 and 4 bytes wide depending on the coding scheme, so the value alone does not say how many bytes it came from; ask CMap::char_size.
CharItem: One decoded character: everything the layers above need about one character code, computed once.
CharmapId: A charmap’s (platform, encoding) identity, as the cmap table declares it.
Cid: A character identifier: an index into a character collection, which a CIDFont turns into a glyph (ISO 32000-1 §9.7.4). CID 0 is .notdef and is also what an unmapped character code yields.
CidTransform: A per-CID affine transform, packed into bytes.
Face: A font face, owning its bytes.
FontCache: Per-document caches: loaded fonts, and the font-identity counter.
FontFlags: The /FontDescriptor /Flags bit set (ISO 32000-1 table 123), plus PDFium’s own USE_EXTERN_ATTR bit.
FontId: Identifies one loaded font within a FontCache, so a glyph cache entry cannot be mistaken for another font’s.
Gid: A glyph index into a font program.
GlyphCache: Memoized glyph outlines in 1000/em text space.
GlyphKey: What identifies one cached outline.
SimpleFont: A one-byte-per-code font.
SubstFont: The record a substitution produces.
SubstitutionOptions: How substitution finds faces.
Type0Font: A composite font.
Type1FontFile: A Type 1 program as a PDF /FontFile stream: the bytes to store, and the ISO 32000-1 §9.9 table 127 lengths that partition them.
Type3Font: A font whose glyphs are content streams.

Enums§

Charmap: Which charmap a lookup reads.
Charset: A Windows charset, as FX_Charset.
Error: What went wrong while loading a font.
FaceEncoding: The fxge-level encodings a font face’s charmap may declare, which are a different set from FontEncoding and are reverse-mapped through the raw tables (CharCodeFromUnicodeForEncoding, the former working note).
Font: A loaded PDF font, ready to decode strings and produce glyphs.
GlyphSource: Where glyphs come from.
StandardFont: One of the fourteen standard fonts.

Constants§

MAX_TYPE3_DEPTH: The maximum nesting of Type 3 glyph procedures, which may themselves show text in a Type 3 font (kMaxType3FormLevel). Ported verbatim.

Functions§

adobe_name_from_unicode: The canonical glyph name for a Unicode value, or None.
canonical_font_name: The canonical PostScript name.
charset_from_unicode: Guess a charset from a single character (GetCharSetFromUnicode).
cid_transform_to_float: Unpack one byte of a transform.
em_adjust: The other 1000/em normalizer: truncating integer division, no rounding and no saturation. Used only for a glyph’s advance width.
invert_to_unicode: Invert a /ToUnicode CMap: Unicode scalar → the character code that maps to it, for every code the program reaches.
load: Build a Font from a /Font resource dictionary.
load_with_options: load, with control over how substitution finds system faces.
type1_font_file: A Type 1 program as the /FontFile stream a PDF writer stores, with the ISO 32000-1 table 127 lengths that partition it.