Struct ggez::graphics::GlyphBrush

pub struct GlyphBrush<V, X = Extra, F = FontArc, H = RandomXxHashBuilder64> { /* fields omitted */ }

Object allowing glyph drawing, containing cache state. Manages glyph positioning cacheing, glyph draw caching & efficient GPU texture cache updating.

Build using a GlyphBrushBuilder.

Also see GlyphCruncher trait which providers extra functionality, such as glyph_bounds.

Caching behaviour

Calls to GlyphBrush::queue, GlyphBrush::glyph_bounds, GlyphBrush::glyphs calculate the positioned glyphs for a section. This is cached so future calls to any of the methods for the same section are much cheaper. In the case of GlyphBrush::queue the calculations will also be used for actual drawing.

The cache for a section will be cleared after a GlyphBrush::process_queued call when that section has not been used since the previous call.

Texture caching behaviour

Note the gpu/draw cache may contain multiple versions of the same glyph at different subpixel positions. This is required for high quality text as a glyph’s positioning is always exactly aligned to it’s draw positioning.

This behaviour can be adjusted with GlyphBrushBuilder::draw_cache_position_tolerance (struct.GlyphBrushBuilder.html#method.draw_cache_position_tolerance).

Implementations

impl<F, V, X, H> GlyphBrush<V, X, F, H> where
    H: BuildHasher, 

pub fn add_font<I>(&mut self, font_data: I) -> FontId where
    I: Into<F>, 

Adds an additional font to the one(s) initially added on build.

Returns a new FontId to reference this font.

impl<F, V, X, H> GlyphBrush<V, X, F, H> where
    F: Font,
    X: Clone + Hash,
    V: 'static + Clone,
    H: BuildHasher, 

pub fn queue_custom_layout<'a, S, G>(&mut self, section: S, custom_layout: &G) where
    G: GlyphPositioner,
    X: 'a,
    S: Into<Cow<'a, Section<'a, X>>>, 

Queues a section/layout to be processed by the next call of process_queued. Can be called multiple times to queue multiple sections for drawing.

Used to provide custom GlyphPositioner logic, if using built-in Layout simply use queue

Benefits from caching, see caching behaviour.

pub fn queue<'a, S>(&mut self, section: S) where
    X: 'a,
    S: Into<Cow<'a, Section<'a, X>>>, 

Queues a section/layout to be processed by the next call of process_queued. Can be called multiple times to queue multiple sections for drawing.

Benefits from caching, see caching behaviour.

glyph_brush.queue(Section::default().add_text(Text::new("Hello glyph_brush")));

pub fn queue_pre_positioned(
    &mut self,
    glyphs: Vec<SectionGlyph, Global>,
    extra: Vec<X, Global>,
    bounds: Rect
)

Queues pre-positioned glyphs to be processed by the next call of process_queued. Can be called multiple times.

pub fn resize_texture(&mut self, new_width: u32, new_height: u32)

Rebuilds the logical texture cache with new dimensions. Should be avoided if possible.

Example

glyph_brush.resize_texture(512, 512);

pub fn texture_dimensions(&self) -> (u32, u32)

Returns the logical texture cache pixel dimensions (width, height).

pub fn keep_cached_custom_layout<'a, S, G>(
    &mut self,
    section: S,
    custom_layout: &G
) where
    S: Into<Cow<'a, Section<'a, Extra>>>,
    G: GlyphPositioner, 

Retains the section in the cache as if it had been used in the last draw-frame.

Should not generally be necessary, see caching behaviour.

pub fn keep_cached<'a, S>(&mut self, section: S) where
    S: Into<Cow<'a, Section<'a, Extra>>>, 

Retains the section in the cache as if it had been used in the last draw-frame.

Should not generally be necessary, see caching behaviour.

impl<F, V, X, H> GlyphBrush<V, X, F, H> where
    F: Font + Sync,
    X: Clone + Hash + PartialEq<X>,
    V: 'static + Clone,
    H: BuildHasher, 

pub fn process_queued<Up, VF>(
    &mut self,
    update_texture: Up,
    to_vertex: VF
) -> Result<BrushAction<V>, BrushError> where
    Up: FnMut(Rectangle<u32>, &[u8]),
    VF: Fn(GlyphVertex<'_, X>) -> V + Copy, 

Processes all queued sections, calling texture update logic when necessary & returning a BrushAction. See queue.

Two closures are required:

• update_texture is called when new glyph texture data has been drawn for update in the actual texture. The arguments are the rect position of the data in the texture & the byte data itself which is a single u8 alpha value per pixel.
• to_vertex maps a single glyph’s GlyphVertex data into a generic vertex type. The mapped vertices are returned in an Ok(BrushAction::Draw(vertices)) result. It’s recommended to use a single vertex per glyph quad for best performance.

Trims the cache, see caching behaviour.

glyph_brush.process_queued(
    |rect, tex_data| update_texture(rect, tex_data),
    |vertex_data| into_vertex(vertex_data),
)?

pub fn is_draw_cached(&self, font_id: FontId, glyph: &Glyph) -> bool

Returns true if this glyph is currently present in the draw cache texture.

So false means either this glyph is invisible, like ' ', or hasn’t been queued & processed yet.

impl<F, V, X, H> GlyphBrush<V, X, F, H> where
    F: Font + Clone,
    H: BuildHasher + Clone, 

pub fn to_builder(&self) -> GlyphBrushBuilder<F, H>

Return a GlyphBrushBuilder prefilled with the properties of this GlyphBrush.

Example

let glyph_brush: GlyphBrush<Vertex> = GlyphBrushBuilder::using_font(sans)
    .initial_cache_size((128, 128))
    .build();

let new_brush: GlyphBrush<Vertex> = glyph_brush.to_builder().build();
assert_eq!(new_brush.texture_dimensions(), (128, 128));

Trait Implementations

impl<F, V, X, H> Debug for GlyphBrush<V, X, F, H>

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

Formats the value using the given formatter.

impl<F, V, X, H> GlyphCruncher<F, X> for GlyphBrush<V, X, F, H> where
    X: Clone + Hash,
    F: Font,
    V: 'static + Clone,
    H: BuildHasher, 

pub fn glyphs_custom_layout<'a, S, L>(
    &'b mut self,
    section: S,
    custom_layout: &L
) -> Iter<'b, SectionGlyph> where
    X: 'a,
    L: GlyphPositioner + Hash,
    S: Into<Cow<'a, Section<'a, X>>>, 

Returns an iterator over the PositionedGlyphs of the given section with a custom layout.

pub fn glyph_bounds_custom_layout<'a, S, L>(
    &mut self,
    section: S,
    custom_layout: &L
) -> Option<Rect> where
    X: 'a,
    L: GlyphPositioner + Hash,
    S: Into<Cow<'a, Section<'a, X>>>, 

Returns a bounding box for the section glyphs calculated using each glyph’s vertical & horizontal metrics.

pub fn fonts(&self) -> &[F]

Returns the available fonts.

fn glyphs<'a, S>(&'b mut self, section: S) -> Iter<'b, SectionGlyph> where
    X: 'a,
    S: Into<Cow<'a, Section<'a, X>>>, 

Returns an iterator over the PositionedGlyphs of the given section.

fn glyph_bounds<'a, S>(&mut self, section: S) -> Option<Rect> where
    X: 'a,
    S: Into<Cow<'a, Section<'a, X>>>, 

Returns a bounding box for the section glyphs calculated using each glyph’s vertical & horizontal metrics.