Crate bevy_text

This crate provides the tools for positioning and rendering text in Bevy.

Font

Fonts contain information for drawing glyphs, which are shapes that typically represent a single character, but in some cases part of a “character” (grapheme clusters) or more than one character (ligatures).

A font face is part of a font family, and is distinguished by its style (e.g. italic), its weight (e.g. bold) and its stretch (e.g. condensed).

In Bevy, Fonts are loaded by the FontLoader as assets.

TextPipeline

The TextPipeline resource does all of the heavy lifting for rendering text.

UI Text is first measured by creating a TextMeasureInfo in TextPipeline::create_text_measure, which is called by the measure_text_system system of bevy_ui.

Note that text measurement is only relevant in a UI context.

With the actual text bounds defined, the bevy_ui::widget::text::text_system system (in a UI context) or text2d::update_text2d_layout system (in a 2d world space context) passes it into TextPipeline::queue_text, which:

1. updates a Buffer from the TextSpans, generating new FontAtlasSets if necessary.
2. iterates over each glyph in the Buffer to create a PositionedGlyph, retrieving glyphs from the cache, or rasterizing to a FontAtlas if necessary.
3. PositionedGlyphs are stored in a TextLayoutInfo, which contains all the information that downstream systems need for rendering.

Re-exports

pub use cosmic_text;

Modules

prelude

The text prelude.

Structs

ComputedTextBlock

Computed information for a text block.

CosmicBuffer

Wrapper for cosmic_text::Buffer

CosmicFontSystem

A wrapper resource around a cosmic_text::FontSystem

Font

An Asset that contains the data for a loaded font, if loaded as an asset.

FontAtlas

Rasterized glyphs are cached, stored in, and retrieved from, a FontAtlas.

FontAtlasKey

Identifies a font size and smoothing method in a FontAtlasSet.

FontAtlasSet

A map of font sizes to their corresponding FontAtlases, for a given font face.

FontAtlasSets

A map of font faces to their corresponding FontAtlasSets.

FontLoader

An AssetLoader for Fonts, for use by the AssetServer

FontWeight

Specifies the weight of glyphs in the font, their degree of blackness or stroke thickness.

GlyphAtlasInfo

Information about a glyph in an atlas.

GlyphAtlasLocation

The location of a glyph in an atlas, and how it should be positioned when placed.

PositionedGlyph

A glyph of a font, typically representing a single character, positioned in screen space.

SwashCache

A wrapper resource around a cosmic_text::SwashCache

Text2d

The top-level 2D text component.

TextBounds

The maximum width and height of text. The text will wrap according to the specified size.

TextColor

The color of the text for this section.

TextEntity

A sub-entity of a ComputedTextBlock.

TextFont

TextFont determines the style of a text span within a ComputedTextBlock, specifically the font face, the font size, and the color.

TextLayout

Component with text format settings for a block of text.

TextLayoutInfo

Render information for a corresponding text block.

TextMeasureInfo

Size information for a corresponding ComputedTextBlock component.

TextPipeline

The TextPipeline is used to layout and render text blocks (see Text/Text2d).

TextPlugin

Adds text rendering support to an app.

TextReader

System parameter for reading text spans in a text block.

TextSpan

A span of text in a tree of spans.

TextSpanIter

Iterator returned by TextReader::iter.

TextWriter

System parameter for reading and writing text spans in a text block.

Update2dText

System set in PostUpdate where all 2d text update systems are executed.

Enums

FontFamily

An owned version of Family

FontLoaderError

Possible errors that can be produced by FontLoader

FontSmoothing

Determines which antialiasing method to use when rendering text. By default, text is rendered with grayscale antialiasing, but this can be changed to achieve a pixelated look.

FontStretch

A face width.

FontStyle

Allows italic or oblique faces to be selected.

JustifyText

Describes the horizontal alignment of multiple lines of text relative to each other.

LineBreak

Determines how lines will be broken when preventing text from running out of bounds.

LineHeight

Specifies the height of each line of text for Text and Text2d

TextError

Errors related to the textsystem

YAxisOrientation

Text is rendered for two different view projections; 2-dimensional text (Text2d) is rendered in “world space” with a BottomToTop Y-axis, while UI is rendered with a TopToBottom Y-axis. This matters for text because the glyph positioning is different in either layout. For TopToBottom, 0 is the top of the text, while for BottomToTop 0 is the bottom.

Constants

DEFAULT_FONT_DATA

The raw data for the default font used by bevy_text

Traits

TextRoot

Helper trait for the root text component in a text block.

TextSpanAccess

Helper trait for using the TextReader and TextWriter system params.

TextSpanComponent

Helper trait for the text span components in a text block.

Functions

calculate_bounds_text2d

System calculating and inserting an Aabb component to entities with some TextLayoutInfo and Anchor components, and without a NoFrustumCulling component.

detect_text_needs_rerender

System that detects changes to text blocks and sets ComputedTextBlock::should_rerender.

extract_text2d_sprite

This system extracts the sprites from the 2D text components and adds them to the “render world”.

remove_dropped_font_atlas_sets

A system that cleans up FontAtlasSets for removed Fonts

scale_value

Scales value by factor.

update_text2d_layout

Updates the layout and size information whenever the text or style is changed. This information is computed by the TextPipeline on insertion, then stored.

Type Aliases

Text2dReader

2d alias for TextReader.

Text2dWriter

2d alias for TextWriter.