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 bevy_sprite::text2d::update_text2d_layout system (in a 2d world space context) passes it into TextPipeline::update_text_layout_info, which:

1. updates a Layout from the TextSpans, generating new FontAtlases if necessary.
2. iterates over each glyph in the Layout 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.

Modules

prelude

The text prelude.

Structs

ComputedTextBlock

Computed information for a text block.

EditableText

A plain-text text input field.

EditableTextFilter

Sets a per-character filter for this text input. Insert and paste edits are ignored if the filter rejects any character.

EditableTextGeneration

Wrapper around a parley::Generation. Used to track when TextLayoutInfo is stale and needs reupdating. The initial Generation of the PlainEditor is not equal to the default Generation value, so the TextLayoutInfo will always be given an initial update.

EditableTextSystems

System set where EditableText::pending_edits are applied.

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 the font atlases for a particular font in FontAtlasSet

FontAtlasSet

Set of rasterized fonts stored in FontAtlases.

FontCx

A font database and cache, used for font family resolution and text layout.

FontFeatureTag

An OpenType font feature tag.

FontFeatures

OpenType features for .otf fonts that support them.

FontFeaturesBuilder

A builder for FontFeatures.

FontLoader

An AssetLoader for Fonts, for use by the AssetServer

FontVariationTag

An OpenType font variation tag.

FontVariations

OpenType font variations for variable fonts that support them.

FontVariationsBuilder

A builder for FontVariations.

FontWeight

How thick or bold the strokes of a font appear.

FontWidth

The visual width of a font as a ratio of its normal width, typically 0.5 to 2.0. <https://docs.microsoft.com/en-us/typography/opentype/spec/os2#uswidthclass>

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.

GlyphCacheKey

Key identifying a glyph

LayoutCx

Text layout context

PositionedGlyph

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

PreeditCursor

A selection within IME preedit text, expressed as byte offsets from the start of the preedit.

RemSize

Base value used to resolve Rem units for font sizes.

RunGeometry

Geometry of a text run used to render text decorations like background colors, strikethrough, and underline. A run in bevy_text is a contiguous sequence of glyphs on a line that share the same text attributes like font, font size, and line height.

ScaleCx

Text scaler context

Strikethrough

A text entity with this component is drawn with strikethrough.

StrikethroughColor

Color for the text’s strikethrough. If this component is not present, its TextColor will be used.

Text2dUpdateSystems

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

TextBackgroundColor

The background color of the text for this section.

TextBounds

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

TextBrush

Per-section metadata attached to shaped text runs.

TextColor

The color of the text for this section.

TextCursorStyle

Controls text cursor appearance.

TextEditChange

Triggered after applying all pending TextEdits to the EditableText by apply_text_edits.

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, the line height, and the antialiasing method.

TextFontTemplate

TextIterScratch

Scratch buffer used to store intermediate state when iterating over text spans.

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.

Underline

Add to a text entity to draw its text with underline.

UnderlineColor

Color for the text’s underline. If this component is not present, its TextColor will be used.

Enums

FontHinting

Font hinting strategy, which controls the rasterization for fonts.

FontLoaderError

Possible errors that can be produced by FontLoader

FontSize

The vertical height of rasterized glyphs in the font atlas in pixels.

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.

FontSource

Determines how the font face for a text sections is selected.

FontSourceTemplate

FontStyle

The slant style of a font face: normal, italic, or oblique.

Justify

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

LetterSpacing

Specifies the space between each letter of text for Text and Text2d

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

TextEdit

Deferred text input edit and navigation actions applied by the apply_text_edits system.

TextError

Errors related to the textsystem

Constants

DEFAULT_FONT_DATA

The raw data for the default font used by bevy_text

Traits

TextSection

Helper trait for using the TextReader and TextWriter system params.

Functions

add_glyph_to_atlas

Adds the given subpixel-offset glyph to the given font atlases

apply_text_edits

Applies pending text edit actions to all EditableText widgets.

detect_text_needs_rerender

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

get_glyph_atlas_info

Generates the GlyphAtlasInfo for the given subpixel-offset glyph.

get_outlined_glyph_texture

Get the texture of the glyph as a rendered image, and its offset

load_font_assets_into_font_collection

Add new font assets to the internal font collection, and set any associated TextFont’s changed. If any fonts are removed, the font collection is completely rebuilt, the generic families are remapped, and all TextFonts are set changed.

resolve_font_source

Resolve a TextFont’s FontSource to a font family.