bevy_text/
lib.rs

1//! This crate provides the tools for positioning and rendering text in Bevy.
2//!
3//! # `Font`
4//!
5//! Fonts contain information for drawing glyphs, which are shapes that typically represent a single character,
6//! but in some cases part of a "character" (grapheme clusters) or more than one character (ligatures).
7//!
8//! A font *face* is part of a font family,
9//! and is distinguished by its style (e.g. italic), its weight (e.g. bold) and its stretch (e.g. condensed).
10//!
11//! In Bevy, [`Font`]s are loaded by the [`FontLoader`] as [assets](bevy_asset::AssetPlugin).
12//!
13//! # `TextPipeline`
14//!
15//! The [`TextPipeline`] resource does all of the heavy lifting for rendering text.
16//!
17//! UI `Text` is first measured by creating a [`TextMeasureInfo`] in [`TextPipeline::create_text_measure`],
18//! which is called by the `measure_text_system` system of `bevy_ui`.
19//!
20//! Note that text measurement is only relevant in a UI context.
21//!
22//! With the actual text bounds defined, the `bevy_ui::widget::text::text_system` system (in a UI context)
23//! or `bevy_sprite::text2d::update_text2d_layout` system (in a 2d world space context)
24//! passes it into [`TextPipeline::update_text_layout_info`], which:
25//!
26//! 1. updates a [`Buffer`](cosmic_text::Buffer) from the [`TextSpan`]s, generating new [`FontAtlas`]es if necessary.
27//! 2. iterates over each glyph in the [`Buffer`](cosmic_text::Buffer) to create a [`PositionedGlyph`],
28//!    retrieving glyphs from the cache, or rasterizing to a [`FontAtlas`] if necessary.
29//! 3. [`PositionedGlyph`]s are stored in a [`TextLayoutInfo`],
30//!    which contains all the information that downstream systems need for rendering.
31
32extern crate alloc;
33
34mod bounds;
35mod error;
36mod font;
37mod font_atlas;
38mod font_atlas_set;
39mod font_loader;
40mod glyph;
41mod pipeline;
42mod text;
43mod text_access;
44
45pub use bounds::*;
46pub use error::*;
47pub use font::*;
48pub use font_atlas::*;
49pub use font_atlas_set::*;
50pub use font_loader::*;
51pub use glyph::*;
52pub use pipeline::*;
53pub use text::*;
54pub use text_access::*;
55
56/// The text prelude.
57///
58/// This includes the most common types in this crate, re-exported for your convenience.
59pub mod prelude {
60    #[doc(hidden)]
61    pub use crate::{
62        Font, FontWeight, Justify, LineBreak, Strikethrough, StrikethroughColor, TextColor,
63        TextError, TextFont, TextLayout, TextSpan, Underline, UnderlineColor,
64    };
65}
66
67use bevy_app::prelude::*;
68use bevy_asset::{AssetApp, AssetEventSystems};
69use bevy_ecs::prelude::*;
70
71/// The raw data for the default font used by `bevy_text`
72#[cfg(feature = "default_font")]
73pub const DEFAULT_FONT_DATA: &[u8] = include_bytes!("FiraMono-subset.ttf");
74
75/// Adds text rendering support to an app.
76///
77/// When the `bevy_text` feature is enabled with the `bevy` crate, this
78/// plugin is included by default in the `DefaultPlugins`.
79#[derive(Default)]
80pub struct TextPlugin;
81
82/// System set in [`PostUpdate`] where all 2d text update systems are executed.
83#[derive(Debug, Hash, PartialEq, Eq, Clone, SystemSet)]
84pub struct Text2dUpdateSystems;
85
86impl Plugin for TextPlugin {
87    fn build(&self, app: &mut App) {
88        app.init_asset::<Font>()
89            .init_asset_loader::<FontLoader>()
90            .init_resource::<FontAtlasSet>()
91            .init_resource::<TextPipeline>()
92            .init_resource::<CosmicFontSystem>()
93            .init_resource::<SwashCache>()
94            .init_resource::<TextIterScratch>()
95            .add_systems(
96                PostUpdate,
97                free_unused_font_atlases_system.before(AssetEventSystems),
98            )
99            .add_systems(Last, trim_cosmic_cache);
100
101        #[cfg(feature = "default_font")]
102        {
103            use bevy_asset::{AssetId, Assets};
104            let mut assets = app.world_mut().resource_mut::<Assets<_>>();
105            let asset = Font::try_from_bytes(DEFAULT_FONT_DATA.to_vec()).unwrap();
106            assets.insert(AssetId::default(), asset).unwrap();
107        };
108    }
109}
bevy_text/lib.rs

bevy_text/
lib.rs
