Struct glyph_brush::GlyphBrush

pub struct GlyphBrush<'font, V: Clone + 'static, H = DefaultSectionHasher> { /* 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.

Caching behaviour

Calls to GlyphBrush::queue, GlyphBrush::pixel_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.

Methods

impl<'font, V: Clone + 'static, H: BuildHasher> GlyphBrush<'font, V, H>

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

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
    S: Into<Cow<'a, VariedSection<'a>>>, 

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 {
    text: "Hello glyph_brush",
    ..Section::default()
});

pub fn queue_pre_positioned(
    &mut self,
    glyphs: Vec<(PositionedGlyph<'font>, Color, FontId)>,
    bounds: Rect<f32>,
    z: f32
)

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

pub fn process_queued<F1, F2>(
    &mut self,
    (screen_w, screen_h): (u32, u32),
    update_texture: F1,
    to_vertex: F2
) -> Result<BrushAction<V>, BrushError> where
    F1: FnMut(Rect<u32>, &[u8]),
    F2: Fn(GlyphVertex) -> 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(
    (1024, 768),
    |rect, tex_data| update_texture(rect, tex_data),
    |vertex_data| into_vertex(vertex_data),
)?

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 add_font_bytes<'a: 'font, B: Into<SharedBytes<'a>>>(
    &mut self,
    font_data: B
) -> FontId

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

Returns a new FontId to reference this font.

Example

use glyph_brush::{GlyphBrush, GlyphBrushBuilder, Section};

// dejavu is built as default `FontId(0)`
let dejavu: &[u8] = include_bytes!("../../fonts/DejaVuSans.ttf");
let mut glyph_brush: GlyphBrush<'_, Vertex> =
    GlyphBrushBuilder::using_font_bytes(dejavu).build();

// some time later, add another font referenced by a new `FontId`
let open_sans_italic: &[u8] = include_bytes!("../../fonts/OpenSans-Italic.ttf");
let open_sans_italic_id = glyph_brush.add_font_bytes(open_sans_italic);

pub fn add_font<'a: 'font>(&mut self, font_data: Font<'a>) -> FontId

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

Returns a new FontId to reference this font.

pub fn keep_cached_custom_layout<'a, S, G>(
    &mut self,
    section: S,
    custom_layout: &G
) where
    S: Into<Cow<'a, VariedSection<'a>>>,
    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, VariedSection<'a>>>, 

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.

Trait Implementations

impl<'font, V: Clone + 'static, H: BuildHasher> GlyphCruncher<'font> for GlyphBrush<'font, V, H>

fn pixel_bounds_custom_layout<'a, S, L>(
    &mut self,
    section: S,
    custom_layout: &L
) -> Option<Rect<i32>> where
    L: GlyphPositioner + Hash,
    S: Into<Cow<'a, VariedSection<'a>>>, 

Returns the pixel bounding box for the input section using a custom layout. The box is a conservative whole number pixel rectangle that can contain the section.

fn glyphs_custom_layout<'a, 'b, S, L>(
    &'b mut self,
    section: S,
    custom_layout: &L
) -> PositionedGlyphIter<'b, 'font> where
    L: GlyphPositioner + Hash,
    S: Into<Cow<'a, VariedSection<'a>>>, 

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

Important traits for &'_ mut [u8]

impl<'_> Write for &'_ mut [u8]impl<'_> Read for &'_ [u8]

fn fonts(&self) -> &[Font<'font>]

Returns the available fonts.

fn pixel_bounds<'a, S>(&mut self, section: S) -> Option<Rect<i32>> where
    S: Into<Cow<'a, VariedSection<'a>>>, 

Returns the pixel bounding box for the input section. The box is a conservative whole number pixel rectangle that can contain the section.

fn glyphs<'a, 'b, S>(&'b mut self, section: S) -> PositionedGlyphIter<'b, 'font> where
    S: Into<Cow<'a, VariedSection<'a>>>, 

Returns an iterator over the PositionedGlyphs of the given section.

impl<V: Clone + 'static, H, '_> Debug for GlyphBrush<'_, V, H>

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

Formats the value using the given formatter.