[−][src]Crate rusttype

RustType is a pure Rust alternative to libraries like FreeType.

The current capabilities of RustType:

Reading TrueType formatted fonts and font collections. This includes *.ttf as well as a subset of *.otf font files.
Retrieving glyph shapes and commonly used properties for a font and its glyphs.
Laying out glyphs horizontally using horizontal and vertical metrics, and glyph-pair-specific kerning.
Rasterising glyphs with sub-pixel positioning using an accurate analytical algorithm (not based on sampling).
Managing a font cache on the GPU with the gpu_cache module. This keeps recently used glyph renderings in a dynamic cache in GPU memory to minimise texture uploads per-frame. It also allows you keep the draw call count for text very low, as all glyphs are kept in one GPU texture.

Notable things that RustType does not support yet:

OpenType formatted fonts that are not just TrueType fonts (OpenType is a superset of TrueType). Notably there is no support yet for cubic Bezier curves used in glyphs.
Font hinting.
Ligatures of any kind.
Some less common TrueType sub-formats.
Right-to-left and vertical text layout.

Getting Started

To hit the ground running with RustType, look at the simple.rs example supplied with the crate. It demonstrates loading a font file, rasterising an arbitrary string, and displaying the result as ASCII art. If you prefer to just look at the documentation, the entry point for loading fonts is FontCollection, from which you can access individual fonts, then their glyphs.

Glyphs

The glyph API uses wrapper structs to augment a glyph with information such as scaling and positioning, making relevant methods that make use of this information available as appropriate. For example, given a Glyph glyph obtained directly from a Font:

// One of the few things you can do with an unsized, positionless glyph is get its id.
let id = glyph.id();
let glyph = glyph.scaled(Scale::uniform(10.0));
// Now glyph is a ScaledGlyph, you can do more with it, as well as what you can do with Glyph.
// For example, you can access the correctly scaled horizontal metrics for the glyph.
let h_metrics = glyph.h_metrics();
let glyph = glyph.positioned(point(5.0, 3.0));
// Now glyph is a PositionedGlyph, and you can do even more with it, e.g. drawing.
glyph.draw(|x, y, v| {}); // In this case the pixel values are not used.

Unicode terminology

This crate uses terminology for computerised typography as specified by the Unicode standard. If you are not sure of the differences between a code point, a character, and a glyph, you may want to check the official Unicode glossary, or alternatively, here's my take on it from a practical perspective:

A character is what you would conventionally call a single symbol, independent of its appearance or representation in a particular font. Examples include a, A, ä, å, 1, *, Ω, etc.
A Unicode code point is the particular number that the Unicode standard associates with a particular character. Note however that code points also exist for things not conventionally thought of as characters by themselves, but can be combined to form characters, such as diacritics like accents. These "characters" are known in Unicode as "combining characters". E.g., a diaeresis (¨) has the code point U+0308. If this code point follows the code point U+0055 (the letter u), this sequence represents the character ü. Note that there is also a single codepoint for ü, U+00FC. This means that what visually looks like the same string can have multiple different Unicode representations. Some fonts will have glyphs (see below) for one sequence of codepoints, but not another that has the same meaning. To deal with this problem it is recommended to use Unicode normalisation, as provided by, for example, the unicode-normalization crate, to convert to code point sequences that work with the font in question. Typically a font is more likely to support a single code point vs. a sequence with the same meaning, so the best normalisation to use is "canonical recomposition", known as NFC in the normalisation crate.
A glyph is a particular font's shape to draw the character for a particular Unicode code point. This will have its own identifying number unique to the font, its ID.

Modules

gpu_cache

This module provides capabilities for managing a cache of rendered glyphs in GPU memory, with the goal of minimisng the size and frequency of glyph uploads to GPU memory from the CPU.

Structs

Codepoint	Represents a Unicode code point.
Contour	A closed loop consisting of a sequence of `Segment`s.
Curve	A quadratic Bezier curve, starting at `p[0]`, ending at `p[2]`, with control point `p[1]`.
Font	A single font. This may or may not own the font data.
FontCollection	A collection of fonts read straight from a font file's data. The data in the collection is not validated. This structure may or may not own the font data.
Glyph	A single glyph of a font. this may either be a thin wrapper referring to the font and the glyph id, or it may be a standalone glyph that owns the data needed by it.
GlyphId	Represents a glyph identifier for a particular font. This identifier will not necessarily correspond to the correct glyph in a font other than the one that it was obtained from.
GlyphIter
HMetrics	The "horizontal metrics" of a glyph. This is useful for calculating the horizontal offset of a glyph from the previous one in a string when laying a string out horizontally.
IntoFontsIter
LayoutIter
Line	A straight line between two points, `p[0]` and `p[1]`
Point	A point in 2-dimensional space, with each dimension of type `N`.
PositionedGlyph	A glyph augmented with positioning and scaling information. You can query such a glyph for information that depends on the scale and position of the glyph.
Rect	A rectangle, with top-left corner at `min`, and bottom-right corner at `max`.
Scale	Defines the size of a rendered face of a font, in pixels, horizontally and vertically. A vertical scale of `y` pixels means that the distance betwen the ascent and descent lines (see `VMetrics`) of the face will be `y` pixels. If `x` and `y` are equal the scaling is uniform. Non-uniform scaling by a factor f in the horizontal direction is achieved by setting `x` equal to f times `y`.
ScaledGlyph	A glyph augmented with scaling information. You can query such a glyph for information that depends on the scale of the glyph.
SharedGlyphData
VMetrics	The "vertical metrics" of a font at a particular scale. This is useful for calculating the amount of vertical space to give a line of text, and for computing the vertical offset between successive lines.
Vector	A vector in 2-dimensional space, with each dimension of type `N`.

Enums

Error	The type for errors returned by rusttype.
Segment	Part of a `Contour`, either a `Line` or a `Curve`.
SharedBytes	`SharedBytes` handles the lifetime of font data used in RustType. The data is either a shared reference to externally owned data, or managed by reference counting. `SharedBytes` can be conveniently used with `From` and `Into`, and dereferences to the contained bytes.

Traits

IntoGlyphId

A trait for types that can be converted into a GlyphId, in the context of a specific font.

Functions

point	A convenience function for generating `Point`s.
vector	A convenience function for generating `Vector`s.