API referencestd/graphics

std/graphics/truetype

Public declarations, types, methods, and source contracts for std/graphics/truetype.

On this page

Library guide · API index and notation

This page is generated from the bundled library in this checkout. Signatures and adjacent source comments are reproduced below; the linked guide explains usage, storage, failures, and platform support.

import "std/graphics/truetype"

Names used in signatures

Unqualified names denote this package’s types (including other source files in the same package), language built-ins, or generic parameters such as T. Qualified names use the import aliases below. These aliases belong to the library source; import a dependency yourself to use its alias in your program.

Alias Package Source file
bytes core/bytes truetype.dodo
graphics std/graphics truetype.dodo
mem core/mem truetype.dodo

Error

Enum · Source

pub enum Error {
    // The data is not a TrueType font or collection, or a table it needs is
    // missing or extends past the end of the data.
    Malformed,
    // A valid font this package cannot draw, such as one with CFF outlines
    // or no Unicode character map.
    Unsupported,
    // A collection index past the last font.
    NoSuchFont
}

error_name

Function · Source

pub fn error_name(error: Error) -> &str from(static)

MAX_SIZE

Constant · Source

The largest size, in pixels per em, that drawing and measuring accept; larger sizes are clamped.

pub const MAX_SIZE: u32 = 4096

font_count

Function · Source

The number of fonts in data: the collection’s count for a .ttc, 1 for a single font.

pub fn font_count(data: &[u8]) -> u32!Error

GlyphBox

Struct · Source

pub struct GlyphBox {
    pub x_min: i32
    pub y_min: i32
    pub x_max: i32
    pub y_max: i32
}

Font

Struct · Source

A parsed font: offsets into the borrowed font data.

pub struct Font {
    // Private implementation fields omitted.
}

Font.new

Function · Source

The font in a .ttf file, or the first font of a .ttc collection.

pub fn new(data: &[u8]) -> Font!Error from(data)

Font.from_collection

Function · Source

Font index of a .ttc collection; index 0 also opens a .ttf.

pub fn from_collection(data: &[u8], index: u32) -> Font!Error from(data)

Font.units_per_em

Function · Source

pub fn units_per_em(&self) -> u32

Font.glyph_count

Function · Source

pub fn glyph_count(&self) -> u32

Font.ascent

Function · Source

Distance from the baseline to the top of the tallest glyphs, in font units (positive).

pub fn ascent(&self) -> i32

Font.descent

Function · Source

Distance from the baseline to the bottom of the lowest glyphs, in font units (negative).

pub fn descent(&self) -> i32

Font.line_gap

Function · Source

Extra space between lines, in font units.

pub fn line_gap(&self) -> i32

Font.glyph_index

Function · Source

The glyph for a Unicode code point, or 0 (the font’s .notdef glyph, usually a box) when the font has none.

pub fn glyph_index(&self, code_point: u32) -> u32

Font.has_glyph

Function · Source

pub fn has_glyph(&self, code_point: u32) -> bool

Font.advance_width

Function · Source

How far the pen moves after glyph, in font units.

pub fn advance_width(&self, glyph: u32) -> u32

Font.left_side_bearing

Function · Source

Distance from the pen position to the left edge of glyph’s outline, in font units.

pub fn left_side_bearing(&self, glyph: u32) -> i32

Font.kerning

Function · Source

The adjustment to the advance between left and right, in font units, from the font’s kern table; 0 without one.

pub fn kerning(&self, left: u32, right: u32) -> i32

Font.glyph_box

Function · Source

The bounding box the font records for glyph, in font units with y up; all zero for a glyph without an outline, such as a space.

pub fn glyph_box(&self, glyph: u32) -> GlyphBox

Font.baseline

Function · Source

Pixels from the top of a line to its baseline at size pixels per em.

pub fn baseline(&self, size: u32) -> u32

Font.line_height

Function · Source

Pixels from one line’s top to the next at size pixels per em: the ascent, descent and line gap, rounded.

pub fn line_height(&self, size: u32) -> u32

Font.advance

Function · Source

How far glyph advances the pen at size, in subpixels (256 to the pixel). Text is positioned to the subpixel, so advances need not be whole pixels.

pub fn advance(&self, glyph: u32, size: u32) -> i64

Font.measure

Function · Source

The area drawing text at size covers: the widest line’s advance, rounded up, by the line count times line_height(size). “\n” starts a line and “\r” is ignored.

pub fn measure(&self, text: &str, size: u32) -> graphics.Size

Font.draw

Function · Source

Draw text at size pixels per em with the top-left corner of its first line at (x, y), antialiased and blended over the canvas, and return the area measure(text, size) reports. Each line’s baseline is baseline(size) pixels below its top. Missing characters draw as the font’s .notdef glyph.

pub fn draw(&self, canvas: &mut graphics.Canvas, x: i32, y: i32, text: &str, size: u32, color: graphics.Color) -> graphics.Rect

Font.draw_gradient

Function · Source

draw with a gradient instead of a color.

pub fn draw_gradient(&self, canvas: &mut graphics.Canvas, x: i32, y: i32, text: &str, size: u32, gradient: &graphics.Gradient) -> graphics.Rect

Font.glyph

Function · Source

The outline of glyph at size pixels per em with its origin (the pen position on the baseline) at subpixel position (x, y). Fill it with canvas.fill_outline or gradient_outline using FillRule.NonZero.

pub fn glyph(&self, glyph: u32, x: i32, y: i32, size: u32) -> Glyph from(self)

GlyphCache

Struct · Source

Remembers rasterized glyphs so drawing text again copies coverage instead of decoding and rasterizing outlines. Each cached glyph is its coverage, stored as runs (graphics.coverage_spans) in storage the caller provides; the cache never allocates. Draw through the cache wherever Font.draw would be called:

storage := [0u8; 65536] cache := truetype.GlyphCache.new(&font, &mut storage) cache.draw(&mut canvas, 10, 10, “Score: 1200”, 14, graphics.WHITE)

Text drawn through the cache matches Font.draw except that glyphs are placed to a quarter pixel horizontally instead of 1/256: a glyph is cached for each size and each of the four quarter-pixel offsets it is drawn at. Any amount of storage works, more holds more glyphs: 64 KiB holds a few hundred glyphs at 14 pixels per em, or a few dozen at 96. When the cache is full the glyphs cached longest ago make room. A glyph whose bounding box exceeds about a quarter of the storage in pixels is drawn from its outline, uncached, so one huge glyph cannot flush the rest.

pub struct GlyphCache {
    // Private implementation fields omitted.
}

GlyphCache.new

Function · Source

pub fn new(font: &Font, storage: &mut[u8]) -> GlyphCache from(font, storage)

GlyphCache.draw

Function · Source

Font.draw through the cache.

pub fn draw(&mut self, canvas: &mut graphics.Canvas, x: i32, y: i32, text: &str, size: u32, color: graphics.Color) -> graphics.Rect

GlyphCache.draw_gradient

Function · Source

Font.draw_gradient through the cache. The cached masks are the same for every color and gradient.

pub fn draw_gradient(&mut self, canvas: &mut graphics.Canvas, x: i32, y: i32, text: &str, size: u32, gradient: &graphics.Gradient) -> graphics.Rect

GlyphCache.clear

Function · Source

Forget every cached glyph.

pub fn clear(&mut self)

GlyphCache.len

Function · Source

The number of glyphs cached.

pub fn len(&self) -> usize

GlyphCache.is_empty

Function · Source

pub fn is_empty(&self) -> bool

GlyphCache.hits

Function · Source

Glyphs drawn from the cache and glyphs rasterized (cached or not) since the cache was made, for judging how much storage to give it.

pub fn hits(&self) -> u64

GlyphCache.misses

Function · Source

pub fn misses(&self) -> u64

Glyph

Struct · Source

One glyph of a font, placed and scaled for drawing; see Font.glyph. It implements graphics.Outline.

pub struct Glyph {
    // Private implementation fields omitted.
}

Glyph.index

Function · Source

pub fn index(&self) -> u32

Glyph.trace

Function · Source

pub fn trace(&self, pen: &mut graphics.Pen)

Search every guide, reference page, and API declaration.