From 0db999c795bb7f34885ddbb5438288486aae6f31 Mon Sep 17 00:00:00 2001 From: Bruce Mitchener Date: Sat, 28 Oct 2023 01:53:57 +0700 Subject: [PATCH] Add some more docs for bevy_text. (#9873) # Objective - Have more docs for `bevy_text` to avoid reading the source code for some things. ## Solution - Add some additional docs. ## Changelog - `TextSettings.max_font_atlases` in `bevy_text` has been renamed to ` TextSettings.soft_max_font_atlases`. ## Migration Guide - Usages of `TextSettings.max_font_atlases` from `bevy_text` must be changed to `TextSettings.soft_max_font_atlases`. --- crates/bevy_text/src/glyph_brush.rs | 4 ++-- crates/bevy_text/src/lib.rs | 22 +++++++++++++++------- crates/bevy_text/src/text2d.rs | 5 ++++- errors/B0005.md | 2 +- 4 files changed, 22 insertions(+), 11 deletions(-) diff --git a/crates/bevy_text/src/glyph_brush.rs b/crates/bevy_text/src/glyph_brush.rs index 9aab58ee97..a00d71a779 100644 --- a/crates/bevy_text/src/glyph_brush.rs +++ b/crates/bevy_text/src/glyph_brush.rs @@ -115,9 +115,9 @@ impl GlyphBrush { if !text_settings.allow_dynamic_font_size && !font_atlas_warning.warned - && font_atlas_set.len() > text_settings.max_font_atlases.get() + && font_atlas_set.len() > text_settings.soft_max_font_atlases.get() { - warn!("warning[B0005]: Number of font atlases has exceeded the maximum of {}. Performance and memory usage may suffer.", text_settings.max_font_atlases.get()); + warn!("warning[B0005]: Number of font atlases has exceeded the maximum of {}. Performance and memory usage may suffer.", text_settings.soft_max_font_atlases.get()); font_atlas_warning.warned = true; } diff --git a/crates/bevy_text/src/lib.rs b/crates/bevy_text/src/lib.rs index 024dc663f7..6a1981fa61 100644 --- a/crates/bevy_text/src/lib.rs +++ b/crates/bevy_text/src/lib.rs @@ -34,15 +34,21 @@ use bevy_render::{camera::CameraUpdateSystem, ExtractSchedule, RenderApp}; use bevy_sprite::SpriteSystem; use std::num::NonZeroUsize; +/// Adds text rendering support to an app. +/// +/// When the `bevy_text` feature is enabled with the `bevy` crate, this +/// plugin is included by default in the `DefaultPlugins`. #[derive(Default)] pub struct TextPlugin; -/// [`TextPlugin`] settings +/// Settings used to configure the [`TextPlugin`]. #[derive(Resource)] pub struct TextSettings { - /// Maximum number of font atlases supported in a [`FontAtlasSet`]. - pub max_font_atlases: NonZeroUsize, - /// Allows font size to be set dynamically exceeding the amount set in `max_font_atlases`. + /// Soft maximum number of font atlases supported in a [`FontAtlasSet`]. When this is exceeded, + /// a warning will be emitted a single time. The [`FontAtlasWarning`] resource ensures that + /// this only happens once. + pub soft_max_font_atlases: NonZeroUsize, + /// Allows font size to be set dynamically exceeding the amount set in `soft_max_font_atlases`. /// Note each font size has to be generated which can have a strong performance impact. pub allow_dynamic_font_size: bool, } @@ -50,19 +56,21 @@ pub struct TextSettings { impl Default for TextSettings { fn default() -> Self { Self { - max_font_atlases: NonZeroUsize::new(16).unwrap(), + soft_max_font_atlases: NonZeroUsize::new(16).unwrap(), allow_dynamic_font_size: false, } } } +/// This resource tracks whether or not a warning has been emitted due to the number +/// of font atlases exceeding the [`TextSettings::soft_max_font_atlases`] setting. #[derive(Resource, Default)] pub struct FontAtlasWarning { warned: bool, } -/// Text is rendered for two different view projections, normal `Text2DBundle` is rendered with a -/// `BottomToTop` y axis, and UI is rendered with a `TopToBottom` y axis. This matters for text because +/// Text is rendered for two different view projections, a [`Text2dBundle`] is rendered 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. pub enum YAxisOrientation { TopToBottom, diff --git a/crates/bevy_text/src/text2d.rs b/crates/bevy_text/src/text2d.rs index ffb285deba..b4208176f6 100644 --- a/crates/bevy_text/src/text2d.rs +++ b/crates/bevy_text/src/text2d.rs @@ -78,6 +78,8 @@ pub struct Text2dBundle { pub text_layout_info: TextLayoutInfo, } +/// This system extracts the sprites from the 2D text components and adds them to the +/// "render world". pub fn extract_text2d_sprite( mut commands: Commands, mut extracted_sprites: ResMut, @@ -148,7 +150,7 @@ pub fn extract_text2d_sprite( } /// Updates the layout and size information whenever the text or style is changed. -/// This information is computed by the `TextPipeline` on insertion, then stored. +/// This information is computed by the [`TextPipeline`] on insertion, then stored. /// /// ## World Resources /// @@ -222,6 +224,7 @@ pub fn update_text2d_layout( } } +/// Scales `value` by `factor`. pub fn scale_value(value: f32, factor: f64) -> f32 { (value as f64 * factor) as f32 } diff --git a/errors/B0005.md b/errors/B0005.md index 16b198f5e2..57fa6e94a6 100644 --- a/errors/B0005.md +++ b/errors/B0005.md @@ -6,4 +6,4 @@ Separate font atlases are created for each font and font size. This is expensive If you need to smoothly scale font size, use `Transform::scale`. -You can disable this warning by setting `TextSettings::allow_dynamic_font_size` to `true` or raise the limit by setting `TextSettings::max_font_atlases`. +You can disable this warning by setting `TextSettings::allow_dynamic_font_size` to `true` or raise the limit by setting `TextSettings::soft_max_font_atlases`.