Skip to content
canvas
text
ttf
TTFFace

TTFFace

Mojo struct 🡭

TTFFace

@memory_only
struct TTFFace

A parsed TrueType font file: the raw file bytes plus the table offsets and global metrics this module reads.

Fields

  • data (List[UInt8])
  • units_per_em (Int)
  • num_glyphs (Int)
  • index_to_loc_format (Int)
  • ascender (Int)
  • descender (Int)
  • line_gap (Int)
  • num_h_metrics (Int)

Implemented traits

AnyType, Deinitable, Movable

Methods

__init__ 

fn def __init__(out self, path: String)

Parse a TrueType (glyf-outline) font file.

Args:

  • path (String): Path to a .ttf file.
  • self (Self)

Returns:

Self

Raises:

Error: path can’t be read, isn’t a TrueType font (a CFF/OpenType-CFF .otf included), or is missing a required table.

set_pixel_size 

fn def set_pixel_size(mut self, pixel_size: Int)

Set this face’s active rasterization size in pixels. Must precede scale() or any pixel-space metric or outline query.

Args:

  • self (Self)
  • pixel_size (Int): Rasterization size in pixels.

scale 

fn def scale(self) -> Float64

Font-design-units -> pixels conversion factor at the active pixel size (pixel_size / units_per_em). Raises if set_pixel_size was never called (see _pixel_size).

Args:

  • self (Self)

Returns:

Float64

Raises:

advance_width 

fn def advance_width(self, glyph_index: Int) -> Int

hmtx’s rule that when there are fewer hMetrics entries than glyphs, the last entry’s advance width repeats for the rest – the spec’s optimization for monospace and large fonts.

Args:

  • self (Self)
  • glyph_index (Int): Glyph to look up.

Returns:

Int: The glyph’s advance width, in font design units.

Raises:

has_kerning 

fn def has_kerning(self) -> Bool

Whether this font carries pair kerning this module reads – a GPOS kern feature with PairPos lookups, or a format 0 horizontal kern subtable.

Args:

  • self (Self)

Returns:

Bool: True if kern_adjustment can return a nonzero value.

kern_adjustment 

fn def kern_adjustment(mut self, left: Int, right: Int) -> Int

The x-advance adjustment to apply between two adjacent glyphs, in font design units. Negative pulls them together, which is what most kerned pairs (“AV”, “To”) ask for.

GPOS takes precedence over the kern table when the font has both, since a font shipping both writes GPOS for shapers and kern for the legacy path, and every shaper resolves the overlap the same way. Memoized, since text repeats pairs.

Args:

  • self (Self)
  • left (Int): Glyph index of the left-hand glyph.
  • right (Int): Glyph index of the right-hand glyph.

Returns:

Int: The pair’s x-advance adjustment in font design units, 0 when the font kerns neither pair nor at all.

Raises:

has_substitutions 

fn def has_substitutions(self, script_tag: String = "latn") -> Bool

Whether this font carries glyph substitutions this module reads for a script – a single or ligature lookup under one of the features _script_feature_tags lists for it.

Args:

  • self (Self)
  • script_tag (String): OpenType script tag, arab or the default.

Returns:

Bool: True if substitute_glyphs can change a glyph sequence.

substitute_glyphs 

fn def substitute_glyphs(self, glyphs: List[Int]) -> ShapedRun

Apply the default script’s liga and ccmp lookups to a glyph sequence: “f”, “f”, “i” comes back as the one “ffi” glyph where the font has it. Every lookup runs at every position.

Args:

  • self (Self)
  • glyphs (List[Int]): Glyph indices to substitute over, in logical order.

Returns:

ShapedRun: The substituted glyphs, with each one’s span over glyphs.

Raises:

fn def substitute_glyphs(self, glyphs: List[Int], masks: List[Int], script_tag: String) -> ShapedRun

Apply script_tag’s substitution features to a glyph sequence, each lookup running only where its features are enabled.

masks[i] is glyph i’s enabled _FEATURE_* bits. That is what makes the Arabic joining features work: fina, medi and init each cover most of the alphabet, so a whole-run sweep would give every letter the same form. A per-glyph mask lets one sweep of fina reach only the letters joining.mojo decided are final.

Args:

  • self (Self)
  • glyphs (List[Int]): Glyph indices to substitute over, in logical order.
  • masks (List[Int]): One enabled-feature bitmask per entry of glyphs.
  • script_tag (String): OpenType script tag, arab or the default.

Returns:

ShapedRun: The substituted glyphs, with each one’s span over glyphs.

Raises:

glyph_index_for_codepoint 

fn def glyph_index_for_codepoint(mut self, codepoint: Int) -> Int

Look up codepoint in the cmap table, preferring a full-Unicode format 12 subtable (covering supplementary planes: emoji, some CJK) over a BMP-only format 4 one. Returns 0 (".notdef") when no subtable maps it, cmap’s convention.

Memoized, since text repeats characters.

Args:

  • self (Self)
  • codepoint (Int): Unicode codepoint to look up.

Returns:

Int: The mapped glyph index, or 0 (".notdef") if unmapped.

Raises:

has_color_bitmaps 

fn def has_color_bitmaps(self) -> Bool

Whether the font carries a CBLC/CBDT color strike, so some glyphs draw as bitmaps rather than outlines.

Args:

  • self (Self)

Returns:

Bool: True when a color strike was found.

color_bitmap_metrics 

fn def color_bitmap_metrics(self, glyph_index: Int) -> BitmapMetrics

The color bitmap’s size and placement for glyph_index in the largest strike, found False when the strike has no image for it.

Args:

  • self (Self)
  • glyph_index (Int): Glyph to look up.

Returns:

BitmapMetrics: The metrics, in the strike’s pixels.

Raises:

color_bitmap 

fn def color_bitmap(mut self, glyph_index: Int) -> ArcPointer[Canvas]

The decoded color bitmap for glyph_index, at the strike’s size, cached per face.

Args:

  • self (Self)
  • glyph_index (Int): Glyph to decode.

Returns:

ArcPointer[Canvas]: The bitmap as an RGBA canvas.

Raises:

Error: The glyph has no bitmap, or its image is not a PNG this package decodes.

glyph_outline 

fn def glyph_outline(mut self, glyph_index: Int) -> RawGlyphOutline

This glyph’s decoded outline, in font design units.

Returns an owned outline, copying the cached one’s point lists. glyph_outline_shared is what the rendering path uses.

Args:

  • self (Self)
  • glyph_index (Int): Glyph to decode.

Returns:

RawGlyphOutline: The glyph’s contours/points, in font design units.

Raises:

glyph_outline_shared 

fn def glyph_outline_shared(mut self, glyph_index: Int) -> ArcPointer[RawGlyphOutline]

This glyph’s decoded outline, shared rather than copied.

Args:

  • self (Self)
  • glyph_index (Int): Glyph to decode.

Returns:

ArcPointer[RawGlyphOutline]: The glyph’s contours/points, in font design units, shared with every other caller decoding the same glyph index.

Raises:

ShapedRunoutline_to_path