#font API reference

A pure-Jennifer TrueType / OpenType (SFNT) font parser: read a .ttf / .otf from bytes and expose its metrics, character map, and glyph outlines. No Go, no dependency - just the bytes type and the bitwise operators for the big-endian tables - so it runs on both binaries.

Both outline backends ship: the TrueType glyf backend (simple and composite glyphs, quadratic curves) and the CFF / PostScript backend for OpenType OTTO fonts (a Type2 charstring interpreter with global / local subroutines and CID-keyed FDArray / FDSelect, so CJK fonts outline too), detected on parse; a CFF glyph's cubic curves render as native C segments in glyphPath and are approximated as quadratics in the Glyph struct. It parses the core tables - head, cmap (formats 4 and 12), maxp / hhea / hmtx, OS/2 (vertical metrics), the legacy kern table, loca / glyf or CFF , and name.

Import with import "font.j" as font;. See the font guide for prose and examples.

#Functions

#font.advance(f as Font, cp as int)

The horizontal advance width of the glyph for a codepoint, in font units.

Parameters

• f {Font} - the font
• cp {int} - the Unicode codepoint

Returns {int} - the advance width

#font.advanceGid(f as Font, gid as int)

The horizontal advance width of a glyph id, in font units (the raw hmtx metric, for building a PDF W widths array keyed by glyph / CID).

Parameters

• f {Font} - the font
• gid {int} - the glyph id

Returns {int} - the advance width

#font.advances(f as Font, gids as list of int)

Batch advance-width lookup: the advances (font units) for a list of glyph ids, in one call. Prefer this over advanceGid per glyph (see glyphIds).

Parameters

• f {Font} - the font
• gids {list of int} - the glyph ids

Returns {list of int} - the advance widths, in order

#font.ascender(f as Font)

The typographic ascender in font units (OS/2 sTypoAscender, else the hhea ascent). The distance from the baseline to the top of the em box.

Parameters

• f {Font} - the font

Returns {int} - the ascender

#font.bbox(f as Font)

The font bounding box in font units as [xMin, yMin, xMax, yMax] (the head table's global glyph bounds, for a PDF FontBBox).

Parameters

• f {Font} - the font

Returns {list of int} - [xMin, yMin, xMax, yMax]

#font.capHeight(f as Font)

The capital height in font units (OS/2 sCapHeight): the height of a flat capital such as H. 0 when the font has no OS/2 v2+ table.

Parameters

• f {Font} - the font

Returns {int} - the cap height, or 0 when unavailable

#font.data(f as Font)

The raw font file bytes (for embedding the font in a container such as a PDF FontFile2).

Parameters

• f {Font} - the font

Returns {bytes} - the font file contents

#font.descender(f as Font)

The typographic descender in font units (OS/2 sTypoDescender, else hhea). Conventionally negative (below the baseline).

Parameters

• f {Font} - the font

Returns {int} - the descender

#font.glyph(f as Font, cp as int)

The full outline of the glyph for a codepoint: its contours (on / off-curve points), advance, and bounding box. A codepoint the font lacks maps to glyph 0 (.notdef).

Parameters

• f {Font} - the font
• cp {int} - the Unicode codepoint

Returns {Glyph} - the glyph outline

#font.glyphId(f as Font, cp as int)

The glyph id (index) a codepoint maps to through the font's character map, or 0 (.notdef) when the font lacks the codepoint. The identifier a PDF embeds under Identity encoding.

Parameters

• f {Font} - the font
• cp {int} - the Unicode codepoint

Returns {int} - the glyph id

#font.glyphIds(f as Font, cps as list of int)

Batch glyph-id lookup: map a list of codepoints to their glyph ids in one call. Prefer this over calling glyphId per character - the font is value-semantic (its raw bytes are copied on every call), so a per-character loop copies the whole font each time; this copies it once for the whole batch.

Parameters

• f {Font} - the font
• cps {list of int} - the codepoints

Returns {list of int} - the glyph ids, in order

#font.glyphPath(f as Font, cp as int)

The glyph outline for a codepoint as an SVG path d string, in font-unit coordinates (y-up, as fonts store them - flip y for screen rendering). Quadratic segments render as Q commands. An empty glyph yields "".

Parameters

• f {Font} - the font
• cp {int} - the Unicode codepoint

Returns {string} - the SVG path data

#font.isCff(f as Font)

Whether the font uses CFF / PostScript outlines (an OpenType OTTO) rather than TrueType glyf outlines.

Parameters

• f {Font} - the font

Returns {bool} - true for a CFF font

#font.kern(f as Font, left as int, right as int)

The kerning adjustment between two codepoints in font units (negative pulls them closer). Reads the legacy kern table (version 0, horizontal format-0 subtables); 0 when the font has no kern table or no pair entry. Modern fonts carry kerning in GPOS instead, which this does not read.

Parameters

• f {Font} - the font
• left {int} - the left codepoint
• right {int} - the right codepoint

Returns {int} - the kerning adjustment, or 0

#font.lineGap(f as Font)

The typographic line gap in font units (OS/2 sTypoLineGap, else hhea): the recommended extra leading between lines. Line height = ascender - descender + lineGap.

Parameters

• f {Font} - the font

Returns {int} - the line gap

#font.name(f as Font)

The font family name.

Parameters

• f {Font} - the font

Returns {string} - the family name

#font.numGlyphs(f as Font)

The number of glyphs in the font.

Parameters

• f {Font} - the font

Returns {int} - the glyph count

#font.open(path as string)

Load and parse a font from a file path.

Parameters

• path {string} - the .ttf file path

Returns {Font} - the parsed font

Throws

• {Error} - on a read or parse error

#font.parse(b as bytes)

Parse a TrueType / OpenType (SFNT) font from its bytes - a glyf (TrueType) or CFF (OpenType/PostScript) outline font.

Parameters

• b {bytes} - the font file contents

Returns {Font} - the parsed font

Throws

• {Error} - on a malformed font or an unrecognised container

#font.unitsPerEm(f as Font)

The font's units-per-em (the coordinate scale of every outline / metric).

Parameters

• f {Font} - the font

Returns {int} - units per em

#font.xHeight(f as Font)

The x-height in font units (OS/2 sxHeight): the height of a lowercase x. 0 when the font has no OS/2 v2+ table.

Parameters

• f {Font} - the font

Returns {int} - the x-height, or 0 when unavailable

#Structs

#font.Contour

One closed contour of a glyph: its ordered points.

#font.Font

A parsed font. Holds the raw bytes plus the table offsets and header values needed to answer metric / cmap / outline queries; glyph outlines are decoded on demand.

#font.Glyph

A glyph outline: its contours, advance width, and bounding box, all in font units. An empty glyph (e.g. a space) has no contours.

#font.Point

A point in a glyph contour, in font-unit coordinates.