Struct glyph_brush::GlyphBrushBuilder

pub struct GlyphBrushBuilder<'a, H = DefaultSectionHasher> {
    pub font_data: Vec<Font<'a>>,
    pub cache_glyph_positioning: bool,
    pub cache_glyph_drawing: bool,
    pub section_hasher: H,
    pub gpu_cache_builder: CacheBuilder,
    // some fields omitted
}

Builder for a GlyphBrush.

Example

use glyph_brush::{GlyphBrush, GlyphBrushBuilder};

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

Fields

font_data: Vec<Font<'a>>

cache_glyph_positioning: bool

cache_glyph_drawing: bool

section_hasher: H

gpu_cache_builder: CacheBuilder

Methods

impl<'a> GlyphBrushBuilder<'a>

pub fn using_font_bytes<B: Into<SharedBytes<'a>>>(font_0_data: B) -> Self

Create a new builder with a single font's data that will be used to render glyphs. Referenced with FontId(0), which is default.

pub fn using_fonts_bytes<B, V>(font_data: V) -> Self where
    B: Into<SharedBytes<'a>>,
    V: IntoIterator<Item = B>, 

Create a new builder with multiple fonts' data.

pub fn using_font(font_0: Font<'a>) -> Self

Create a new builder with a single font that will be used to render glyphs. Referenced with FontId(0), which is default.

pub fn using_fonts<V: Into<Vec<Font<'a>>>>(fonts: V) -> Self

Create a new builder with multiple fonts.

pub fn without_fonts() -> Self

Create a new builder without any fonts.

Warning: A GlyphBrush built without fonts will panic if you try to use it as it will have no default FontId(0) to use. Use GlyphBrush.add_font before queueing any text sections in order to avoid panicking.

impl<'a, H: BuildHasher> GlyphBrushBuilder<'a, H>

pub fn add_font_bytes<B: Into<SharedBytes<'a>>>(
    &mut self,
    font_data: B
) -> FontId

Adds additional fonts to the one added in using_font / using_font_bytes. Returns a FontId to reference this font.

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

Adds additional fonts to the one added in using_font / using_font_bytes. Returns a FontId to reference this font.

pub fn replace_fonts<V, F>(self, font_fn: F) -> Self where
    V: Into<Vec<Font<'a>>>,
    F: FnOnce(Vec<Font<'a>>) -> V, 

Consume all builder fonts a replace with new fonts returned by the input function.

Generally only makes sense when wanting to change fonts after calling GlyphBrush::to_builder.

Example

let two_font_brush: GlyphBrush<'_, Vertex>
    = GlyphBrushBuilder::using_fonts(vec![open_sans, deja_vu_sans]).build();

let one_font_brush: GlyphBrush<'_, Vertex> = two_font_brush
    .to_builder()
    .replace_fonts(|mut fonts| {
        // remove open_sans, leaving just deja_vu as FontId(0)
        fonts.remove(0);
        fonts
    })
    .build();

assert_eq!(one_font_brush.fonts().len(), 1);
assert_eq!(two_font_brush.fonts().len(), 2);

pub fn initial_cache_size(self, (w, h): (u32, u32)) -> Self

Initial size of 2D texture used as a gpu cache, pixels (width, height). The GPU cache will dynamically quadruple in size whenever the current size is insufficient.

Defaults to (256, 256)

pub fn gpu_cache_scale_tolerance(self, tolerance: f32) -> Self

Sets the maximum allowed difference in scale used for judging whether to reuse an existing glyph in the GPU cache.

Defaults to 0.5

See rusttype docs for rusttype::gpu_cache::Cache

pub fn gpu_cache_position_tolerance(self, tolerance: f32) -> Self

Sets the maximum allowed difference in subpixel position used for judging whether to reuse an existing glyph in the GPU cache. Anything greater than or equal to 1.0 means "don't care".

Defaults to 0.1

See rusttype docs for rusttype::gpu_cache::Cache

pub fn gpu_cache_align_4x4(self, align: bool) -> Self

Align glyphs in texture cache 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.

Defaults to false

See rusttype docs for rusttype::gpu_cache::Cache

pub fn cache_glyph_positioning(self, cache: bool) -> Self

Sets whether perform the calculation of glyph positioning according to the layout every time, or use a cached result if the input Section and GlyphPositioner are the same hash as a previous call.

Improves performance. Should only disable if using a custom GlyphPositioner that is impure according to it's inputs, so caching a previous call is not desired. Disabling also disables cache_glyph_drawing.

Defaults to true

pub fn cache_glyph_drawing(self, cache: bool) -> Self

Sets optimising drawing by reusing the last draw requesting an identical draw queue.

Improves performance. Is disabled if cache_glyph_positioning is disabled.

Defaults to true

pub fn section_hasher<T: BuildHasher>(
    self,
    section_hasher: T
) -> GlyphBrushBuilder<'a, T>

Sets the section hasher. GlyphBrush cannot handle absolute section hash collisions so use a good hash algorithm.

This hasher is used to distinguish sections, rather than for hashmap internal use.

Defaults to xxHash.

Example

GlyphBrushBuilder::using_font_bytes(some_font)
    .section_hasher(SomeOtherBuildHasher::default())
    // ...

pub fn build<V>(self) -> GlyphBrush<'a, V, H>

Builds a GlyphBrush using the input gfx factory

pub fn rebuild<V>(self, brush: &mut GlyphBrush<'a, V, H>)

Rebuilds an existing GlyphBrush with this builder's properties. This will clear all caches and queues.

Example

let mut glyph_brush: GlyphBrush<'_, Vertex> = GlyphBrushBuilder::using_font(sans).build();
assert_eq!(glyph_brush.texture_dimensions(), (256, 256));

// Use a new builder to rebuild the brush with a smaller initial cache size
glyph_brush.to_builder().initial_cache_size((64, 64)).rebuild(&mut glyph_brush);
assert_eq!(glyph_brush.texture_dimensions(), (64, 64));