Struct conrod::text::GlyphCache

pub struct GlyphCache<'font> { /* fields omitted */ }

An implementation of a dynamic GPU glyph cache. See the module documentation for more information.

Methods

impl<'font> Cache<'font>

fn new<'a>(
    width: u32,
    height: u32,
    scale_tolerance: f32,
    position_tolerance: f32
) -> 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.

width and height specify the 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. If you need to change the dimensions of the cache texture (e.g. due to high cache pressure), construct a new Cache and discard the old one.

scale_tolerance and position_tolerance specify the tolerances (maximum allowed difference) for judging whether an existing glyph in the cache is close enough to the requested glyph in scale and subpixel offset to be used in its place. Due to floating point inaccuracies that can affect user code it is not recommended to set these parameters too close to zero as effectively identical glyphs could end up duplicated in the cache. Both scale_tolerance and position_tolerance are measured in pixels. Note that since pixel_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.

Panics

scale_tolerance or position_tolerance are less than or equal to zero.

fn set_scale_tolerance(&mut self, tolerance: f32)

Sets the scale tolerance for the cache. See the documentation for Cache::new for more information.

Panics

tolerance is less than or equal to zero.

fn scale_tolerance(&self) -> f32

Returns the current scale tolerance for the cache.

fn set_position_tolerance(&mut self, tolerance: f32)

Sets the subpixel position tolerance for the cache. See the documentation for Cache::new for more information.

Panics

tolerance is less than or equal to zero.

fn position_tolerance(&self) -> f32

Returns the current subpixel position tolerance for the cache.

fn dimensions(&self) -> (u32, u32)

Returns the cache texture dimensions assumed by the cache. For proper operation this should match the dimensions of the used GPU texture.

fn queue_glyph(&mut self, font_id: usize, glyph: PositionedGlyph<'font>)

Queue a glyph for caching by the next call to cache_queued. font_id is used to disambiguate glyphs from different fonts. The user should ensure that font_id is unique to the font the glyph is from.

fn clear(&mut self)

Clears the cache. Does not affect the glyph queue.

fn clear_queue(&mut self)

Clears the glyph queue.

fn cache_queued<F>(&mut self, uploader: F) -> Result<(), CacheWriteErr> where
    F: FnMut(Rect<u32>, &[u8]) -> (), 

Caches the queued glyphs. If this is unsuccessful, the queue is untouched. Any glyphs cached by previous calls to this function may be removed from the cache to make room for the newly queued glyphs. Thus if you want to ensure that a glyph is in the cache, the most recently cached queue must have contained that glyph.

uploader is the user-provided function that should perform the texture uploads to the GPU. The information provided is the rectangular region to insert the pixel data into, and the pixel data itself. This data is provided in horizontal scanline format (row major), with stride equal to the rectangle width.

fn rect_for(
    &'a self,
    font_id: usize,
    glyph: &PositionedGlyph
) -> Result<Option<(Rect<f32>, Rect<i32>)>, CacheReadErr>

Retrieves the (floating point) texture coordinates of the quad for a glyph in the cache, as well as the pixel-space (integer) coordinates that this region should be drawn at. In the majority of cases these pixel-space coordinates should be identical to the bounding box of the input glyph. They only differ if the cache has returned a substitute glyph that is deemed close enough to the requested glyph as specified by the cache tolerance parameters.

A sucessful result is Some if the glyph is not an empty glyph (no shape, and thus no rect to return).

Ensure that font_id matches the font_id that was passed to queue_glyph with this glyph.