Struct Font 

pub struct Font<'a> { /* private fields */ }

A parsed TrueType / OpenType font, lifetime-bound to the input bytes.

Font::from_bytes walks the sfnt header + table directory once; the individual *Table parsers are run on first use and cached as already-validated slices on the struct. Lookup methods (glyph_index, glyph_outline, etc.) are O(log n) or O(n) over the raw table bytes — no glyphs are pre-decoded or cached.

Implementations

impl<'a> Font<'a>

pub fn shape( &self, text: &str, script: [u8; 4], lang: Option<[u8; 4]>, features: &[[u8; 4]], ) -> Vec<ShapedGlyph>

Shape a run of text into positioned glyphs under script / lang, applying the listed features.

script and lang are OpenType tags (*b"latn", *b"arab", *b"DFLT"; lang = None selects the script’s default language system). features is the ordered list of feature tags the caller wants enabled (e.g. [*b"ccmp", *b"liga", *b"kern"]); a feature tag the font does not list under the active script is silently ignored. The relative order of features does not by itself dictate application order — the GSUB/GPOS lookups behind the union of requested features run in LookupList order, per the OpenType common-table-format rules — but it determines which features are active.

Returns one ShapedGlyph per output glyph. For a font with no GSUB/GPOS, this degenerates to nominal cmap mapping with hmtx advances (i.e. unshaped glyph runs still come back correctly positioned for simple scripts).

The variation-instance-aware feature resolution (Font::gsub_features_for_script_at_instance) is used, so a variable font shaped after Font::set_variation_coords honours its FeatureVariations substitutions.

impl<'a> Font<'a>

pub fn from_collection_bytes(bytes: &'a [u8], index: u32) -> Result<Self, Error>

Parse the index-th subfont out of a TrueType Collection (.ttc / 'ttcf') byte slice.

TTC files start with a 'ttcf' magic followed by a list of byte offsets pointing at per-subfont sfnt headers. This entry point reads the TTC header, then runs the regular sfnt parse path against the slice rooted at the chosen subfont. The returned Font<'a> borrows from the original bytes (sub-slicing is done internally; the lifetime stays tied to the input).

Returns:

• Error::BadMagic if bytes is not a TTC.
• Error::SubfontOutOfRange(index) if the chosen index exceeds numFonts.
• Whatever the underlying sfnt path emits otherwise (typically MissingTable / BadOffset for a malformed subfont).

Spec: Microsoft OpenType §“Font Collections”, Apple TrueType Reference / “TrueType Collections”.

pub fn from_bytes(bytes: &'a [u8]) -> Result<Self, Error>

Parse a font from a borrowed byte slice.

pub fn bytes(&self) -> &'a [u8]

Raw bytes used to build this Font. Mostly useful for debugging.

pub fn family_name(&self) -> Option<&str>

Family name from the name table (Windows English first, falls back to Mac Roman if that’s all the font has).

pub fn full_name(&self) -> Option<&str>

Full name (typically family + style) from the name table.

pub fn subfamily_name(&self) -> Option<&str>

Subfamily (style) name from the name table — e.g. “Bold”, “Italic”, “Regular”. nameID 2 (Adobe TN5149 §1.4).

pub fn typographic_family_name(&self) -> Option<&str>

Typographic (preferred) family name — nameID 16 — falling back to the standard family name (nameID 1) when the font omits it. Adobe TN5149 §1.4: when nameID 16 equals nameID 1 it may be omitted, so the fallback reconstructs the intended value.

pub fn typographic_subfamily_name(&self) -> Option<&str>

Typographic (preferred) subfamily name — nameID 17 — falling back to the standard subfamily name (nameID 2). Same omission rule as Self::typographic_family_name (TN5149 §1.4).

pub fn postscript_name(&self) -> Option<&str>

PostScript name — nameID 6 (TN5149 §1.5). The unique name a PostScript interpreter uses to select the font.

pub fn version_string(&self) -> Option<&str>

Version string — nameID 5 (TN5149 §1.9), e.g. “Version 1.000”.

pub fn copyright(&self) -> Option<&str>

Copyright notice — nameID 0 (TN5149 §1.3).

pub fn trademark(&self) -> Option<&str>

Trademark — nameID 7 (TN5149 §1.10).

pub fn manufacturer(&self) -> Option<&str>

Manufacturer name — nameID 8 (TN5149 §1.10).

pub fn designer(&self) -> Option<&str>

Designer name — nameID 9 (TN5149 §1.10).

pub fn description(&self) -> Option<&str>

Description — nameID 10 (TN5149 §1.10).

pub fn vendor_url(&self) -> Option<&str>

Font vendor URL — nameID 11 (TN5149 §1.10).

pub fn designer_url(&self) -> Option<&str>

Font designer URL — nameID 12 (TN5149 §1.10).

pub fn license_description(&self) -> Option<&str>

Licence description — nameID 13 (TN5149 §1.10).

pub fn license_url(&self) -> Option<&str>

Licence URL — nameID 14 (TN5149 §1.10).

pub fn name_string(&self, name_id: u16) -> Option<&str>

Arbitrary name-table string by nameID, picking the best-ranked locale (Windows English first). The well-known IDs are exported as name_id constants. Use Self::name_string_for to target a specific platform + language.

pub fn name_string_for( &self, name_id: u16, platform_id: u16, language_id: u16, ) -> Option<String>

A specific (nameID, platformID, languageID) string — no ranking, the exact locale you name (e.g. (name_id::FAMILY, platform::WINDOWS, 0x0411) for the Japanese family name). Returns an owned String because non-ASCII records are decoded into a new buffer. None when no record matches or its encoding is one we cannot decode without an unstaged legacy codepage table (Macintosh non-Roman scripts — TN5149 §1.2).

pub fn name_records(&self) -> Vec<NameRecord>

Every name-table record, decoded where possible (see NameRecord). The locator tuple (platformID, encodingID, languageID, nameID) is always present; string is None for encodings we cannot decode in-crate.

pub fn units_per_em(&self) -> u16

head.unitsPerEm. Almost always 1024 or 2048; never zero in valid fonts.

pub fn head_table(&self) -> &HeadTable

Borrow the parsed head table (ISO/IEC 14496-22:2019 §5.2.1), exposing fontRevision, the flags / macStyle words (with decoded predicates), the created / modified timestamps, lowestRecPPEM, fontDirectionHint, and glyphDataFormat.

pub fn font_revision(&self) -> f32

head.fontRevision — the font designer’s revision number as a 16.16 fixed value (e.g. 2.37).

pub fn lowest_rec_ppem(&self) -> u16

head.lowestRecPPEM — the smallest size, in pixels, at which the font is intended to remain legible.

pub fn ascent(&self) -> i16

Typographic ascent. We prefer OS/2.sTypoAscender if present (Windows-clean), falling back to hhea.ascent.

pub fn descent(&self) -> i16

Typographic descent (typically negative).

pub fn line_gap(&self) -> i16

Suggested gap between lines.

pub fn glyph_count(&self) -> u16

maxp.numGlyphs.

pub fn hhea_table(&self) -> &HheaTable

Borrow the parsed hhea table (ISO/IEC 14496-22:2019 §5.2.4), exposing the horizontal header in full: ascent / descent / line gap, advanceWidthMax, the min side-bearing extremes, xMaxExtent, the caret-slope rise / run / offset, and numberOfHMetrics.

pub fn maxp_table(&self) -> &MaxpTable

Borrow the parsed maxp table (ISO/IEC 14496-22:2019 §5.2.5). For a v1.0 (TrueType) table the v1 field carries the rasteriser-sizing maxima (maxPoints, composite limits, bytecode resource caps, maxComponentDepth); v1 is None for a v0.5 (CFF) table.

pub fn weight_class(&self) -> u16

OS/2.usWeightClass (100..1000), or 400 (Regular) if OS/2 absent.

pub fn width_class(&self) -> u16

OS/2.usWidthClass (1..9, where 5 = Medium/Normal), or 5 if OS/2 is absent (ISO/IEC 14496-22:2019 §5.2.3).

pub fn os2_table(&self) -> Option<&Os2Table>

Borrow the parsed OS/2 table (ISO/IEC 14496-22:2019 §5.2.3), when the font publishes one. Exposes the full field set: classification (weight / width / PANOSE / family class), fsType embedding permissions, fsSelection style bits, the sub/superscript and strikeout metrics, Unicode / code-page coverage ranges, vendor id, the typographic / Windows vertical metrics, and (versioned) x-height / cap-height / optical-size range.

pub fn embedding_installable(&self) -> Option<bool>

The OS/2.fsType embedding-permission state, distilled to the single most-restrictive applicable flag, or None when OS/2 is absent. installable (no restriction bit) is the permissive default. See [Os2Table]’s embedding_* predicates for the raw bits.

pub fn italic_angle(&self) -> f32

post.italicAngle in degrees (negative for forward-slanted).

pub fn has_post(&self) -> bool

true when the font ships a post table (any version).

pub fn has_cff_outlines(&self) -> bool

true when the font carries PostScript (CFF ) outlines rather than (or in addition to) TrueType glyf outlines.

pub fn cff_table(&self) -> Option<&CffTable<'a>>

Borrow the parsed CFF table, when the font ships one.

pub fn has_cff2_outlines(&self) -> bool

true when the font carries variable PostScript (CFF2) outlines.

pub fn cff2_table(&self) -> Option<&Cff2Table<'a>>

Borrow the parsed CFF2 table, when the font ships one.

pub fn is_cid_keyed(&self) -> bool

true when the CFF table is CID-keyed (Adobe TN #5176 §18).

pub fn has_math(&self) -> bool

true when the font ships a MATH table (math typesetting data).

pub fn math_table(&self) -> Option<&MathTable<'a>>

Borrow the parsed MATH table, when the font publishes one (ISO/IEC 14496-22:2019 §6.3.6).

pub fn math_constant_var(&self, index: usize) -> Option<f32>

A MathConstants value (one of the tables::math::constant::* indices) resolved at the font’s current variation instance.

Folds in the record’s VariationIndex correction (§6.3.6.2.1) against the GDEF ItemVariationStore at the instance set via Self::set_variation_coords. Returns None when the font has no MATH table or no MathConstants sub-table; the value is in font design units (fractional after variation). For a non-variable font the result equals the plain MathConstants design-unit value.

pub fn math_italics_correction_var(&self, gid: u16) -> Option<f32>

Per-glyph MATH italics correction for gid resolved at the current variation instance (§6.3.6.2.5 + §6.3.6.2.1). None when there is no MATH table, no MathGlyphInfo, or gid is uncovered.

pub fn math_top_accent_attachment_var(&self, gid: u16) -> Option<f32>

Per-glyph MATH top-accent attachment point for gid resolved at the current variation instance (§6.3.6.2.6 + §6.3.6.2.1). None when uncovered (the layout engine then uses the glyph’s geometric centre).

pub fn math_kern_var( &self, gid: u16, corner: MathKernCorner, height: i16, ) -> Option<f32>

MATH per-corner kern value for gid at correction height, resolved at the current variation instance (§6.3.6.2.8/.9 + §6.3.6.2.1). None when gid has no kern table for corner.

pub fn math_assembly_italics_correction_var( &self, gid: u16, dir: GrowDirection, ) -> Option<f32>

MATH glyph-assembly italics correction for gid growing in dir, resolved at the current variation instance (§6.3.6.2.12 + §6.3.6.2.1). None when gid has no assembly in dir.

pub fn has_jstf(&self) -> bool

true when the font ships a JSTF table (justification data).

pub fn jstf_table(&self) -> Option<&JstfTable<'a>>

Borrow the parsed JSTF table, when the font publishes one (ISO/IEC 14496-22:2019 §6.3.5).

pub fn has_dsig(&self) -> bool

true when the font ships a DSIG table (a digital signature).

pub fn dsig_table(&self) -> Option<&DsigTable<'a>>

Borrow the parsed DSIG table (ISO/IEC 14496-22:2019 §8.x), when the font publishes one. The table carries one or more PKCS#7 signature blocks surfaced as raw bytes; this crate decodes the table structure but does not verify the signature cryptographically.

pub fn has_merg(&self) -> bool

true when the font ships a MERG table (glyph-merge declarations for antialias filtering, ISO/IEC 14496-22:2019 §5.7.5).

pub fn merg_table(&self) -> Option<&MergTable>

Borrow the parsed MERG table, when the font publishes one. The table maps glyphs to merge classes and gives a per-class-pair merge-entry byte; the run-processing algorithm that consumes those entries is a renderer concern.

pub fn post_table(&self) -> Option<&PostTable>

Borrow the parsed post table. None when the font does not publish one.

pub fn glyph_name_ref(&self, gid: u16) -> Option<GlyphNameRef<'_>>

Resolve glyph gid’s post-table name reference, when the table publishes one.

Returns:

• Some(GlyphNameRef::Custom(name)) — the font supplied the glyph’s name as a v2.0 Pascal string. The string is already trimmed of its length byte.
• Some(GlyphNameRef::StandardMac { index }) — the glyph resolves to entry index of the 258-name standard Macintosh glyph table (referenced through v1.0, v2.0, or v2.5). The 258-name array is staged in docs/text/opentype/ and exposed as STANDARD_MAC_GLYPH_NAMES; Font::glyph_name resolves the index into the canonical name. This lower-level accessor surfaces the raw index so tooling can introspect the reference without name resolution.
• None — the font has no post table, the table is v3.0 (no glyph names at all), gid falls outside the v2.0 / v2.5 index array, or the index references a Pascal string the pool cannot satisfy.

pub fn glyph_name(&self, gid: u16) -> Option<&str>

Convenience accessor: return the glyph’s PostScript name, resolving both post-name branches.

A font-supplied v2.0 Pascal string is returned directly; a StandardMac { index } reference (from v1.0, v2.0 with glyphNameIndex < 258, or v2.5) is resolved through the STANDARD_MAC_GLYPH_NAMES table into its canonical standard Macintosh name.

Returns None when no name is available — the font has no post table, the table is v3.0 (no names at all), or gid falls outside the table’s index space. Use Font::glyph_name_ref to distinguish the custom and standard-Mac branches when that matters.

pub fn gid_for_glyph_name(&self, name: &str) -> Option<u16>

Reverse lookup: the glyph id named name by the post table, inverting Font::glyph_name.

Resolves over every named glyph the table publishes — v2.0 custom Pascal strings and standard-Macintosh names alike (from v1.0, v2.0 with glyphNameIndex < 258, or v2.5). The comparison is exact byte equality (PostScript glyph names are ASCII).

Returns the lowest glyph id carrying that name, or None when the font has no post table, the table is v3.0, or no glyph is named name.

pub fn iter_glyph_names(&self) -> Box<dyn Iterator<Item = (u16, &str)> + '_>

Iterate every (glyph_id, post-table name) pair the font publishes, in ascending glyph-id order.

Standard-Macintosh references are resolved to their canonical names; v2.0 custom strings are returned directly. Glyph ids the post table names with an unsatisfiable reference are skipped. The iterator is empty when the font has no post table or the table is v3.0 (no names at all).

pub fn glyph_index(&self, codepoint: char) -> Option<u16>

Map a Unicode codepoint to its glyph id.

pub fn lookup_variation( &self, codepoint: char, variation_selector: char, ) -> Option<u16>

Look up the variant glyph for a (codepoint, variation_selector) pair from the cmap format-14 (Unicode Variation Sequences) subtable.

Returns:

• Some(glyph) from the non-default UVS table when the variation selector overrides the base glyph (e.g. emoji presentation <emoji, U+FE0F>, text presentation <emoji, U+FE0E>, or registered Ideographic Variation Sequence <CJK, U+E0100..U+E01EF>).
• Some(base) when the pair is in the default UVS table — semantically “render the base codepoint’s default glyph; the variation selector is just a hint”. Equivalent to Self::glyph_index for the base codepoint, returned for API symmetry so callers don’t have to special-case the default-presentation branch.
• None when the font has no format-14 subtable, the variation selector isn’t enumerated, or neither UVS table covers the base codepoint.

pub fn glyph_outline(&self, glyph_id: u16) -> Result<TtOutline, Error>

Decode the TrueType outline for glyph_id. Empty / blank glyphs (e.g. the space glyph) return an outline with zero contours.

Returns an empty outline when the font has no glyf/loca (CBDT/CBLC-only colour-emoji fonts). Callers that care should check Font::has_color_bitmaps first.

Variable fonts: if the font ships fvar/gvar and the caller has set non-default coordinates via Font::set_variation_coords, the static outline returned here has gvar deltas applied (with avar remap on the input coords first).

Both simple and composite glyphs are retargeted. For a composite glyph the gvar packed point numbers address the components (plus four phantom points), not flattened outline points, per ISO/IEC 14496-22:2019 §7.3.4.3 — the per-component (dx, dy) placement deltas are folded into each component’s X/Y offset (and scaled with the offset where SCALED_COMPONENT_OFFSET is set) before the children are flattened. Point-matched components take no delta, and nested components inherit their own glyph’s variation when decoded as top-level glyphs, matching the spec’s “most deeply-nested first” processing order.

pub fn glyph_advance(&self, glyph_id: u16) -> i16

Per-glyph advance width in font units.

For a composite glyph whose components include one carrying the USE_MY_METRICS flag (§5.3.4), the advance is taken from that component’s hmtx entry rather than the composite’s own — the spec uses this to force a composite (e.g. i-circumflex) to inherit a component’s (e.g. dotless-i) metrics. The last flagged component wins; the chase is depth-bounded.

pub fn glyph_lsb(&self, glyph_id: u16) -> i16

Per-glyph left-side bearing in font units. Honours USE_MY_METRICS the same way as Font::glyph_advance (the spec forces both aw and lsb to the flagged component’s values).

pub fn has_vertical_metrics(&self) -> bool

true when the font ships both a vhea and vmtx table — i.e. it supplies vertical-layout metrics for CJK / Mongolian or other top-to-bottom-written scripts.

pub fn vhea_table(&self) -> Option<&VheaTable>

Borrow the parsed vhea table, when present. (ISO/IEC 14496-22:2019 §5.7.9.)

pub fn vertical_ascent(&self) -> Option<i16>

Vertical typographic ascender from vhea. For v1.1 this is vertTypoAscender (distance in font design units from the ideographic em-box centre baseline to the right side of the em-box, per §5.7.9 v1.1 row 2); for v1.0 the same bytes are the centre-line-relative ascent field. Returns None if the font lacks a vhea table.

pub fn vertical_descent(&self) -> Option<i16>

Vertical typographic descender from vhea (v1.1 vertTypoDescender; v1.0 descent).

pub fn vertical_line_gap(&self) -> Option<i16>

Vertical typographic line gap from vhea (v1.1 vertTypoLineGap; v1.0 row “Reserved; set to 0”, so static v1.0 fonts will return Some(0) here).

pub fn advance_height_max(&self) -> Option<i16>

vhea.advanceHeightMax — the maximum advance height in the font, in design units. Per §5.7.9 the field is int16.

pub fn vmtx_table(&self) -> Option<&VmtxTable<'a>>

Borrow the parsed vmtx table, when present. (ISO/IEC 14496-22:2019 §5.7.10.)

pub fn glyph_advance_height(&self, glyph_id: u16) -> Option<u16>

Per-glyph advance height in font design units. Returns None when the font lacks vhea/vmtx; otherwise returns the vMetrics advance for glyph_id, with the §5.7.10 “monospaced tail” rule (glyphs beyond numOfLongVerMetrics inherit the last pair’s advance height) applied transparently.

pub fn glyph_top_side_bearing(&self, glyph_id: u16) -> Option<i16>

Per-glyph top side bearing in font design units. Returns None when the font lacks vmtx.

pub fn glyph_vertical_origin_y(&self, glyph_id: u16) -> Option<i16>

Per-glyph vertical origin Y coordinate in font design units. Per §5.7.10 (“Vertical Origin and Advance Height”), this is topSideBearing + glyph_bounding_box.y_max. Returns None when the font lacks vmtx or when the glyph has no outline bounding box (empty glyph, blank glyph, or a CBDT-only colour- emoji font with no glyf/loca). For CFF fonts the spec recommends the optional VORG table instead; that path is not implemented here (TrueType outlines only).

pub fn has_vorg(&self) -> bool

true when the font ships a VORG table per §5.4.4. The table is optional and, per spec, restricted to CFF-flavoured sfnts; it appears occasionally in TrueType sfnts as well, in which case the parser surfaces the bytes but Self::vert_origin_y_from_vorg declines to consult it (the spec mandates “If present in TrueType OFF fonts it must be ignored by font clients”).

pub fn vorg_table(&self) -> Option<&VorgTable>

Borrow the parsed VORG table, when present. Surfaced verbatim so callers that want to introspect the metrics array directly (e.g. font tooling) can do so without re-parsing the bytes.

pub fn vorg_default_vert_origin_y(&self) -> Option<i16>

Default vertical-origin Y per §5.4.4, in font design units. Returns None when no VORG table is present.

pub fn vert_origin_y_from_vorg(&self, glyph_id: u16) -> Option<i16>

Y coordinate of the vertical origin for glyph_id per VORG §5.4.4, in font design units.

Returns:

• None when the font has no VORG.
• None when the font is TrueType-flavoured (a glyf table is present). §5.4.4 mandates “If present in TrueType OFF fonts it must be ignored by font clients, just as any other unrecognized table would be”; we honour that rule here. Callers that want the TrueType-derived origin should use Self::glyph_vertical_origin_y (which derives the value from vmtx.topSideBearing + glyf bbox per §5.7.10).
• Some(default_vert_origin_y) when the glyph has no per-glyph override entry — §5.4.4 size-optimised form (“glyphs whose vertical origin’s y coordinate equals defaultVertOriginY will not have an entry”).
• Some(vert_origin_y) from the metrics-array override when one is present.

pub fn has_base(&self) -> bool

true when the font ships a BASE table (ISO/IEC 14496-22:2019 §6.3.1). The table is optional for both TrueType and CFF sfnts and is consulted by text-layout clients when aligning glyphs from different scripts on a common baseline.

pub fn base_table(&self) -> Option<&BaseTable>

Borrow the parsed BASE table when present. Exposes the HorizAxis / VertAxis trees plus (in v1.1 tables) the ItemVariationStore offset for variable-font baseline deltas.

pub fn base_horiz_y_for_script_baseline( &self, script_tag: [u8; 4], baseline_tag: [u8; 4], ) -> Option<i16>

Per-script default Y baseline (HorizAxis, §6.3.1.3) for the given script tag and baseline tag. Returns the design-unit coordinate from the BaseValues entry whose index matches baseline_tag inside the Axis’s BaseTagList.

Returns None when:

• the font has no BASE table;
• the HorizAxis is missing (typical for CJK vertical-only fonts);
• the script tag is not listed in the Axis’s BaseScriptList (§6.3.1.3 “If a script is not listed here, then the text-processing client will render the script using the layout information specified for the entire font”);
• the BaseTagList is NULL or baseline_tag is not in it;
• the BaseValues array is shorter than the BaseTagList index.

pub fn base_vert_x_for_script_baseline( &self, script_tag: [u8; 4], baseline_tag: [u8; 4], ) -> Option<i16>

Per-script default X baseline (VertAxis, §6.3.1.3) for the given script tag and baseline tag. Mirror of Self::base_horiz_y_for_script_baseline for vertical layout.

pub fn base_horiz_y_for_script_baseline_var( &self, script_tag: [u8; 4], baseline_tag: [u8; 4], ) -> Option<i16>

Variation-aware sibling of Self::base_horiz_y_for_script_baseline: a BaseCoordFormat3 VariationIndex device offset is resolved against the BASE ItemVariationStore at the font’s current instance, so the baseline Y tracks the design axes.

pub fn base_vert_x_for_script_baseline_var( &self, script_tag: [u8; 4], baseline_tag: [u8; 4], ) -> Option<i16>

Variation-aware sibling of Self::base_vert_x_for_script_baseline.

pub fn has_gasp(&self) -> bool

true when the font carries a gasp table (ISO/IEC 14496-22:2019 §5.3.7). Absent in many fonts; the rasteriser applies its default policy when missing.

pub fn gasp_table(&self) -> Option<&GaspTable>

Borrow the parsed gasp table when present. Carries the per-ppem rasterisation hints (GASP_GRIDFIT, GASP_DOGRAY, GASP_SYMMETRIC_GRIDFIT, GASP_SYMMETRIC_SMOOTHING) sorted by rangeMaxPPEM.

pub fn gasp_behavior_for_ppem(&self, ppem: u16) -> Option<&GaspRange>

Pick the gasp record that governs rasterisation at the given pixel-per-em size — the first record whose rangeMaxPPEM is at least ppem (§5.3.7). Returns None when the font ships no gasp table or every record’s upper limit is below ppem; in either case the caller should fall back to the rasteriser’s default policy.

pub fn has_ltsh(&self) -> bool

true when the font ships an LTSH table (ISO/IEC 14496-22:2019 §5.7.4). Absent in most fonts; rasterisers without one always grid-fit (or consult hdmx / vdmx if those are present instead) to find each glyph’s true advance width.

pub fn ltsh_table(&self) -> Option<&LtshTable>

Borrow the parsed LTSH table when present. Carries the per-glyph yPels array recording each glyph’s linear-threshold ppem per §5.7.4.

pub fn ltsh_threshold(&self, glyph_id: u16) -> Option<u8>

Lowest ppem at which the grid-fitted advance for glyph_id has converged on the rounded linear advance per §5.7.4 — i.e. the rasteriser may round the design-unit advance to integer pixels at every ppem at least the returned value. Returns None when the font ships no LTSH table or glyph_id is out of range.

pub fn ltsh_linearly_scales_at_ppem(&self, glyph_id: u16, ppem: u16) -> bool

true when glyph_id is safe to advance-scale linearly at ppem per §5.7.4 — i.e. ppem >= LTSH.yPels[glyph_id]. When the font ships no LTSH table, returns false so the caller falls back to grid-fitting (which is what §5.7.4 also prescribes for fonts without an LTSH). Returns false for out-of-range glyph_id.

pub fn has_hdmx(&self) -> bool

true when the font ships an hdmx table (ISO/IEC 14496-22:2019 §5.7.2). Optional table; absent in most fonts. §7.3.5 forbids hdmx in variable fonts — a caller that wants to validate the font shape may pair this with Self::is_variable.

pub fn hdmx_table(&self) -> Option<&HdmxTable>

Borrow the parsed hdmx table when present. Carries the per-ppem device records mapping each glyph to its grid-fitted integer-pixel advance width at that ppem.

pub fn hdmx_advance_pixels(&self, glyph_id: u16, ppem: u8) -> Option<u8>

Grid-fitted advance width of glyph_id at the requested ppem, in integer pixels, per §5.7.2. Returns None when the font ships no hdmx, when the requested ppem is not in the table’s record array (§5.7.2 has no “round down” rule — the caller falls back to scan-converting), or when glyph_id exceeds the recorded per-glyph array. ppem is u8 because the on-wire field that drives the lookup is uint8; values above 255 ppem are not representable in the table.

pub fn hdmx_recorded_ppem_sizes(&self) -> Vec<u8>

The set of ppem sizes the font’s hdmx table covers, in ascending order. Returns an empty Vec when no hdmx is present.

pub fn has_vdmx(&self) -> bool

true when the font ships a VDMX table (ISO/IEC 14496-22:2019 §5.7.8). Optional table; absent in most fonts. §7.3.5 forbids VDMX in variable fonts — pair with Self::is_variable when validating a font’s shape.

pub fn vdmx_table(&self) -> Option<&VdmxTable>

Borrow the parsed VDMX table when present. Carries one or more VDMX groups indexed via a per-aspect-ratio RatioRange array; each group publishes per-ppem (yMax, yMin) envelopes for the font as a whole.

pub fn vdmx_y_extent_for_device( &self, ppem: u16, device_x_ratio: u8, device_y_ratio: u8, ) -> Option<(i16, i16)>

(yMax, yMin) pel envelope for (ppem, deviceXRatio, deviceYRatio), per §5.7.8’s first-match RatioRange search. Returns None when the font ships no VDMX, when no RatioRange matches the device pair (and there is no (0,0,0) sentinel), or when the matched group does not record the exact ppem requested (§5.7.8 “need not be continuous” — no fallback to neighbouring records).

For square-pixel screens the canonical call is vdmx_y_extent_for_device(ppem, 1, 1).

pub fn vdmx_y_extent_square(&self, ppem: u16) -> Option<(i16, i16)>

Convenience for the common square-pixel case: equivalent to vdmx_y_extent_for_device(ppem, 1, 1). Returns the (yMax, yMin) pel envelope at ppem under the 1:1 RatioRange (matching either the explicit (xRatio=1, yStartRatio=1, yEndRatio=1) entry, or the (0,0,0) catch-all sentinel when present), or None otherwise.

pub fn has_meta(&self) -> bool

true when the font ships a meta (Metadata) table per ISO/IEC 14496-22:2019 §5.7.6.

pub fn meta_table(&self) -> Option<&MetaTable<'a>>

Borrow the parsed meta table when present.

The returned [MetaTable] carries the §5.7.6 DataMap array; per-record payloads borrow from the on-wire meta byte slice for the lifetime of the Font.

pub fn meta_record(&self, tag: &[u8; 4]) -> Option<MetaRecord<'_>>

First meta DataMap record whose tag equals tag, or None. §5.7.6.1’s closing paragraph permits multiple records for the same tag but specifies that “any instances after the first may be ignored” for single-record tags; this accessor honours that rule by returning the first match. Callers that want every record for a duplicated tag should iterate [MetaTable::records] directly.

pub fn meta_design_languages(&self) -> Option<&'a str>

Design-language declaration from the meta table’s 'dlng' record (ISO/IEC 14496-22:2019 §5.7.6.2), if present and well-formed UTF-8. The value is a comma-separated list of ScriptLangTags identifying the languages or scripts the font was primarily designed for.

pub fn meta_supported_languages(&self) -> Option<&'a str>

Supported-language declaration from the meta table’s 'slng' record (ISO/IEC 14496-22:2019 §5.7.6.2), if present and well-formed UTF-8. Used to declare languages or scripts the font is capable of supporting (a superset of Self::meta_design_languages in typical use).

pub fn has_pclt(&self) -> bool

true when the font ships a PCLT (PCL 5) table per ISO/IEC 14496-22:2019 §5.7.7. The spec deems the table “strongly discouraged for OFF fonts with TrueType outlines”, so a true here typically marks a legacy font.

pub fn pclt_table(&self) -> Option<&PcltTable>

Borrow the parsed PCLT table when present.

The returned [PcltTable] carries the §5.7.7 PCL 5 font-selection attributes: HP font number, pitch / x-height / cap-height design-unit metrics, the packed style / type-family / symbol-set words, the typeface “font print” string, the character-complement bitfield, the PCL file name, and the stroke-weight / width-type / serif-style classification bytes.

pub fn has_svg(&self) -> bool

true when the font ships an SVG table per ISO/IEC 14496-22:2019/Amd.1:2020 §5.5.1 — vector colour-glyph descriptions as SVG 1.1 documents. This is one of the four colour-glyph mechanisms (COLR/CPAL, CBDT/CBLC, sbix, SVG ); a font may ship more than one.

pub fn svg_table(&self) -> Option<&SvgTable<'a>>

Borrow the parsed SVG table when present.

The returned [SvgTable] carries the §5.5.1 document records, each covering a contiguous glyph-ID range. Document payloads borrow from the on-wire SVG byte slice and are surfaced raw (plain UTF-8 markup or gzip-encoded — test with SvgDocument::is_gzip_encoded).

pub fn svg_document(&self, glyph_id: u16) -> Option<&SvgDocument<'a>>

Resolve the raw SVG document covering glyph_id, or None when the font has no SVG table or no document range covers the glyph. The returned SvgDocument borrows the on-wire document bytes (plain UTF-8 SVG 1.1 markup or a gzip-encoded stream per §5.5.2); inflation + XML parsing are the consumer renderer’s responsibility, matching the raw-payload policy used for sbix and CBDT image strikes.

pub fn glyph_bounding_box(&self, glyph_id: u16) -> Option<BBox>

Glyph bounding box from the glyf header (xMin/yMin/xMax/yMax). Returns None for empty / blank glyphs and for fonts that lack a glyf/loca pair (CBDT-only colour-emoji fonts).

pub fn lookup_ligature(&self, glyphs: &[u16]) -> Option<(u16, usize)>

Look up a ligature substitution for the input glyph run.

Returns Some((replacement, consumed)) if a GSUB LookupType 4 rule matches a prefix of glyphs of length consumed >= 2. Returns None otherwise (no ligature, or no GSUB table).

pub fn gsub_features_for_script( &self, script_tag: [u8; 4], lang_tag: Option<[u8; 4]>, ) -> Vec<GsubFeature>

Resolve every GSUB feature active for script_tag under lang_tag to a list of GsubFeature { tag, lookup_indices }.

lang_tag = None selects the script’s DefaultLangSys. If lang_tag is supplied but isn’t enumerated for the script, the lookup falls back to DefaultLangSys (matching the spec’s “language system not present in script → use default” rule).

The resulting Vec is empty when the font has no GSUB table or the script tag isn’t in the ScriptList. Order matches the LangSys’s featureIndices field, so a shaper can apply features in declaration order. The required feature (when present) is emitted first.

Used by the consumer crate’s Arabic shaper to discover which lookup indices implement init / medi / fina / isol for the current script — modern Arabic fonts (Noto Sans Arabic UI, most Indic fonts) ship positional forms via GSUB rather than the legacy Presentation Forms-B Unicode block.

pub fn gsub_features_for_script_at_instance( &self, script_tag: [u8; 4], lang_tag: Option<[u8; 4]>, ) -> Vec<GsubFeature>

Like Self::gsub_features_for_script, but honours the GSUB FeatureVariations table (ISO/IEC 14496-22:2019 §6.2.9) at the font’s current variation instance.

A variable font may publish a version-1.1 GSUB header that swaps the lookups behind a feature for an alternate set when the current instance falls inside a normalised range on one or more fvar axes (the canonical use is optical-size- or weight-conditional substitution). This accessor evaluates the active condition set against Self::normalised_coords and, for every feature whose index is overridden by the matching FeatureTableSubstitution, returns the alternate lookup-index list while keeping the feature tag unchanged.

For static fonts, v1.0 GSUB headers, or instances that match no condition set, the result is identical to Self::gsub_features_for_script. Set the instance with Self::set_variation_coords first.

pub fn gsub_has_feature_variations(&self) -> bool

true when the GSUB table carries a §6.2.9 FeatureVariations table (a version-1.1 header with a non-zero offset). When this is false, Self::gsub_features_for_script_at_instance is identical to Self::gsub_features_for_script.

pub fn gpos_features_for_script( &self, script_tag: [u8; 4], lang_tag: Option<[u8; 4]>, ) -> Vec<GposFeature>

Return all GPOS features active for script_tag under lang_tag, each resolved to the list of lookup indices that implement it.

The GPOS sibling of Self::gsub_features_for_script: it walks the same OpenType Layout ScriptList / FeatureList / LangSys substructure but over the positioning table, so a shaper can discover which lookup indices implement kern / mark / mkmk / curs / cpsp for the current script and feed them to the matching gpos_apply_lookup_type_* path.

lang_tag = None selects the script’s DefaultLangSys; an unrecognised lang_tag falls back to it too. The required feature (when present) is emitted first, then the LangSys’s declared features in order. Returns an empty Vec when the font has no GPOS table or the script is absent.

pub fn gpos_features_for_script_at_instance( &self, script_tag: [u8; 4], lang_tag: Option<[u8; 4]>, ) -> Vec<GposFeature>

Like Self::gpos_features_for_script, but honours the GPOS FeatureVariations table (the shared ISO/IEC 14496-22:2019 §6.2.9 substructure, reachable through a version-1.1 GPOS header) at the font’s current variation instance.

A variable font may publish a version-1.1 GPOS header that swaps the lookups behind a positioning feature for an alternate set when the current instance falls inside a normalised range on one or more fvar axes (e.g. weight-conditional kerning). This accessor evaluates the active condition set against Self::normalised_coords and, for every feature whose index is overridden by the matching FeatureTableSubstitution, returns the alternate lookup-index list while keeping the feature tag unchanged.

For static fonts, v1.0 GPOS headers, or instances that match no condition set, the result is identical to Self::gpos_features_for_script. Set the instance with Self::set_variation_coords first.

pub fn gpos_has_feature_variations(&self) -> bool

true when the GPOS table carries a §6.2.9 FeatureVariations table (a version-1.1 header with a non-zero offset). When this is false, Self::gpos_features_for_script_at_instance is identical to Self::gpos_features_for_script.

pub fn gsub_apply_lookup_type_1( &self, lookup_index: u16, gid: u16, ) -> Option<u16>

Apply GSUB LookupType 1 (Single Substitution) lookup lookup_index to a single input glyph gid.

Returns Some(replacement_gid) when the lookup’s coverage covers gid, or None when no substitution applies (caller keeps the input glyph unchanged). None is also returned when the font has no GSUB, the lookup index is out of range, or the referenced lookup isn’t a single-substitution lookup (e.g. a ligature lookup is silently skipped here — call Self::lookup_ligature for those).

Format 1 (delta) and Format 2 (substitute-array) sub-tables are both supported; ExtensionSubst (LookupType 7) wrappers are unwrapped transparently.

pub fn gsub_apply_lookup_type_4( &self, lookup_index: u16, gids: &[u16], ) -> Option<(u16, usize)>

Apply GSUB LookupType 4 (Ligature Substitution) lookup lookup_index to a prefix of gids.

Returns Some((replacement_gid, consumed)) when a sub-table in the named lookup matches a prefix of gids of length consumed (typically >= 2 for real ligatures). Returns None when no rule applies, the lookup index is out of range, the referenced lookup is not a ligature lookup, or the font has no GSUB table. ExtensionSubst (LookupType 7) wrappers are unwrapped transparently.

This is the lookup-index-specific counterpart of Self::lookup_ligature (which walks every lookup) and is the API a feature-driven shaper uses after resolving the liga / rlig / dlig feature for the active script via Self::gsub_features_for_script.

pub fn gsub_apply_lookup_type_6( &self, lookup_index: u16, gids: &[u16], pos: usize, ) -> Option<Vec<u16>>

Apply GSUB LookupType 6 (Chained Contexts Substitution) lookup lookup_index to the glyph run starting at pos.

Returns Some(rewritten_run) — a fresh Vec<u16> of the full run with any sub-lookups dispatched at the matched (backtrack, input, lookahead) window — when one of the lookup’s sub-tables (Format 1 / 2 / 3) matches around pos. Returns None when no chained-context rule applies, the lookup index is out of range, the referenced lookup is not a chain-context lookup, or the font has no GSUB table.

Each SubstLookupRecord { sequenceIndex, lookupListIndex } inside the matched rule is recursively dispatched: LookupType 1 substitutes the single glyph at the relative sequenceIndex, LookupType 4 substitutes componentCount glyphs starting there. Nested LookupType 6 references are also handled (bounded depth). ExtensionSubst (LookupType 7) is unwrapped transparently.

This is the biggest GSUB unlock for complex scripts: Arabic shaping cascades, Indic reordering, and most ligature-with- context rules (e.g. Latin ct only between word boundaries) all run through chained-context lookups.

pub fn gsub_apply_lookup_type_2( &self, lookup_index: u16, gid: u16, ) -> Option<Vec<u16>>

Apply GSUB LookupType 2 (Multiple Substitution) lookup lookup_index to a single input glyph gid.

Returns Some(substitute_sequence) — a Vec<u16> of the expanded glyph sequence — when the lookup’s coverage covers gid. Returns None when no rule applies, the lookup index is out of range, the referenced lookup is not a multiple substitution, or the font has no GSUB table. ExtensionSubst (LookupType 7) wrappers are unwrapped transparently. The spec permits glyphCount = 0 (deletion); such hits surface as Some(Vec::new()).

pub fn gsub_apply_lookup_type_3( &self, lookup_index: u16, gid: u16, alternate_index: u16, ) -> Option<u16>

Apply GSUB LookupType 3 (Alternate Substitution) lookup lookup_index to gid, picking alternate_index from the resolved AlternateSet.

Returns Some(replacement_gid) when the lookup covers gid AND alternate_index is in range for that coverage’s AlternateSet. Returns None on coverage miss, out-of-range alternate index, non-alternate-substitution referenced lookup, or a font without GSUB. Default callers should pass alternate_index = 0 — the spec doesn’t register a per-feature variant index. ExtensionSubst (LookupType 7) is unwrapped transparently.

pub fn gsub_apply_lookup_type_5( &self, lookup_index: u16, gids: &[u16], pos: usize, ) -> Option<Vec<u16>>

Apply GSUB LookupType 5 (Contextual Substitution) lookup lookup_index to the glyph run starting at pos.

LookupType 5 mirrors LookupType 6 minus backtrack and lookahead — the input window is the only context. Returns Some(rewritten_run) — a fresh Vec<u16> with any sub-lookups dispatched at the matched input window — when one of the lookup’s sub-tables (Format 1 / 2 / 3) matches around pos. Returns None when no contextual rule applies, the lookup index is out of range, the referenced lookup is not a contextual lookup, or the font has no GSUB. ExtensionSubst (LookupType 7) is unwrapped transparently. Recursive sub-lookup expansion is bounded.

pub fn gsub_apply_lookup_type_8( &self, lookup_index: u16, gids: &[u16], pos: usize, ) -> Option<u16>

Apply GSUB LookupType 8 (Reverse Chained Context Substitution) lookup lookup_index to the glyph at gids[pos].

Returns Some(replacement_gid) when the input coverage covers gids[pos] AND every backtrack / lookahead coverage matches the surrounding glyphs. Returns None otherwise (no rule, out of range, wrong lookup type, no GSUB). ExtensionSubst (LookupType 7) is unwrapped transparently.

The spec mandates reverse-text processing of the input run (essential for Arabic isolated forms in some fonts) — a higher- level shaper is what walks pos from right to left; this per-position entry point answers “does the rule fire here?”.

pub fn kern_header_variant(&self) -> Option<KernHeaderVariant>

On-disk header variant of the legacy kern table, if present.

Two header layouts coexist: Microsoft-format kern (every Windows-authored / most Adobe / Google TTF — u16 version, u16 nTables) and Apple-format kern (macOS-bundled TTFs — u32 version = 0x00010000, u32 nTables, with different per-subtable header bytes). This crate decodes Microsoft-format Format-0 horizontal kerning subtables; Apple-format tables parse cleanly but their subtable bodies surface as zero pairs (see KernHeaderVariant::Apple).

Returns None for fonts that don’t ship a kern table at all (modern OpenType fonts use GPOS LookupType 2 instead).

pub fn lookup_kerning(&self, left: u16, right: u16) -> i16

Look up the kerning between an ordered glyph pair, in font units.

Tries GPOS LookupType 2 first; falls back to the legacy kern table (format 0). Returns 0 if neither is present or the pair has no defined kerning.

pub fn lookup_mark_to_base(&self, base: u16, mark: u16) -> Option<(i16, i16)>

Look up a mark-to-base attachment offset for a (base, mark) glyph pair. Returns (dx, dy) in font units (TT Y-up convention) to add to the mark’s pen origin so its anchor lands on the base’s anchor for the mark’s class.

Walks GPOS LookupType 4 sub-tables; returns None if no matching MarkBasePos rule covers both glyphs (or if the font has no GPOS table). Used by the consumer crate’s shaper to position diacritics above / below their base glyph (essential for European Latin extended, Vietnamese, polytonic Greek).

Whether mark is actually a mark glyph (per GDEF) is the caller’s responsibility — typically the shaper checks Font::is_mark_glyph before calling this. The lookup itself works for any pair the font’s MarkBasePos coverage tables list, regardless of GDEF.

pub fn lookup_mark_to_mark(&self, mark1: u16, mark2: u16) -> Option<(i16, i16)>

Look up a mark-to-mark attachment offset for a (mark1, mark2) glyph pair, where mark1 is the previously-positioned mark (already attached to a base via a prior mark-to-base lookup) and mark2 is the mark we want to stack on top of (or below) it. Returns (dx, dy) in font units (TT Y-up convention) to add to mark2’s pen origin so its anchor lands on mark1’s anchor for mark2’s class.

Walks GPOS LookupType 6 sub-tables; returns None if no matching MarkMarkPos rule covers both glyphs (or if the font has no GPOS table). Used by the consumer crate’s shaper to build multi-mark stacks (e.g. polytonic Greek α + tonos + dialytika, Vietnamese a + circumflex + acute).

pub fn lookup_kerning_var(&self, left: u16, right: u16) -> i16

Variation-aware sibling of Self::lookup_kerning.

Resolves a GPOS pair’s xAdvance VariationIndex against the GDEF ItemVariationStore at the font’s current variation instance (set via Self::set_variation_coords), so variable kerning tracks the design axes. Falls back to the legacy kern table exactly like the static accessor. For a non-variable font, or one at its default instance, the result equals Self::lookup_kerning.

pub fn lookup_mark_to_base_var( &self, base: u16, mark: u16, ) -> Option<(i16, i16)>

Variation-aware sibling of Self::lookup_mark_to_base: resolves AnchorFormat3 VariationIndex offsets against the GDEF ItemVariationStore at the current instance so the diacritic attachment point tracks the design axes.

pub fn lookup_mark_to_mark_var( &self, mark1: u16, mark2: u16, ) -> Option<(i16, i16)>

Variation-aware sibling of Self::lookup_mark_to_mark: resolves AnchorFormat3 VariationIndex offsets against the GDEF ItemVariationStore at the current instance so the mark-on-mark stacking offset tracks the design axes.

pub fn lookup_cursive_attachment_var( &self, gid: u16, ) -> Option<CursiveAttachment>

Variation-aware sibling of Self::lookup_cursive_attachment: resolves AnchorFormat3 VariationIndex offsets on the entry / exit anchors against the GDEF ItemVariationStore at the current instance.

pub fn gpos_apply_lookup_type_1_var( &self, lookup_index: u16, gid: u16, ) -> Option<PosValue>

Variation-aware sibling of Self::gpos_apply_lookup_type_1: resolves the matched ValueRecord’s VariationIndex device offsets against the GDEF ItemVariationStore at the current instance.

pub fn ligature_carets_resolved(&self, gid: u16) -> Option<Vec<Option<i16>>>

Resolve a ligature glyph’s GDEF carets to concrete font-unit coordinates at the current variation instance (CaretValueFormat3 VariationIndex deltas applied from the GDEF ItemVariationStore; Format2 contour-point carets surface as None). Returns None when the font has no GDEF ligature-caret list covering gid. See [GdefTable::ligature_carets_resolved].

pub fn is_mark_glyph(&self, glyph_id: u16) -> bool

Is this glyph classified as a mark by the font’s GDEF table? Returns false if the font has no GDEF or the glyph isn’t enumerated. Used by the consumer crate’s shaper to decide whether to attempt mark-to-base attachment for an adjacent glyph pair.

pub fn gpos_apply_lookup_type_1( &self, lookup_index: u16, gid: u16, ) -> Option<PosValue>

Apply GPOS LookupType 1 (Single Adjustment Positioning) to gid via the lookup at lookup_index.

Returns Some(PosValue) with the four geometric adjustments (xPlacement, yPlacement, xAdvance, yAdvance) when the lookup’s coverage covers gid, or None when no rule applies (or the font has no GPOS). Both SinglePosFormat 1 (one shared ValueRecord) and Format 2 (per-glyph ValueRecord) are supported; ExtensionPos (LookupType 9) wrappers are unwrapped transparently.

Use this for features that don’t need pair context — e.g. the cpsp (capital spacing) feature applies a SinglePos to every uppercase glyph to add side bearing.

pub fn gpos_apply_lookup_type_3( &self, lookup_index: u16, gid: u16, ) -> Option<CursiveAttachment>

Apply GPOS LookupType 3 (Cursive Attachment) to gid via the lookup at lookup_index.

Returns Some(CursiveAttachment { entry, exit }) when the lookup’s coverage covers gid. Either anchor may be None (the spec allows one-sided cursive glyphs at cluster boundaries). Returns None when no rule applies, the lookup index is out of range, the referenced lookup is not a cursive lookup, or the font has no GPOS. ExtensionPos (LookupType 9) wrappers are unwrapped transparently.

Cursive attachment chains glyph N+1 onto glyph N: the shaper translates glyph N+1’s pen origin so its entry anchor lands on glyph N’s exit anchor — i.e. the per-glyph delta is prev.exit - this.entry in (x, y) font units.

pub fn lookup_cursive_attachment(&self, gid: u16) -> Option<CursiveAttachment>

Walk every GPOS LookupType-3 (Cursive Attachment) lookup looking for gid’s entry/exit anchor pair. Convenience wrapper around Self::gpos_apply_lookup_type_3 for fonts that ship a single curs lookup (the common Arabic Nastaliq case). Returns the first hit in lookup order.

pub fn gpos_apply_lookup_type_5( &self, lookup_index: u16, ligature: u16, ligature_component: u16, mark: u16, ) -> Option<(i16, i16)>

Apply GPOS LookupType 5 (Mark-to-Ligature Attachment) to the (ligature, ligature_component, mark) triple via the lookup at lookup_index.

Returns Some((dx, dy)) (font units, TT Y-up) — the offset to add to the mark’s pen origin so its class anchor lands on the selected component’s anchor. ligature_component is 0-indexed (component 0 = first component, e.g. f in fi). Returns None when no rule covers both glyphs, when the component index is out of range, or when no anchor exists for the mark’s class on the requested component. ExtensionPos (LookupType 9) wrappers are unwrapped transparently.

Closes the “fi + dot-above” gap: a mark following the second codepoint of a 2-component ligature attaches to component 1.

pub fn lookup_mark_to_ligature( &self, ligature: u16, ligature_component: u16, mark: u16, ) -> Option<(i16, i16)>

Walk every GPOS LookupType-5 (Mark-to-Ligature) lookup looking for the (ligature, ligature_component, mark) triple. Convenience wrapper around Self::gpos_apply_lookup_type_5 that scans the LookupList rather than a specific index.

pub fn lookup_mark_to_ligature_var( &self, ligature: u16, ligature_component: u16, mark: u16, ) -> Option<(i16, i16)>

Variation-aware sibling of Self::lookup_mark_to_ligature: resolves AnchorFormat3 VariationIndex offsets against the GDEF ItemVariationStore at the font’s current instance.

pub fn gpos_apply_lookup_type_7( &self, lookup_index: u16, gids: &[u16], pos: usize, ) -> Option<Vec<PosRecord>>

Apply GPOS LookupType 7 (Contextual Positioning) to the glyph run starting at pos via the lookup at lookup_index.

LookupType 7 is the non-chained sibling of LookupType 8: it matches an input glyph sequence (no backtrack / lookahead) and, on a hit, dispatches the rule’s SequenceLookupRecord[] into nested per-glyph positioning lookups. Returns Some(records) — a Vec<PosRecord> of the per-glyph adjustments emitted — when a sub-table matches the input window at pos. Each PosRecord.glyph_index is an absolute offset into gids.

All three sub-table formats (1 glyph-sequence, 2 class-based, 3 coverage-based) are supported. ExtensionPos (LookupType 9) wrappers are unwrapped transparently; nested records into LookupType 1 / 2 / 3 / 4 / 6 / 7 / 8 dispatch through the same bounded-recursion machinery as the chained path.

pub fn gpos_apply_lookup_type_8( &self, lookup_index: u16, gids: &[u16], pos: usize, ) -> Option<Vec<PosRecord>>

Apply GPOS LookupType 8 (Chained Contexts Positioning) to the glyph run starting at pos via the lookup at lookup_index.

Returns Some(records) — a Vec<PosRecord> listing every per-glyph adjustment the matched chain rule emits — when one of the lookup’s sub-tables matches the (backtrack, input, lookahead) window around pos. Each PosRecord.glyph_index is an absolute offset into gids.

All three sub-table formats (1 glyph-sequence, 2 class-based, 3 coverage-based) are supported. ExtensionPos (LookupType 9) wrappers are unwrapped transparently. Nested PosLookupRecord references into LookupType 1 / 2 / 4 / 6 / 8 dispatch through the same machinery; recursion is bounded.

pub fn gpos_lookup_list(&self) -> Vec<(u16, u16, u16)>

Enumerate every GPOS lookup as (lookup_index, lookup_type, subtable_count).

The reported lookup_type is the effective type after unwrapping any LookupType-9 ExtensionPos wrapper. Returns an empty iterator when the font has no GPOS table.

Use this to find every chained-context positioning lookup, or every mark-to-ligature lookup, etc., without probing each index in turn — for example, font.gpos_lookup_list().filter(|(_, t, _)| *t == 8) enumerates the chained-context-positioning lookups.

pub fn gsub_lookup_list(&self) -> Vec<(u16, u16, u16)>

Enumerate every GSUB lookup as (lookup_index, lookup_type, subtable_count). Same shape as Self::gpos_lookup_list — the reported lookup_type is post-unwrap of any LookupType-7 ExtensionSubst wrapper.

pub fn gsub_lookup_flags(&self, lookup_index: u16) -> u16

The lookupFlag of GSUB lookup lookup_index (0 when there’s no GSUB or the index is out of range). The low-byte skip bits — RIGHT_TO_LEFT 0x0001, IGNORE_BASE_GLYPHS 0x0002, IGNORE_LIGATURES 0x0004, IGNORE_MARKS 0x0008, USE_MARK_FILTERING_SET 0x0010 — control which glyphs a shaper skips when matching the lookup’s input; the high byte is the markAttachmentType class. Self::shape honours these.

pub fn gpos_lookup_flags(&self, lookup_index: u16) -> u16

The lookupFlag of GPOS lookup lookup_index (0 when there’s no GPOS or the index is out of range). Same bit layout as Self::gsub_lookup_flags.

pub fn gsub_lookup_mark_filtering_set(&self, lookup_index: u16) -> Option<u16>

The markFilteringSet index of GSUB lookup lookup_index, or None when the lookup does not carry USE_MARK_FILTERING_SET (0x0010). When present, the value indexes the GDEF MarkGlyphSets structure and the layout engine skips every mark glyph not in that set (Self::shape honours this through the shared skip predicate).

pub fn gpos_lookup_mark_filtering_set(&self, lookup_index: u16) -> Option<u16>

The markFilteringSet index of GPOS lookup lookup_index, or None when the lookup does not carry USE_MARK_FILTERING_SET. See Self::gsub_lookup_mark_filtering_set.

pub fn lookup_skips_glyph( &self, flags: u16, mark_filtering_set: Option<u16>, glyph_id: u16, ) -> bool

The shared §2 (“Common Table Formats”) lookup skip predicate: returns true when a lookup with flags (its lookupFlag) and the optional mark_filtering_set index must skip glyph_id while matching its input / backtrack / lookahead sequences.

The rule, per the LookupFlag bit enumeration:

• IGNORE_BASE_GLYPHS (0x0002) — skip glyphs whose GDEF GlyphClassDef class is base (1).
• IGNORE_LIGATURES (0x0004) — skip glyphs whose class is ligature (2).
• IGNORE_MARKS (0x0008) — skip every mark glyph (class 3).
• MARK_ATTACHMENT_CLASS_FILTER (high byte 0xFF00, non-zero) — skip every mark glyph whose GDEF MarkAttachClassDef class is not the specified class. Non-mark glyphs are unaffected.
• USE_MARK_FILTERING_SET (0x0010) — skip every mark glyph that is not a member of the GDEF mark glyph set named by mark_filtering_set.

IGNORE_MARKS subsumes both mark-specific filters (a lookup that already skips all marks ignores the mark-class / filtering-set qualifiers). With no GDEF table the predicate degenerates to “never skip”, matching the §2 requirement that a GlyphClassDef table be present whenever a skip bit is set.

pub fn has_color_bitmaps(&self) -> bool

true if this font ships a CBDT/CBLC pair — i.e. carries embedded colour bitmap glyphs (Noto Color Emoji, Apple Color Emoji’s Google-format counterparts, and most Android emoji fonts). Returns false for plain outline-only fonts.

pub fn color_strike_sizes(&self) -> Vec<(u8, u8)>

All (ppem_x, ppem_y) strikes the colour-bitmap tables ship. Returns an empty iterator when the font lacks CBDT/CBLC. Useful for picking a strike before calling Font::glyph_color_bitmap.

pub fn glyph_color_bitmap( &self, glyph_id: u16, target_ppem: u8, ) -> Option<ColorBitmap<'a>>

Resolve glyph_id’s colour bitmap at the strike whose ppem_y is closest to target_ppem. Returns None if the font has no CBDT/CBLC tables OR no strike contains glyph_id OR the strike’s per-glyph entry is in a CBDT format we don’t decode (anything other than 17/18/19 — the three PNG-payload formats).

On success returns a ColorBitmap with raw png_bytes ready to feed into oxideav-png in the consumer crate. We deliberately don’t decode the PNG here so this crate stays dependency-light.

pub fn has_gray_bitmaps(&self) -> bool

true if this font ships an EBDT/EBLC pair — i.e. carries embedded monochrome or grayscale bitmap glyphs (legacy pixel / CJK bitmap faces, hand-hinted small-size strikes). Returns false for outline-only and colour-bitmap-only fonts.

pub fn gray_strike_sizes(&self) -> Vec<(u8, u8)>

All (ppem_x, ppem_y) strikes the monochrome / grayscale bitmap tables ship, in declaration order. Empty when the font lacks EBDT/EBLC. Useful for picking a strike before calling Font::glyph_gray_bitmap.

pub fn glyph_gray_bitmap( &self, glyph_id: u16, target_ppem: u8, ) -> Option<GrayBitmap>

Resolve glyph_id’s monochrome / grayscale bitmap at the strike whose ppem_y is closest to target_ppem. Returns None if the font has no EBDT/EBLC tables OR no strike contains glyph_id OR the strike’s per-glyph entry is in an EBDT format we don’t decode (format 4 compressed).

Composite formats 8 / 9 (§5.6.2.2.8 / §5.6.2.2.9) are decoded: the composite’s component glyphs are resolved out of the same strike and blitted onto the composite’s canvas at their per-component (xOffset, yOffset) offsets (nested composites are followed up to a bounded depth). The returned GrayBitmap is the assembled image.

On success returns a GrayBitmap whose pixels field is an unpacked width * height row-major grid of alpha coverage (0x00 = transparent, 0xFF = opaque), ready to blit as a glyph mask at (bearing_x, bearing_y). Bit depths 1 / 2 / 4 / 8 are all expanded to the full 0..=255 range (§5.6.2.2 / §5.6.3.1).

pub fn has_ebsc(&self) -> bool

true if this font ships an EBSC table (ISO/IEC 14496-22:2019 §5.6.4) — i.e. declares one or more synthesised bitmap strikes built by scaling a real EBLC/EBDT strike. Returns false for fonts without EBSC, including the common case of a font that has real embedded bitmaps but never scales them.

pub fn ebsc_table(&self) -> Option<&EbscTable>

The parsed EBSC table, for tooling that wants to introspect the BitmapScale records directly (target / substitute ppem pairs and the per-strike line metrics).

pub fn ebsc_target_sizes(&self) -> Vec<(u8, u8)>

All target (ppemX, ppemY) sizes the EBSC table can synthesise by scaling, in declaration order. These are sizes at which a rasteriser can obtain a bitmap without a real strike existing at that ppem — Font::glyph_gray_bitmap_scaled resolves them. Empty when the font has no EBSC.

pub fn glyph_gray_bitmap_scaled( &self, glyph_id: u16, target_ppem: u8, ) -> Option<GrayBitmap>

Resolve glyph_id at an EBSC-synthesised strike whose target ppemY equals target_ppem, returning a GrayBitmap whose pixel grid is the real substitute strike’s imagery with the per-glyph metrics (width, height, bearings, advance) scaled by the target / substitute ppem ratio and rounded to the nearest integer pixel per §5.6.4. The ppem field of the returned bitmap is set to the synthesised target so the caller knows the intended display size.

The pixel buffer itself is not resampled here — §5.6.4 leaves the actual scaling to the rasteriser (“a font to define a bitmap strike as a scaled version of another strike”); this method performs the table-level redirection and the metric scaling the spec mandates, and hands the source pixels through so the consumer crate can resample at its chosen filter quality. The reported width / height are the scaled dimensions the resampled grid should target.

Returns None when the font has no EBSC, no BitmapScale record targets target_ppem, no real strike exists at the record’s substitutePpemY, the substitute strike lacks glyph_id, or the substitute entry is in an undecoded EBDT format.

pub fn has_color_layers(&self) -> bool

true if this font ships a COLR + CPAL pair — i.e. carries vector colour-emoji glyphs as a per-glyph layer stack (Microsoft’s Segoe UI Emoji, Twemoji’s Mozilla cut, FiraCode’s “color” variant, and so on). Returns false for plain outline-only fonts and for CBDT-only colour-emoji fonts.

Both COLR versions are decoded: the v0 flat layer stack through Font::color_layers, and the v1 paint graph through Font::color_paint_root / Font::color_paint. The spec prefers a v1 paint graph over a v0 layer stack for the same base glyph, so check Font::color_paint_root first when Font::has_colr_v1 is set.

pub fn color_layers(&self, glyph_id: u16) -> Vec<ColorLayer>

All colour layers for glyph_id, in back-to-front paint order. Each layer carries an outline-glyph id (whose outline you fetch via Font::glyph_outline) and a CPAL palette-entry index. The reserved palette index 0xFFFF means “use the renderer’s foreground colour” — substitute your own.

Returns an empty Vec when the font has no COLR table or glyph_id isn’t a base glyph (i.e. it’s a single-colour outline glyph or a layer-only glyph used by other bases).

pub fn has_colr_v1(&self) -> bool

true if this font’s COLR table carries a version-1 BaseGlyphList — i.e. at least one glyph is defined as a paint graph (gradients / transforms / composites) rather than, or in addition to, a v0 flat layer stack.

pub fn color_paint_root(&self, glyph_id: u16) -> Option<PaintRef>

Resolve glyph_id to the root PaintRef of its COLR v1 colour-glyph graph (a binary search over the BaseGlyphList). None when the font has no v1 COLR data or the glyph has no paint record — fall back to Font::color_layers then, per the spec’s v1-over-v0 preference order.

pub fn color_paint(&self, paint: PaintRef) -> Option<Paint>

Decode one Paint node of a COLR v1 graph at the current variation instance (set with Font::set_variation_coords / Font::set_axis_value; static fonts and the default instance resolve identically). Every PaintVar* wire form folds its deltas into the same resolved Paint variant as its static twin.

Child paints are surfaced as further PaintRefs: the caller owns traversal and must bound depth / track visited refs — the spec requires the graph to be acyclic, but a hostile font can tie a loop (e.g. through PaintColrGlyph).

Returns None for an unrecognised paint format (the spec’s forward-compatibility rule is to ignore it) or a malformed node.

pub fn color_paint_format(&self, paint: PaintRef) -> Option<u8>

The raw wire format byte of the Paint table at paint — distinguishes e.g. the four scale wire forms that Font::color_paint folds into Paint::Scale, and a PaintVar* from its static twin.

pub fn color_clip_box(&self, glyph_id: u16) -> Option<ClipBox>

The precomputed COLR v1 clip box covering glyph_id, resolved at the current variation instance. Variable clip boxes (ClipBoxFormat 2) round outward per the spec so the box only ever expands. None when the font has no ClipList or no clip record covers the glyph — compute the bound from the graph then.

pub fn colr_var_index_map_unsupported(&self) -> bool

true when the COLR table ships a varIndexMap that does not decode — an unrecognised future format byte, reserved entryFormat bits, or a truncated map. Both defined DeltaSetIndexMap formats (0 and 1, per the staged OFF common-formats chapter) decode, so this only fires on malformed or future-format maps: the paint graph still decodes but every variation delta resolves to 0 (default-instance values).

pub fn color_glyph_is_bounded(&self, glyph_id: u16) -> Option<bool>

Whether the COLR v1 colour glyph rooted at glyph_id is bounded — a well-formedness requirement (staged reference §9: “A version-1 color glyph definition must be bounded”; PaintGlyph is inherently bounded and PaintComposite follows the per-mode §6 table). Some(false) = the graph decodes but paints an unbounded region; None = not well-formed (no paint record, an undecodable node, a cycle, or an adversarial graph that exhausts the bounded analysis budget). Renderers should refuse Some(false) / None glyphs or clip them to Font::color_clip_box.

pub fn colr_effective_color( &self, palette_index: u16, entry_index: u16, alpha: f32, ) -> Option<[u8; 4]>

Resolve a COLR colour reference — a (palette entry, alpha) pair from a Paint::Solid or a tables::colr::ColorStop — against CPAL palette palette_index, applying the spec’s alpha-multiplication rule: the COLR alpha (clamped to [0, 1]) scales the CPAL entry’s own alpha channel. RGB channels pass through untouched.

Returns None for the 0xFFFF “text foreground” sentinel (the caller substitutes its own foreground colour and applies alpha to it), for a missing CPAL table, or for an out-of-range index.

pub fn cpal_color( &self, palette_index: u16, color_index: u16, ) -> Option<[u8; 4]>

Resolve a single CPAL colour by (palette_index, color_index). Returns [r, g, b, a] (the byte order swizzled out of CPAL’s on-disk BGRA) or None when either index is out of range or the font has no CPAL table.

Palette 0 is the spec’s “default” palette. CPAL v1’s palette flags (USABLE_WITH_LIGHT_BACKGROUND, USABLE_WITH_DARK_BACKGROUND) are exposed via Font::cpal_palette_type for renderers that want to pick a theme-appropriate palette.

pub fn cpal_palette(&self, palette_index: u16) -> Option<Vec<[u8; 4]>>

All colours for palette palette_index as an Vec<[u8; 4]> (RGBA byte order). None if the font has no CPAL table or palette_index is out of range.

pub fn cpal_num_palettes(&self) -> u16

Number of CPAL palettes the font ships, or 0 if there’s no CPAL table. Mostly useful for renderers that pick a palette based on cpal_palette_type flags.

pub fn cpal_palette_type(&self, palette_index: u16) -> u32

CPAL v1 palette-type flags for palette_index. Returns 0 when the font has no CPAL table, the table is v0, or the palette index is out of range.

Bit 0 (0x0001) = USABLE_WITH_LIGHT_BACKGROUND Bit 1 (0x0002) = USABLE_WITH_DARK_BACKGROUND

pub fn cpal_palette_label(&self, palette_index: u16) -> Option<u16>

CPAL v1 palette label: the name table ID of a UI string naming palette palette_index (e.g. “Regular”, “High Contrast”). Returns None when the font has no CPAL table, the table is v0, the paletteLabelArray is absent, the palette index is out of range, or the slot holds the 0xFFFF “no label” sentinel. Pass the returned ID to a name-table lookup to fetch the localized string.

pub fn cpal_palette_entry_label(&self, entry_index: u16) -> Option<u16>

CPAL v1 palette-entry label: the name table ID of a UI string naming palette entry entry_index (e.g. “Outline”, “Fill”). The label applies uniformly across every palette in the font. Returns None when the font has no CPAL table, the table is v0, the paletteEntryLabelArray is absent, the entry index is out of range, or the slot holds the 0xFFFF “no label” sentinel.

pub fn has_sbix(&self) -> bool

true if this font ships an sbix table — Apple’s PNG/JPEG/ TIFF bitmap-strike container, used by Apple Color Emoji and every macOS/iOS-native colour-emoji font. Returns false for outline-only fonts and for CBDT/CBLC- or COLR/CPAL-flavoured colour fonts.

pub fn sbix_strikes(&self) -> Vec<u16>

All strike ppem sizes the sbix table ships, sorted ascending and de-duplicated. Apple Color Emoji typically lists eight strikes in the 20-160 ppem range. Returns an empty Vec when the font has no sbix table.

pub fn sbix_glyph(&self, glyph_id: u16, ppem: u16) -> Option<SbixGlyph<'a>>

Resolve glyph_id’s sbix bitmap from the strike whose ppem is closest to the requested ppem (ties favour the larger strike, per the spec recommendation). Returns None if the font has no sbix table OR no strike contains a bitmap for glyph_id.

SbixGlyph::graphic_type is one of *b"png ", *b"jpg ", *b"tiff", or *b"dupe" — the consumer crate is expected to route the payload to the right decoder. The special 'dupe' value indicates a 2-byte big-endian glyph id whose bitmap should be substituted; this method surfaces the indirection sentinel as-is for byte-level introspection. Use Self::sbix_glyph_resolved when the caller wants the indirection chased for them.

pub fn sbix_glyph_resolved( &self, glyph_id: u16, ppem: u16, ) -> Option<SbixGlyph<'a>>

Like Self::sbix_glyph, but chases 'dupe' indirections within the chosen strike — up to SBIX_MAX_DUPE_DEPTH hops — with explicit cycle detection. Returns the first reachable non-'dupe' entry, or None if the chain cycles, exceeds the hop cap, or hits a malformed / out-of-range target. Callers that need to introspect the raw 'dupe' sentinel keep using Self::sbix_glyph.

pub fn is_variable(&self) -> bool

true if the font ships an fvar table — i.e. it exposes one or more variation axes. Returns false for static fonts.

pub fn variation_axes(&self) -> &[VariationAxis]

All variation axes the font publishes (fvar), in declaration order. Returns an empty slice for static fonts.

pub fn named_instances(&self) -> &[NamedInstance]

All named instances the font ships (fvar), in declaration order. Each carries a coordinate vector matching Self::variation_axes (one f32 per axis) plus a name table id for the human-readable subfamily label.

pub fn variation_coords(&self) -> &[f32]

Current user-space variation coordinates (one entry per axis, in fvar declaration order). Empty slice for static fonts. Defaults to each axis’s default value at parse time; updated by Self::set_variation_coords.

pub fn set_variation_coords(&mut self, coords: &[f32])

Replace the current variation coordinates. Each entry is in user-space units (e.g. wght is 100..900). The vector must be the same length as Self::variation_axes; shorter vectors leave the trailing axes at their previous value, longer vectors are truncated. Out-of-range values are clamped to each axis’s [min, max].

No-op when the font is static (is_variable() == false).

pub fn axis_index(&self, tag: &[u8; 4]) -> Option<usize>

Index of the axis carrying the four-byte tag (e.g. *b"wght"), or None when the font has no such axis (or is static).

pub fn axis_value(&self, tag: &[u8; 4]) -> Option<f32>

Current user-space value of the axis with the four-byte tag, or None when the font has no such axis.

pub fn set_axis_value(&mut self, tag: &[u8; 4], value: f32) -> bool

Set a single variation axis (identified by its four-byte tag, e.g. *b"wght" / *b"wdth" / *b"slnt" / *b"opsz" / *b"ital") to a user-space value, leaving every other axis at its current value. The value is clamped to the axis’s [min, max] range, like Self::set_variation_coords.

Returns true when the axis was found and updated, false for a static font or an unknown tag (in which case nothing changes).

pub fn apply_named_instance(&mut self, index: usize) -> bool

Set the variation coordinates to the named instance at index (its position in Self::named_instances). After this call the font renders/shapes as that designer-chosen design variant (e.g. “Bold”, “Condensed Light”).

Each named-instance coordinate is clamped to its axis range, like Self::set_variation_coords. Instances whose stored coordinate vector is shorter than the axis count leave the trailing axes at their current value; longer vectors are truncated.

Returns true when the instance existed and was applied, false for a static font or an out-of-range index.

pub fn normalised_coords(&self) -> Vec<f32>

Compute the normalised coordinate vector (each entry in [-1, +1]) by mapping each user-space value through the fvar axis triple, then through the avar per-axis remap. Returns an empty vec for static fonts.

pub fn avar_axis_index_map_unsupported(&self) -> bool

true when the font’s avar table is version 2 and ships an axisIndexMap that does not decode — an unrecognised future format byte, reserved entryFormat bits, or a truncated map. Both defined DeltaSetIndexMap formats (0 and 1, per the staged OFF common-formats chapter) decode, so this only fires on malformed or future-format maps: the cross-axis delta stage is skipped for the whole table (the v1 segment maps still apply).

pub fn cvt_count(&self) -> u16

Number of entries in the cvt Control Value Table, or 0 when the font has no cvt table. Each entry is an int16 FWORD (ISO/IEC 14496-22:2019 §5.3.2); the count is the table length divided by two (a trailing odd byte, if any, is ignored).

pub fn cvt_value(&self, index: u16) -> Option<i16>

The static (un-varied) value of cvt entry index, or None when the font has no cvt table or index is out of range. This is the raw FWORD as authored, before any cvar instance delta is applied — see Self::cvt_value_varied.

pub fn has_cvar(&self) -> bool

true if the font ships a cvar CVT-variations table.

pub fn cvar_table(&self) -> Option<&CvarTable<'a>>

Borrow the parsed cvar table, when present.

pub fn cvt_deltas(&self) -> Vec<i32>

Per-cvt-entry deltas for the current variation instance, computed against the avar-bent normalised coordinate vector (ISO/IEC 14496-22:2019 §7.3.2). Returns a Vec<i32> of length Self::cvt_count; every entry is 0 for a static font, a font without cvar, or the default instance. Index i is the delta to add to cvt entry i.

pub fn cvt_value_varied(&self, index: u16) -> Option<i16>

The cvt entry index with the current instance’s cvar delta applied (saturating to the i16 FWORD range), or None when the font has no cvt table or index is out of range. For a static font or the default instance this equals Self::cvt_value.

pub fn fpgm_program(&self) -> Option<&'a [u8]>

The raw fpgm font-program bytes (TrueType bytecode run once when the font is first used, ISO/IEC 14496-22:2019 §5.3.3), or None when the font ships no fpgm table.

This crate does not execute the bytecode (TrueType hinting is out of scope — modern anti-aliasing at typical sizes does not need it). The bytes are surfaced for tooling that introspects, edits, or round-trips the hinting program, and for a downstream interpreter.

pub fn prep_program(&self) -> Option<&'a [u8]>

The raw prep control-value-program bytes (TrueType bytecode run whenever the point size / font / transform changes, ISO/IEC 14496-22:2019 §5.3.x), or None when absent. Like fpgm, surfaced raw and not executed.

pub fn has_hinting_program(&self) -> bool

true if the font carries any TrueType hinting program (fpgm, prep, or a non-empty cvt ). A purely outline-driven font with no hinting returns false. Note the bytecode is surfaced raw, never executed.

pub fn mvar_table(&self) -> Option<&MvarTable>

Borrow the parsed MVAR table, when present. Static fonts and variable fonts that omit MVAR return None.

pub fn metric_variation_delta(&self, tag: &[u8; 4]) -> Option<f32>

Interpolated MVAR adjustment for a four-byte metric tag (e.g. *b"xhgt", *b"cpht", *b"hasc") at the current variation coordinates.

Per ISO/IEC 14496-22:2019 §7.3.6.2, the adjustment is computed against the current normalised coordinate vector (i.e. after the avar remap, see Self::normalised_coords). The returned value is a delta to be added to the corresponding field in OS/2 / hhea / vhea / post / gasp.

Returns None when:

• the font lacks an MVAR table, or
• the requested tag is not present in MVAR’s value-record array (the spec’s “if the tag does not occur, the item is constant across the variation space” rule).

Returns Some(0.0) when the variation evaluates to zero at the current instance (e.g. at the axis defaults).

pub fn hvar_table(&self) -> Option<&HvarTable>

Borrow the parsed HVAR table, when present.

pub fn advance_width_variation_delta(&self, glyph_id: u16) -> Option<f32>

Interpolated HVAR adjustment to the advance width of glyph_id at the current variation coordinates.

Per ISO/IEC 14496-22:2019 §7.3.5.3, the application reads the default advance width from hmtx and adds this delta to derive the per-instance advance. When an advanceWidthMapping table is published, that map provides the (outer, inner) index pair; otherwise the glyph ID itself acts as the inner index and the outer index is zero (the implicit form).

Returns None when the font lacks HVAR or when the resolved index pair is out of range for the embedded item variation store. Returns Some(0.0) when the variation evaluates to zero at the current instance (e.g. at the axis defaults).

pub fn lsb_variation_delta(&self, glyph_id: u16) -> Option<f32>

Interpolated HVAR adjustment to the left side bearing of glyph_id. Requires that the font ship a left-side-bearing mapping table (§7.3.5.2 says LSB / RSB lookups always need one); returns None otherwise.

pub fn rsb_variation_delta(&self, glyph_id: u16) -> Option<f32>

Interpolated HVAR adjustment to the right side bearing of glyph_id. Requires a right-side-bearing mapping table per §7.3.5.2; returns None otherwise.

pub fn glyph_advance_varied(&self, glyph_id: u16) -> i16

Per-glyph advance width at the current variation instance: the static hmtx advance (see Self::glyph_advance) plus the HVAR delta (§7.3.5.3), rounded to the nearest font unit. For a static font, a font without HVAR, or the default instance this equals Self::glyph_advance. The result is clamped to the i32 range only in pathological inputs; advances are unsigned in hmtx but the fused value is returned signed for symmetry with Self::glyph_advance.

pub fn glyph_lsb_varied(&self, glyph_id: u16) -> i16

Per-glyph left-side bearing at the current variation instance: the static hmtx LSB (see Self::glyph_lsb) plus the HVAR LSB delta (§7.3.5.2), rounded to the nearest font unit. Equals Self::glyph_lsb for a static font, a font without an HVAR LSB mapping, or the default instance.

pub fn vvar_table(&self) -> Option<&VvarTable>

Borrow the parsed VVAR table, when present.

pub fn advance_height_variation_delta(&self, glyph_id: u16) -> Option<f32>

Interpolated VVAR adjustment to the advance height of glyph_id at the current variation coordinates.

Per ISO/IEC 14496-22:2019 §7.3.8.2 (cross-referenced back to §7.3.5.3), the application reads the default advance height from vmtx and adds this delta to derive the per-instance advance. When an advanceHeightMapping table is published, that map provides the (outer, inner) index pair; otherwise the glyph ID itself acts as the inner index and the outer index is zero (the implicit form).

Returns None when the font lacks VVAR or when the resolved index pair is out of range for the embedded item variation store. Returns Some(0.0) when the variation evaluates to zero at the current instance (e.g. at the axis defaults).

pub fn tsb_variation_delta(&self, glyph_id: u16) -> Option<f32>

Interpolated VVAR adjustment to the top side bearing of glyph_id. Requires that the font ship a top-side-bearing mapping table (§7.3.8.2 inherits the §7.3.5.2 rule that side- bearing lookups always need a map); returns None otherwise.

pub fn bsb_variation_delta(&self, glyph_id: u16) -> Option<f32>

Interpolated VVAR adjustment to the bottom side bearing of glyph_id. Requires a bottom-side-bearing mapping table per §7.3.8.2; returns None otherwise.

pub fn glyph_advance_height_varied(&self, glyph_id: u16) -> Option<u16>

Per-glyph advance height at the current variation instance: the static vmtx advance height (see Self::glyph_advance_height) plus the VVAR advance-height delta (§7.3.8.2), rounded to the nearest font unit. Returns None when the font lacks vhea/vmtx. Equals Self::glyph_advance_height for a font without VVAR or at the default instance.

pub fn vorg_variation_delta(&self, glyph_id: u16) -> Option<f32>

Interpolated VVAR adjustment to the vertical-origin Y of glyph_id. §7.3.8.2 final paragraph: a mapping table is required for vertical-origin variation data, and the data is “not used in fonts with TrueType outlines” — populated only by CFF2 variable fonts that publish a VORG table. Returns None otherwise.

pub fn stat_table(&self) -> Option<&StatTable>

Borrow the parsed STAT table, when present. Static fonts may omit it; variable fonts are required by ISO/IEC 14496-22:2019 §7.3.7 to ship one.

pub fn stat_axes(&self) -> &[StatAxisRecord]

STAT.designAxes — one record per design axis. For a variable font, every fvar axis must appear here; the order is arbitrary (sort by axis_ordering if a stable UI order is needed). Returns an empty slice when no STAT table is present.

pub fn stat_axis_values(&self) -> &[StatAxisValue]

STAT.axisValueTables — every axis value record in document order. Filter by axis tag with Self::stat_axis_values_for_tag or walk by format to compose subfamily strings under the R/B/I/BI, WWS, or unrestricted naming models (§7.3.7.3). Returns an empty slice when no STAT table is present.

pub fn stat_elided_fallback_name_id(&self) -> Option<u16>

STAT.elidedFallbackNameID — the name table nameID applied when every component of a composed subfamily string would be elided (§7.3.7.1). Returns None when the font ships no STAT table; returns name ID 2 (“Regular”) for the deprecated v1.0 header that lacked the field.

pub fn stat_axis_values_for_tag( &self, axis_tag: [u8; 4], ) -> Box<dyn Iterator<Item = &StatAxisValue> + '_>

Every STAT axis-value record whose axis is axis_tag (e.g. *b"wght", *b"wdth"). Format-4 records are matched when one of their contributing axes references this tag. Returns an empty iterator when the font has no STAT table or the tag is not in the design-axes array.

Trait Implementations

impl<'a> Debug for Font<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.