Struct rusttype::gpu_cache::CacheBuilder

pub struct CacheBuilder { /* fields omitted */ }

Builder & rebuilder for Cache.

Example

use rusttype::gpu_cache::Cache;

// Create a cache with all default values set explicitly
// equivalent to `Cache::builder().build()`
let default_cache = Cache::builder()
    .dimensions(256, 256)
    .scale_tolerance(0.1)
    .position_tolerance(0.1)
    .pad_glyphs(true)
    .align_4x4(false)
    .multithread(true)
    .build();

// Create a cache with all default values, except with a dimension of 1024x1024
let bigger_cache = Cache::builder().dimensions(1024, 1024).build();

Implementations

impl CacheBuilder

pub fn dimensions(self, width: u32, height: u32) -> CacheBuilder

width & height dimensions of the 2D texture that will hold the cache contents on the GPU.

This must match the dimensions of the actual texture used, otherwise cache_queued will try to cache into coordinates outside the bounds of the texture.

Example (set to default value)

let cache = Cache::builder().dimensions(256, 256).build();

pub fn scale_tolerance<V>(self, scale_tolerance: V) -> CacheBuilder where
    V: Into<f32>, 

Specifies the tolerances (maximum allowed difference) for judging whether an existing glyph in the cache is close enough to the requested glyph in scale to be used in its place. Due to floating point inaccuracies a min value of 0.001 is enforced.

Both scale_tolerance and position_tolerance are measured in pixels.

Tolerances produce even steps for scale and subpixel position. Only a single glyph texture will be used within a single step. For example, scale_tolerance = 0.1 will have a step 9.95-10.05 so similar glyphs with scale 9.98 & 10.04 will match.

A typical application will produce results with no perceptible inaccuracies with scale_tolerance and position_tolerance set to 0.1. Depending on the target DPI higher tolerance may be acceptable.

Example (set to default value)

let cache = Cache::builder().scale_tolerance(0.1).build();

pub fn position_tolerance<V>(self, position_tolerance: V) -> CacheBuilder where
    V: Into<f32>, 

Specifies the tolerances (maximum allowed difference) for judging whether an existing glyph in the cache is close enough to the requested glyph in subpixel offset to be used in its place. Due to floating point inaccuracies a min value of 0.001 is enforced.

Both scale_tolerance and position_tolerance are measured in pixels.

Tolerances produce even steps for scale and subpixel position. Only a single glyph texture will be used within a single step. For example, scale_tolerance = 0.1 will have a step 9.95-10.05 so similar glyphs with scale 9.98 & 10.04 will match.

Note that since position_tolerance is a tolerance of subpixel offsets, setting it to 1.0 or higher is effectively a "don't care" option.

A typical application will produce results with no perceptible inaccuracies with scale_tolerance and position_tolerance set to 0.1. Depending on the target DPI higher tolerance may be acceptable.

Example (set to default value)

let cache = Cache::builder().position_tolerance(0.1).build();

pub fn pad_glyphs(self, pad_glyphs: bool) -> CacheBuilder

Pack glyphs in texture with a padding of a single zero alpha pixel to avoid bleeding from interpolated shader texture lookups near edges.

If glyphs are never transformed this may be set to false to slightly improve the glyph packing.

Example (set to default value)

let cache = Cache::builder().pad_glyphs(true).build();

pub fn align_4x4(self, align_4x4: bool) -> CacheBuilder

Align glyphs in texture to 4x4 texel boundaries.

If your backend requires texture updates to be aligned to 4x4 texel boundaries (e.g. WebGL), this should be set to true.

Example (set to default value)

let cache = Cache::builder().align_4x4(false).build();

pub fn multithread(self, multithread: bool) -> CacheBuilder

When multiple CPU cores are available spread rasterization work across all cores.

Significantly reduces worst case latency in multicore environments.

Platform-specific behaviour

This option has no effect on wasm32.

Example (set to default value)

let cache = Cache::builder().multithread(true).build();

pub fn build<'a>(self) -> Cache<'a>

Constructs a new cache. Note that this is just the CPU side of the cache. The GPU texture is managed by the user.

Panics

scale_tolerance or position_tolerance are less than or equal to zero.

Example

let cache = Cache::builder().build();

pub fn rebuild(self, cache: &mut Cache<'_>)

Rebuilds a Cache with new attributes. All cached glyphs are cleared, however the glyph queue is retained unmodified.

Panics

scale_tolerance or position_tolerance are less than or equal to zero.

Example

// Rebuild the cache with different dimensions
cache.to_builder().dimensions(768, 768).rebuild(&mut cache);

Trait Implementations

impl Clone for CacheBuilder

fn clone(&self) -> CacheBuilder

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CacheBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for CacheBuilder

fn default() -> CacheBuilder

Returns the "default value" for a type.