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
indexof 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
leftandright, 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
sizepixels per em.
pub fn baseline(&self, size: u32) -> u32
Font.line_height
Function · Source
Pixels from one line’s top to the next at
sizepixels per em: the ascent, descent and line gap, rounded.
pub fn line_height(&self, size: u32) -> u32
Font.advance
Function · Source
How far
glyphadvances the pen atsize, 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
textatsizecovers: 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
textatsizepixels 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
glyphatsizepixels 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)