Minimal Font Families, Font Queries, Collections, System Fonts, Stretch, and Slant support (#22156)

# Objective

Implement support for the remaining missing text features with minimal
changes.

## Solution

`TextFont` has been expanded to include new fields:
```rust
pub struct TextFont {
    pub font: FontSource,
    pub font_size: f32,
    pub weight: FontWeight,
    pub width: FontWidth,
    pub style: FontStyle,
    pub font_smoothing: FontSmoothing,
    pub font_features: FontFeatures,
}
```

FontSource has two variants: Handle, which identifies a font by asset
handle, and Family, which selects a font by its family name.

`FontWidth` is a newtype struct representing OpenType font stretch
classifications ranging from ULTRA_CONDENSED (50%) to ULTRA_EXPANDED
(200%).

`FontStyle` is an enum used to set the slant style of a font, either
`Normal`, `Italic`, or `Oblique`.

The system font support is very barebones. You load them using the
`CosmicFontSystem` resource:
```rust
font_system.db_mut().load_system_fonts()
```
Then they are available to be selected by family name using
`FontSource::Family`.

### Other changes

* `TextPipelines`'s `glyph_info` field has been removed. There is no
need to collect the section infos or perform any querys during text
layout updates, so that code has been removed as well.

* `update_text_layout_info` used some `try_for_each` with some nested
closures which was unnecessarily complicated again. They've been
replaced with a regular for loop.

* After font assets are loaded there's a new system
`load_font_assets_into_fontdb_system` that automatically adds them to
cosmic text's font database. Then they are available to be looked up by
family name as well as by asset handle.

* There aren't are performance motivated changes but layout updates seem
to be overall significantly more efficient now, with a slight regression
for very large numbers of short, single section text entities.

* Font texture atlases are no longer automatically cleared when the font
asset they were generated from is removed. There is no way to remove
individual fonts from cosmic text's `FontSystem`, so the font is still
accessible using the family name with `FontSource::family` and removing
the text atlases naively could cause a panic since rendering expects
them to be present.

## Testing

```
cargo run --example font_query
```
---

## Showcase

<img width="1229" height="591" alt="font-query"
src="https://github.com/user-attachments/assets/23f5aaa2-fdb8-4448-9b4e-9d65d6431107"
/>

---------

Co-authored-by: Thierry Berger <[email protected]>

Author: ickshonpe

Cargo.toml

@@ -3688,6 +3688,17 @@ description = "Demonstrates dragging and dropping UI nodes"
 category = "UI (User Interface)"
 wasm = true
 
+[[example]]
+name = "font_query"
+path = "examples/ui/font_query.rs"
+doc-scrape-examples = true
+
+[package.metadata.example.font_query]
+name = "Font Queries"
+description = "Demonstrates font querying"
+category = "UI (User Interface)"
+wasm = true
+
 [[example]]
 name = "display_and_visibility"
 path = "examples/ui/display_and_visibility.rs"

crates/bevy_feathers/src/font_styles.rs

@@ -58,7 +58,7 @@ pub(crate) fn on_changed_font(
         }
     {
         commands.entity(insert.entity).insert(Propagate(TextFont {
-            font,
+            font: font.into(),
             font_size: style.font_size,
             ..Default::default()
         }));

crates/bevy_sprite/src/lib.rs

@@ -84,12 +84,11 @@ impl Plugin for SpritePlugin {
             PostUpdate,
             (
                 bevy_text::detect_text_needs_rerender::<Text2d>,
-                update_text2d_layout
-                    .after(bevy_camera::CameraUpdateSystems)
-                    .after(bevy_text::free_unused_font_atlases_system),
+                update_text2d_layout.after(bevy_camera::CameraUpdateSystems),
                 calculate_bounds_text2d.in_set(VisibilitySystems::CalculateBounds),
             )
                 .chain()
+                .after(bevy_text::load_font_assets_into_fontdb_system)
                 .in_set(bevy_text::Text2dUpdateSystems)
                 .after(bevy_app::AnimationSystems),
         );

crates/bevy_sprite/src/text2d.rs

@@ -179,7 +179,6 @@ pub fn update_text2d_layout(
         &mut ComputedTextBlock,
         Ref<FontHinting>,
     )>,
-    text_font_query: Query<&TextFont>,
     mut text_reader: Text2dReader,
     mut font_system: ResMut<CosmicFontSystem>,
     mut swash_cache: ResMut<SwashCache>,
@@ -275,8 +274,6 @@ pub fn update_text2d_layout(
 
         match text_pipeline.update_text_layout_info(
             &mut text_layout_info,
-            text_font_query,
-            scale_factor as f64,
             &mut font_atlas_set,
             &mut texture_atlases,
             &mut textures,

crates/bevy_text/Cargo.toml

@@ -34,6 +34,7 @@ cosmic-text = { version = "0.16", features = ["shape-run-cache"] }
 thiserror = { version = "2", default-features = false }
 serde = { version = "1", features = ["derive"] }
 smallvec = { version = "1", default-features = false }
+smol_str = { version = "0.2", default-features = false }
 sys-locale = "0.3.0"
 tracing = { version = "0.1", default-features = false, features = ["std"] }
 

crates/bevy_text/src/font.rs

@@ -1,9 +1,19 @@
 use alloc::sync::Arc;
 
 use bevy_asset::Asset;
+use bevy_asset::AssetEvent;
+use bevy_asset::Assets;
+use bevy_ecs::message::MessageReader;
+use bevy_ecs::system::Query;
+use bevy_ecs::system::ResMut;
 use bevy_reflect::TypePath;
+use cosmic_text::fontdb::ID;
 use cosmic_text::skrifa::raw::ReadError;
 use cosmic_text::skrifa::FontRef;
+use smallvec::SmallVec;
+
+use crate::ComputedTextBlock;
+use crate::CosmicFontSystem;
 
 /// An [`Asset`] that contains the data for a loaded font, if loaded as an asset.
 ///
@@ -21,6 +31,8 @@ use cosmic_text::skrifa::FontRef;
 pub struct Font {
     /// Content of a font file as bytes
     pub data: Arc<Vec<u8>>,
+    /// Ids for fonts in font file
+    pub ids: SmallVec<[ID; 8]>,
 }
 
 impl Font {
@@ -29,6 +41,38 @@ impl Font {
         let _ = FontRef::from_index(&font_data, 0)?;
         Ok(Self {
             data: Arc::new(font_data),
+            ids: SmallVec::new(),
         })
     }
 }
+
+/// Add new font assets to the font system's database.
+pub fn load_font_assets_into_fontdb_system(
+    mut fonts: ResMut<Assets<Font>>,
+    mut events: MessageReader<AssetEvent<Font>>,
+    mut cosmic_font_system: ResMut<CosmicFontSystem>,
+    mut text_block_query: Query<&mut ComputedTextBlock>,
+) {
+    let mut new_fonts_added = false;
+    let font_system = &mut cosmic_font_system.0;
+    for event in events.read() {
+        if let AssetEvent::Added { id } = event
+            && let Some(font) = fonts.get_mut(*id)
+        {
+            let data = Arc::clone(&font.data);
+            font.ids = font_system
+                .db_mut()
+                .load_font_source(cosmic_text::fontdb::Source::Binary(data))
+                .into_iter()
+                .collect();
+            new_fonts_added = true;
+        }
+    }
+
+    // Whenever new fonts are added, update all text blocks so they use the new fonts.
+    if new_fonts_added {
+        for mut block in text_block_query.iter_mut() {
+            block.needs_rerender = true;
+        }
+    }
+}

crates/bevy_text/src/font_atlas_set.rs

@@ -1,32 +1,22 @@
-use crate::{Font, FontAtlas, FontSmoothing, TextFont};
-use bevy_asset::{AssetEvent, AssetId};
+use crate::{FontAtlas, FontSmoothing};
 use bevy_derive::{Deref, DerefMut};
-use bevy_ecs::{message::MessageReader, resource::Resource, system::ResMut};
+use bevy_ecs::resource::Resource;
 use bevy_platform::collections::HashMap;
+use cosmic_text::fontdb::ID;
 
 /// Identifies the font atlases for a particular font in [`FontAtlasSet`]
 ///
 /// Allows an `f32` font size to be used as a key in a `HashMap`, by its binary representation.
 #[derive(Debug, Hash, PartialEq, Eq, Clone, Copy)]
 pub struct FontAtlasKey {
     /// Font asset id
-    pub id: AssetId<Font>,
+    pub id: ID,
     /// Font size via `f32::to_bits`
     pub font_size_bits: u32,
     /// Antialiasing method
     pub font_smoothing: FontSmoothing,
 }
 
-impl From<&TextFont> for FontAtlasKey {
-    fn from(font: &TextFont) -> Self {
-        Self {
-            id: font.font.id(),
-            font_size_bits: font.font_size.to_bits(),
-            font_smoothing: font.font_smoothing,
-        }
-    }
-}
-
 /// Set of rasterized fonts stored in [`FontAtlas`]es.
 #[derive(Debug, Default, Resource, Deref, DerefMut)]
 pub struct FontAtlasSet(HashMap<FontAtlasKey, Vec<FontAtlas>>);
@@ -38,15 +28,3 @@ impl FontAtlasSet {
             .is_some_and(|font_atlas| font_atlas.iter().any(|atlas| atlas.has_glyph(cache_key)))
     }
 }
-
-/// A system that automatically frees unused texture atlases when a font asset is removed.
-pub fn free_unused_font_atlases_system(
-    mut font_atlas_sets: ResMut<FontAtlasSet>,
-    mut font_events: MessageReader<AssetEvent<Font>>,
-) {
-    for event in font_events.read() {
-        if let AssetEvent::Removed { id } = event {
-            font_atlas_sets.retain(|key, _| key.id != *id);
-        }
-    }
-}

crates/bevy_text/src/lib.rs

@@ -42,6 +42,7 @@ mod pipeline;
 mod text;
 mod text_access;
 
+use bevy_asset::AssetEventSystems;
 pub use bounds::*;
 pub use error::*;
 pub use font::*;
@@ -59,13 +60,14 @@ pub use text_access::*;
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::{
-        Font, FontHinting, FontWeight, Justify, LineBreak, Strikethrough, StrikethroughColor,
-        TextColor, TextError, TextFont, TextLayout, TextSpan, Underline, UnderlineColor,
+        Font, FontHinting, FontSource, FontStyle, FontWeight, FontWidth, Justify, LineBreak,
+        Strikethrough, StrikethroughColor, TextColor, TextError, TextFont, TextLayout, TextSpan,
+        Underline, UnderlineColor,
     };
 }
 
 use bevy_app::prelude::*;
-use bevy_asset::{AssetApp, AssetEventSystems};
+use bevy_asset::AssetApp;
 use bevy_ecs::prelude::*;
 
 /// The raw data for the default font used by `bevy_text`
@@ -94,7 +96,7 @@ impl Plugin for TextPlugin {
             .init_resource::<TextIterScratch>()
             .add_systems(
                 PostUpdate,
-                free_unused_font_atlases_system.before(AssetEventSystems),
+                load_font_assets_into_fontdb_system.after(AssetEventSystems),
             )
             .add_systems(Last, trim_cosmic_cache);