Struct glyph_brush::GlyphBrush
source · pub struct GlyphBrush<V, X = Extra, F = FontArc, H = DefaultSectionHasher> { /* private fields */ }
Expand description
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 GlyphCruncher::glyph_bounds
.
Generic types
V
A single glyph’s vertex data type that matches, or is inferred by, theto_vertex
function given to theGlyphBrush::process_queued
call.X
Extra non-layout data for use in vertex generation. DefaultExtra
.F
ab-glyph font type. Generally inferred by builder usage. DefaultFontArc
.H
Section hasher used for cache matching. SeeGlyphBrushBuilder::section_hasher
. DefaultDefaultSectionHasher
.
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
.
Implementations§
source§impl<F, V, X, H: BuildHasher> GlyphBrush<V, X, F, H>
impl<F, V, X, H: BuildHasher> GlyphBrush<V, X, F, H>
source§impl<F, V, X, H> GlyphBrush<V, X, F, H>where
F: Font,
X: Clone + Hash,
V: Clone + 'static,
H: BuildHasher,
impl<F, V, X, H> GlyphBrush<V, X, F, H>where F: Font, X: Clone + Hash, V: Clone + 'static, H: BuildHasher,
sourcepub 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>>>,
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.
sourcepub fn queue<'a, S>(&mut self, section: S)where
X: 'a,
S: Into<Cow<'a, Section<'a, X>>>,
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")));
sourcepub fn queue_pre_positioned(
&mut self,
glyphs: Vec<SectionGlyph>,
extra: Vec<X>,
bounds: Rect
)
pub fn queue_pre_positioned( &mut self, glyphs: Vec<SectionGlyph>, extra: Vec<X>, bounds: Rect )
Queues pre-positioned glyphs to be processed by the next call of
process_queued
. Can be called multiple
times.
sourcepub fn resize_texture(&mut self, new_width: u32, new_height: u32)
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);
sourcepub fn texture_dimensions(&self) -> (u32, u32)
pub fn texture_dimensions(&self) -> (u32, u32)
Returns the logical texture cache pixel dimensions (width, height)
.
sourcepub fn keep_cached_custom_layout<'a, S, G>(
&mut self,
section: S,
custom_layout: &G
)where
S: Into<Cow<'a, Section<'a, X>>>,
G: GlyphPositioner,
X: 'a,
pub fn keep_cached_custom_layout<'a, S, G>( &mut self, section: S, custom_layout: &G )where S: Into<Cow<'a, Section<'a, X>>>, G: GlyphPositioner, X: '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.
sourcepub fn keep_cached<'a, S>(&mut self, section: S)where
S: Into<Cow<'a, Section<'a, X>>>,
X: 'a,
pub fn keep_cached<'a, S>(&mut self, section: S)where S: Into<Cow<'a, Section<'a, X>>>, X: '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.
source§impl<F, V, X, H> GlyphBrush<V, X, F, H>where
F: Font + Sync,
X: Clone + Hash + PartialEq,
V: Clone + 'static,
H: BuildHasher,
impl<F, V, X, H> GlyphBrush<V, X, F, H>where F: Font + Sync, X: Clone + Hash + PartialEq, V: Clone + 'static, H: BuildHasher,
sourcepub 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,
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 singleu8
alpha value per pixel.to_vertex
maps a single glyph’sGlyphVertex
data into a generic vertex type. The mapped vertices are returned in anOk(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),
)?
sourcepub fn is_draw_cached(&self, font_id: FontId, glyph: &Glyph) -> bool
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.
source§impl<F: Font + Clone, V, X, H: BuildHasher + Clone> GlyphBrush<V, X, F, H>
impl<F: Font + Clone, V, X, H: BuildHasher + Clone> GlyphBrush<V, X, F, H>
sourcepub fn to_builder(&self) -> GlyphBrushBuilder<F, H>
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§
source§impl<F, V, X, H> Debug for GlyphBrush<V, X, F, H>
impl<F, V, X, H> Debug for GlyphBrush<V, X, F, H>
source§impl<F, V, X, H> GlyphCruncher<F, X> for GlyphBrush<V, X, F, H>where
X: Clone + Hash,
F: Font,
V: Clone + 'static,
H: BuildHasher,
impl<F, V, X, H> GlyphCruncher<F, X> for GlyphBrush<V, X, F, H>where X: Clone + Hash, F: Font, V: Clone + 'static, H: BuildHasher,
source§fn glyphs_custom_layout<'a, 'b, S, L>(
&'b mut self,
section: S,
custom_layout: &L
) -> SectionGlyphIter<'b>where
X: 'a,
L: GlyphPositioner + Hash,
S: Into<Cow<'a, Section<'a, X>>>,
fn glyphs_custom_layout<'a, 'b, S, L>( &'b mut self, section: S, custom_layout: &L ) -> SectionGlyphIter<'b>where X: 'a, L: GlyphPositioner + Hash, S: Into<Cow<'a, Section<'a, X>>>,
PositionedGlyph
s of the given section with a custom layout. Read more