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::queue_text`], which:
25//!
26//! 1. updates a [`Buffer`](cosmic_text::Buffer) from the [`TextSpan`]s, generating new [`FontAtlasSet`]s 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, Justify, LineBreak, TextColor, TextError, TextFont, TextLayout, TextSpan,
63    };
64}
65
66use bevy_app::prelude::*;
67use bevy_asset::{AssetApp, AssetEventSystems};
68use bevy_ecs::prelude::*;
69
70/// The raw data for the default font used by `bevy_text`
71#[cfg(feature = "default_font")]
72pub const DEFAULT_FONT_DATA: &[u8] = include_bytes!("FiraMono-subset.ttf");
73
74/// Adds text rendering support to an app.
75///
76/// When the `bevy_text` feature is enabled with the `bevy` crate, this
77/// plugin is included by default in the `DefaultPlugins`.
78#[derive(Default)]
79pub struct TextPlugin;
80
81/// System set in [`PostUpdate`] where all 2d text update systems are executed.
82#[derive(Debug, Hash, PartialEq, Eq, Clone, SystemSet)]
83pub struct Text2dUpdateSystems;
84
85/// Deprecated alias for [`Text2dUpdateSystems`].
86#[deprecated(since = "0.17.0", note = "Renamed to `Text2dUpdateSystems`.")]
87pub type Update2dText = Text2dUpdateSystems;
88
89impl Plugin for TextPlugin {
90    fn build(&self, app: &mut App) {
91        app.init_asset::<Font>()
92            .init_asset_loader::<FontLoader>()
93            .init_resource::<FontAtlasSets>()
94            .init_resource::<TextPipeline>()
95            .init_resource::<CosmicFontSystem>()
96            .init_resource::<SwashCache>()
97            .init_resource::<TextIterScratch>()
98            .add_systems(
99                PostUpdate,
100                remove_dropped_font_atlas_sets.before(AssetEventSystems),
101            )
102            .add_systems(Last, trim_cosmic_cache);
103
104        #[cfg(feature = "default_font")]
105        {
106            use bevy_asset::{AssetId, Assets};
107            let mut assets = app.world_mut().resource_mut::<Assets<_>>();
108            let asset = Font::try_from_bytes(DEFAULT_FONT_DATA.to_vec()).unwrap();
109            assets.insert(AssetId::default(), asset).unwrap();
110        };
111    }
112}
bevy_text/lib.rs

bevy_text/
lib.rs
