Struct webgl2_glyph::glyph_brush::GlyphBrush [−][src]
pub struct GlyphBrush<V, X = Extra, F = FontArc, H = RandomXxHashBuilder64> { /* fields omitted */ }
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
impl<F, V, X, H> GlyphBrush<V, X, F, H> where
F: Font,
X: Clone + Hash,
V: 'static + Clone,
H: BuildHasher,
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>>>,
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.
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
)
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.
Rebuilds the logical texture cache with new dimensions. Should be avoided if possible.
Example
glyph_brush.resize_texture(512, 512);
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,
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.
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,
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,
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),
)?
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.
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> GlyphCruncher<F, X> for GlyphBrush<V, X, F, H> where
X: Clone + Hash,
F: Font,
V: 'static + Clone,
H: BuildHasher,
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>>>,
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 PositionedGlyph
s of the given section with a custom layout. Read more
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>>>,
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. Read more
Returns the available fonts. Read more
Returns an iterator over the PositionedGlyph
s of the given section. Read more