# [−][src]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.

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)