Module rusttype::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.

This module is optional, and not compiled by default. To use it enable the gpu_cache feature in your Cargo.toml.

Typical applications that render directly with hardware graphics APIs (e.g. games) need text rendering. There is not yet a performant solution for high quality text rendering directly on the GPU that isn't experimental research work. Quality is often critical for legibility, so many applications use text or individual characters that have been rendered on the CPU. This is done either ahead-of-time, giving a fixed set of fonts, characters, and sizes that can be used at runtime, or dynamically as text is required. This latter scenario is more flexible and the focus of this module.

To minimise the CPU load and texture upload bandwidth saturation, recently used glyphs should be cached on the GPU for use by future frames. This module provides a mechanism for maintaining such a cache in the form of a single packed 2D GPU texture. When a rendered glyph is requested, it is either retrieved from its location in the texture if it is present or room is made in the cache (if necessary), the CPU renders the glyph then it is uploaded into a gap in the texture to be available for GPU rendering. This cache uses a Least Recently Used (LRU) cache eviction scheme - glyphs in the cache that have not been used recently are as a rule of thumb not likely to be used again soon, so they are the best candidates for eviction to make room for required glyphs.

The API for the cache does not assume a particular graphics API. The intended usage is to queue up glyphs that need to be present for the current frame using Cache::queue_glyph, update the cache to ensure that the queued glyphs are present using Cache::cache_queued (providing a function for uploading pixel data), then when it's time to render call Cache::rect_for to get the UV coordinates in the cache texture for each glyph. For a concrete use case see the gpu_cache example.

Cache dimensions are immutable. If you need to change the dimensions of the cache texture (e.g. due to high cache pressure), rebuild a new Cache. Either from scratch or with CacheBuilder::rebuild.

Example

// Build a default Cache.
let mut cache = Cache::builder().build();

// Queue some positioned glyphs needed for the next frame.
cache.queue_glyph(0, glyph);

// Cache all queued glyphs somewhere in the cache texture.
// If new glyph data has been drawn the closure is called to upload
// the pixel data to GPU memory.
cache.cache_queued(|region, data| update_gpu_texture(region, data))?;

// Lookup a positioned glyph's texture location
if let Ok(Some((uv_rect, screen_rect))) = cache.rect_for(0, &glyph) {
    // Generate vertex data, etc
}

Structs

Cache	An implementation of a dynamic GPU glyph cache. See the module documentation for more information.
CacheBuilder	Builder & rebuilder for Cache.

Enums

CacheReadErr	Returned from Cache::rect_for.
CacheWriteErr	Returned from Cache::cache_queued.
CachedBy	Successful method of caching of the queue.

Type Definitions

TextureCoords

Texture coordinates (floating point) of the quad for a glyph in the cache, as well as the pixel-space (integer) coordinates that this region should be drawn at.