Struct DrawCacheBuilder

pub struct DrawCacheBuilder { /* private fields */ }

Builder & rebuilder for DrawCache.

Example

use glyph_brush_draw_cache::DrawCache;

// Create a cache with all default values set explicitly
// equivalent to `DrawCache::builder().build()`
let default_cache = DrawCache::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 = DrawCache::builder().dimensions(1024, 1024).build();

Implementations

impl DrawCacheBuilder

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

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 = DrawCache::builder().dimensions(256, 256).build();

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

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 = DrawCache::builder().scale_tolerance(0.1).build();

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

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 = DrawCache::builder().position_tolerance(0.1).build();

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

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 = DrawCache::builder().pad_glyphs(true).build();

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

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 = DrawCache::builder().align_4x4(false).build();

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

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 = DrawCache::builder().multithread(true).build();

pub fn build(self) -> DrawCache

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 = DrawCache::builder().build();

pub fn rebuild(self, cache: &mut DrawCache)

Rebuilds a DrawCache 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 DrawCacheBuilder

fn clone(&self) -> DrawCacheBuilder

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for DrawCacheBuilder

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

Formats the value using the given formatter.

impl Default for DrawCacheBuilder

fn default() -> Self

Returns the “default value” for a type.