rusttype

RustType is a pure Rust alternative to libraries like FreeType, designed primarily for easy-to-use font rendering in applications like games.

Core Capabilities:

• Font Loading: Reads OpenType formatted fonts and collections (*.ttf and *.otf).
• Glyph Management: Retrieves glyph shapes and common properties.
• Layout: Supports horizontal layout using horizontal/vertical metrics and glyph-pair-specific kerning.
• Rasterization: Uses an accurate analytical algorithm (not sampling-based) with sub-pixel positioning.
• GPU Caching: The gpu_cache module manages a dynamic font cache in GPU memory to minimize texture uploads and keep draw calls low by storing glyphs in a single texture.

Current Limitations:

• No font hinting.
• No support for ligatures.
• No support for certain less common TrueType sub-formats.
• No support for right-to-left (RTL) or vertical text layout.

In rusttype, Point and Vector are distinct geometric primitives with specific legal operations:

• Point: Represents a location in 2D space.
  • Subtracting one Point from another results in a Vector representing the offset between them.
  • Adding or subtracting a Vector from a Point results in a new Point.
• Vector: Represents a direction and magnitude.
  • Adding or subtracting two Vectors results in a new Vector.
  • Multiplying or dividing a Vector by a scalar (f32 or f64) results in a scaled Vector.
  • Adding a Vector to a Point (or vice versa) results in a Point.

This distinction ensures that operations like p1 - p0 correctly yield a displacement, while p0 + v correctly yields a new position.

# use rusttype::*;
# let p0 = point(0.0, 0.0);
# let p1 = point(10.0, 10.0);
# let t = 0.5;
let interpolated_point = p0 + (p1 - p0) * t;

RustType uses a progressive transformation pattern for glyphs to ensure that methods are only available when the necessary context (scale or position) is provided. This prevents errors like trying to draw a glyph without knowing its size or position.

1. Glyph: The base type. It represents a raw glyph from a font with no inherent scale or position. You can only access its id() or its parent font().
2. ScaledGlyph: Created by calling .scaled(scale) on a Glyph. It adds scaling context, allowing you to access h_metrics() (horizontal metrics) and exact_bounding_box().
3. PositionedGlyph: Created by calling .positioned(point) on a ScaledGlyph. It adds positioning context, allowing you to call .draw() to rasterize the glyph or access its pixel_bounding_box().

This chain ensures that you cannot attempt to rasterize a glyph until you have explicitly defined its scale and position.

# use rusttype::*;
# let glyph: Glyph<'static> = unimplemented!();
// 1. Start with a raw Glyph
let id = glyph.id();

// 2. Scale it to get a ScaledGlyph
let glyph = glyph.scaled(Scale::uniform(10.0));
let h_metrics = glyph.h_metrics();

// 3. Position it to get a PositionedGlyph
let glyph = glyph.positioned(point(5.0, 3.0));

// 4. Now you can draw it
glyph.draw(|x, y, v| {
    // x, y: pixel coordinates relative to bounding box min
    // v: coverage (0.0 to 1.0)
});

The Font type is the primary entry point for font management in rusttype. It can either reference existing byte slices (e.g., from include_bytes!) or own its data (e.g., a Vec<u8>).

Loading Methods

• From byte slices: Use try_from_bytes(bytes: &[u8]) to create a Font that references the provided data. Use try_from_bytes_and_index(bytes: &[u8], index: u32) if the data is a font collection and you need a specific font index.
• From owned data: Use try_from_vec(data: Vec<u8>) to create a Font<'static> that owns its data. Use try_from_vec_and_index(data: Vec<u8>, index: u32) for specific indices in a collection.

All loading methods return Option<Font>, returning None if the data is invalid.

# use rusttype::Font;
// Loading from a static byte slice
let font_data: &[u8] = include_bytes!("path/to/font.ttf");
let font: Font = Font::try_from_bytes(font_data).expect("Failed to load font");

// Loading from an owned Vec
let owned_data: Vec<u8> = std::fs::read("path/to/font.ttf").unwrap();
let font_owned: Font<'static> = Font::try_from_vec(owned_data).expect("Failed to load font");

rusttype provides several ways to query font dimensions and calculate appropriate scales.

Vertical Metrics

• v_metrics_unscaled(&self) -> VMetrics: Returns the raw ascent, descent, and line_gap shared by all glyphs in the font.
• v_metrics(&self, scale: Scale) -> VMetrics: Returns the vertical metrics scaled to the provided Scale.

Scaling and Sizing

• scale_for_pixel_height(&self, height: f32) -> f32: Computes a scale factor required to make the font's total height (ascent minus descent) equal to the specified number of pixels.
• units_per_em(&self) -> u16: Returns the units per EM square defined in the font.
• glyph_count(&self) -> usize: Returns the total number of glyphs available in the font.

// Calculate scale to make font 24 pixels tall
let scale_factor = font.scale_for_pixel_height(24.0);
let scale = Scale::uniform(scale_factor);

// Get scaled vertical metrics
let metrics = font.v_metrics(scale);
println!("Ascent: {}, Descent: {}", metrics.ascent, metrics.descent);

The layout method provides a high-level way to perform horizontal text layout, including kerning. It returns a LayoutIter which produces positioned glyphs.

Usage Notes

• Unicode Normalization: layout does not perform Unicode normalization. For composite characters (like ö represented as o + ¨), you should normalize the input string using a crate like unicode-normalization before passing it to layout to ensure the correct glyph is selected.
• Control Characters: This method does not handle line breaks or other control characters; these should be handled by your application logic.

Signature

pub fn layout<'a, 's>(&'a self, s: &'s str, scale: Scale, start: Point<f32>) -> LayoutIter<'a, 'font, 's>

# use rusttype::*;
let (scale, start) = (Scale::uniform(0.5), Point::new(0.0, 0.0));
let font: Font = unimplemented!();

// Returns an iterator of positioned glyphs
for glyph in font.layout("Hello World!", scale, start) {
    // Use glyph for rendering
}