Struct gfx_glyph::GlyphBrush

pub struct GlyphBrush<'font, R: Resources, F: Factory<R>, H = DefaultSectionHasher> { /* private fields */ }

Object allowing glyph drawing, containing cache state. Manages glyph positioning cacheing, glyph draw caching & efficient GPU texture cache updating and re-sizing on demand.

Build using a GlyphBrushBuilder.

Example

extern crate gfx_glyph;
use gfx_glyph::Section;

let section = Section {
    text: "Hello gfx_glyph",
    ..Section::default()
};

glyph_brush.queue(section);
glyph_brush.queue(some_other_section);

glyph_brush.draw_queued(&mut gfx_encoder, &gfx_color, &gfx_depth)?;

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::draw_queued call when that section has not been used since the previous draw call.

Implementations

impl<'font, R: Resources, F: Factory<R>, H: BuildHasher> GlyphBrush<'font, R, F, 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 drawn by the next call of draw_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 drawn by the next call of draw_queued. Can be called multiple times to queue multiple sections for drawing.

Benefits from caching, see caching behaviour.

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 be necessary unless using multiple draws per frame with distinct transforms, 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 be necessary unless using multiple draws per frame with distinct transforms, see caching behaviour.

pub fn draw_queued<C, CV, DV>(
    &mut self,
    encoder: &mut Encoder<R, C>,
    target: &CV,
    depth_target: &DV
) -> Result<(), String>where
    C: CommandBuffer<R>,
    CV: RawAndFormat<Raw = RawRenderTargetView<R>>,
    DV: RawAndFormat<Raw = RawDepthStencilView<R>>,

Draws all queued sections onto a render target, applying a position transform (e.g. a projection). See queue.

Trims the cache, see caching behaviour.

Raw usage

Can also be used with gfx raw render & depth views if necessary. The Format must also be provided. See example.

pub fn draw_queued_with_transform<C, CV, DV>(
    &mut self,
    transform: [[f32; 4]; 4],
    encoder: &mut Encoder<R, C>,
    target: &CV,
    depth_target: &DV
) -> Result<(), String>where
    C: CommandBuffer<R>,
    CV: RawAndFormat<Raw = RawRenderTargetView<R>>,
    DV: RawAndFormat<Raw = RawDepthStencilView<R>>,

Draws all queued sections onto a render target, applying a position transform (e.g. a projection). See queue.

Trims the cache, see caching behaviour.

Raw usage

Can also be used with gfx raw render & depth views if necessary. The Format must also be provided.

glyph_brush.draw_queued_with_transform(
    transform,
    &mut gfx_encoder,
    &(raw_render_view, format::Srgba8::get_format()),
    &(raw_depth_view, format::Depth::get_format()),
)?

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

Returns the available fonts.

The FontId corresponds to the index of the font data.

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

extern crate gfx_glyph;
use gfx_glyph::{GlyphBrushBuilder, Section};

// dejavu is built as default `FontId(0)`
let dejavu: &[u8] = include_bytes!("../../fonts/DejaVuSans.ttf");
let mut glyph_brush = GlyphBrushBuilder::using_font_bytes(dejavu).build(gfx_factory.clone());

// 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.

Trait Implementations

impl<R: Resources, F: Factory<R>, H> Debug for GlyphBrush<'_, R, F, H>

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

Formats the value using the given formatter.

impl<'font, R: Resources, F: Factory<R>, H: BuildHasher> GlyphCruncher<'font> for GlyphBrush<'font, R, F, 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.

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, S, 'b>(
    &'b mut self,
    section: S
) -> Map<Iter<'b, (PositionedGlyph<'font>, [f32; 4], FontId)>, fn(_: &'b (PositionedGlyph<'font>, [f32; 4], FontId)) -> &'b PositionedGlyph<'font>>where
    S: Into<Cow<'a, VariedSection<'a>>>,

Returns an iterator over the PositionedGlyphs of the given section.