Crate three_d_text_builder
source ·Expand description
Glyph atlas based text rendering for the three-d crate, using fontdue.
This crate’s aim is to provide decent performance and quality of the rendered text.
It is suited for both large static text elements as well as dynamically formatted text that quickly changes.
§Quick Example
// Create a text builder from a TTF font
let mut text_builder = TextBuilder::new(
&include_str!("font.ttf"),
TextBuilderSettings::default()
).unwrap();
// Create some text
let text = TextRef {
// The text to render
text: "The quick brown fox jumps over the lazy dog",
// Set the color
color: Srgba::RED,
// Align to the lower center edge of the viewport
align: TextAlign::Viewport(0, -1),
// Add some padding
padding: vec2(0.0, 8.0),
// Move up by 25% of the viewport's height
position: TextPosition::Percentage(vec2(0.0, 0.25)),
// Add a simple shadow effect
shadow: Some((Srgba::BLACK, vec2(1.0, -1.0))),
..Default::default()
};
// Build a 3D model for our text - this could also be cached for later usage
// to avoid building the same model multiple times
let text_model = text_builder.build(&context, &[text]);
// Setup the viewport so our alignment works as expected
text_builder.set_viewport(viewport);
// Then render it to a target
render_target.render(&camera, text_model, &[]);
For more use cases, check out the standalone examples.
§Implementation Notes
Each TextBuilder
uses a set of GlyphCache
s (one for each font size)
which produce materials from their glyph atlases. These get mapped to
the UVs of generated character quads, which in turn get combined into a
set of meshes. Text meshes that share the same underlying atlas material
get combined into a single mesh in order to improve drawing performance.
In addition, a copy on write approach is employed to keep the number of uploaded GPU materials to a minimum, while also allow generated models to be cached by the application code.
Structs§
- Rasterizes and caches glyphs for a specific font / size combination.
- Description of how an owned String should be rendered as a text mesh.
- Builder for creating models from a slice of
TextRef
’s. - Controls the behaviour of a
TextBuilder
and its correspondingGlyphCache
s. - A single channel material storing rasterized font glyphs.
- A simple mesh geometry rendering mulitple rasterized font glyphs.
- Description of how a string slice should be rendered as a text mesh.