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 GlyphCaches (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§

  • GlyphCache
    Rasterizes and caches glyphs for a specific font / size combination.
  • Text
    Description of how an owned String should be rendered as a text mesh.
  • TextBuilder
    Builder for creating models from a slice of TextRef’s.
  • TextBuilderSettings
    Controls the behaviour of a TextBuilder and its corresponding GlyphCaches.
  • TextMaterial
    A single channel material storing rasterized font glyphs.
  • TextMesh
    A simple mesh geometry rendering mulitple rasterized font glyphs.
  • TextRef
    Description of how a string slice should be rendered as a text mesh.

Enums§