Crate rusttype [−] [src]

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).

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.
Ligatures of any kind
Some less common TrueType sub-formats.
Right-to-left and vertical text layout.

Getting Started

Add the following to your Cargo.toml:

[dependencies]
rusttype = "0.1"

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 an inheritance-style approach using Deref to incrementally 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(Pixels(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.

Structs

Bytes	A newtype wrapper for `Cow<[u8]>` that can be targetted by `From` and `Into`. This is intended to be used for providing convenient APIs that can accept `Vec<u8>`s or `&[u8]`s or other types that can be read as `[u8]`s (feel free to provide your own `From` implementations).
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.
LayoutIter
Line	A straight line between two points, `p[0]` and `p[1]`
Pixels	A uniform font scaling that makes the height of the rendered font a specific number of pixels. For example, if you want to render a font with a height of 20 pixels, use `Pixels(20.0)`.
PixelsXY	A nonuniform font scaling. `PixelsXY(x, y)` produces a scaling that makes the height of the rendered font `y` pixels high, with a horizontal scale factor on top of that of `x/y`. For example, if you want to render a font with a height of 20 pixels, but have it horizontally stretched by a factor of two, use `PixelsXY(40.0, 20.0)`.
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	An opaque struct representing a common format for font scaling. You typically won't use this struct directly, instead using `Pixels` or `PixelsXY` and the `Into` trait to pass them to functions.
SizedGlyph	A glyph augmented with scaling information. You can query such a glyph for information that depends on the scale of the glyph.
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

CodepointOrGlyphId	Represents either a Unicode code point, or a glyph identifier for a font.
Segment	Part of a `Contour`, either a `Line` or a `Curve`.

Functions

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