Struct rusttype::gpu_cache::Cache
[−]
[src]
pub struct Cache { // some fields omitted }
An implementation of a dynamic GPU glyph cache. See the module documentation for more information.
Methods
impl Cache
fn new(width: u32, height: u32, scale_tolerance: f32, position_tolerance: f32) -> Cache
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)
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: FnMut(Rect<u32>, &[u8])>(&mut self, uploader: F) -> Result<(), CacheWriteErr>
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>(&'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
.