Retain UI phase items from frame to frame, and consolidate the UI

queuing systems into one.

Although PR #24893 added retention for UI render world instances
themselves, in order to avoid re-extracting them from the main world ECS
every frame, we still recreate the `TransparentUi` phase items every
frame via `add_transient()`, which additionally removes them from the
phase at the end of every frame. This is a significant CPU time sink and
isn't the preferred pattern in Bevy nowadays.

This commit makes the UI-related phase items retained just as 3D meshes
are. All `queue_` methods in `bevy_ui_render` have been updated to walk
the list of changed and removed meshes and update elements in the
`SortedRenderPhase` only as necessary. The calls to `add_transient()`
have been removed in favor of the more modern `add_retained()`.

Additionally, all the custom queuing systems have been consolidated into
a single generic system, `queue_ui_items`. The resources that hold
extracted UI items have likewise been consolidated into a generic
`UiRenderObjects` resource. The behavior specific to each individual
item type (normal UI nodes, box shadows, gradients, etc.) has been
factored into a trait named `UiRenderObject`. This has resulted in
dramatic simplifications throughout UI rendering. See the documentation
for more information.

On `many_buttons`, this PR reduces the median frame time from 36.95 ms
to 22.78 ms, or 27 FPS to 44 FPS. The `queue_uinodes` system has gone
from 6.21 ms/frame to 15.2 μs/frame, a 409× speedup. And, because the
Rust standard library's sorting algorithm is good at sorting data that's
close to already sorted, the `sort_phase_system` time decreases from
5.17 ms/frame to 1.29 ms/frame, a 4.01× speedup.

Author: pcwalton

crates/bevy_ui_render/Cargo.toml

@@ -42,6 +42,7 @@ bytemuck = { version = "1.5", features = ["derive"] }
 derive_more = { version = "2", default-features = false, features = ["from"] }
 tracing = { version = "0.1", default-features = false, features = ["std"] }
 indexmap = { version = "2" }
+smallvec = { version = "1" }
 
 [features]
 default = ["bevy_ui_debug"]

crates/bevy_ui_render/src/box_shadow.rs

@@ -6,7 +6,6 @@ use bevy_app::prelude::*;
 use bevy_asset::*;
 use bevy_camera::visibility::InheritedVisibility;
 use bevy_color::{Alpha, ColorToComponents, LinearRgba};
-use bevy_ecs::entity::EntityIndexMap;
 use bevy_ecs::prelude::*;
 use bevy_ecs::{
     prelude::Component,
@@ -17,7 +16,7 @@ use bevy_ecs::{
 };
 use bevy_math::{vec2, Affine2, FloatOrd, Rect, Vec2};
 use bevy_mesh::VertexBufferLayout;
-use bevy_render::sync_world::{MainEntity, MainEntityHashMap, MainEntityHashSet};
+use bevy_render::sync_world::{MainEntity, MainEntityHashSet};
 use bevy_render::{
     render_phase::*,
     render_resource::{binding_types::uniform_buffer, *},
@@ -34,9 +33,12 @@ use bevy_ui::{
 use bevy_utils::default;
 use bytemuck::{Pod, Zeroable};
 
-use crate::{BoxShadowSamples, RenderUiSystems, TransparentUi, UiCameraMap};
+use crate::{
+    queue_ui_items, BoxShadowSamples, CachedCameraView, ChangedUiObject, RenderUiSystems,
+    TransparentUi, UiCameraMap, UiRenderObject, UiRenderObjects,
+};
 
-use super::{stack_z_offsets, UiCameraView, QUAD_INDICES, QUAD_VERTEX_POSITIONS};
+use super::{stack_z_offsets, QUAD_INDICES, QUAD_VERTEX_POSITIONS};
 
 /// A plugin that enables the rendering of box shadows.
 pub struct BoxShadowPlugin;
@@ -59,7 +61,7 @@ impl Plugin for BoxShadowPlugin {
                 .add_systems(
                     Render,
                     (
-                        queue_shadows.in_set(RenderSystems::Queue),
+                        queue_ui_items::<ExtractedBoxShadow>.in_set(RenderSystems::Queue),
                         prepare_shadows.in_set(RenderSystems::PrepareBindGroups),
                     ),
                 );
@@ -194,17 +196,44 @@ pub struct ExtractedBoxShadow {
     pub size: Vec2,
 }
 
-/// List of extracted shadows to be sorted and queued for rendering
-#[derive(Resource, Default)]
-pub struct ExtractedBoxShadows {
-    /// The list of box shadows grouped by their main-world entity, along with
-    /// each group's target camera entity.
-    ///
-    /// This is a two-level data structure so that we can quickly remove all box
-    /// shadows associated with a main-world entity when it changes.
-    pub box_shadows: MainEntityHashMap<(Entity, EntityIndexMap<ExtractedBoxShadow>)>,
+impl UiRenderObject for ExtractedBoxShadow {
+    type DrawFunctions = DrawBoxShadows;
+    type ViewPipelineKeyBuilder = UiBoxShadowViewPipelineKeyBuilder;
+    type ViewQueryData = Option<&'static BoxShadowSamples>;
+    type SpecializedRenderPipeline = BoxShadowPipeline;
+    type PipelineKeySystemParam = ();
+
+    fn get_sort_key(&self) -> FloatOrd {
+        FloatOrd(self.stack_index as f32 + stack_z_offsets::BOX_SHADOW)
+    }
+
+    fn create_view_pipeline_key_builder<'w, 's>(
+        box_shadow_samples: Option<&BoxShadowSamples>,
+    ) -> Self::ViewPipelineKeyBuilder {
+        UiBoxShadowViewPipelineKeyBuilder {
+            box_shadow_samples: box_shadow_samples.cloned(),
+        }
+    }
+
+    fn create_pipeline_key(
+        &self,
+        cached_camera_view: &CachedCameraView<Self::ViewPipelineKeyBuilder>,
+        _: &mut SystemParamItem<Self::PipelineKeySystemParam>,
+    ) -> Option<BoxShadowPipelineKey> {
+        Some(BoxShadowPipelineKey {
+            target_format: cached_camera_view.extracted_view.target_format,
+            samples: cached_camera_view
+                .pipeline_key_builder
+                .box_shadow_samples
+                .unwrap_or_default()
+                .0,
+        })
+    }
 }
 
+/// List of extracted shadows to be sorted and queued for rendering
+pub type ExtractedBoxShadows = UiRenderObjects<ExtractedBoxShadow>;
+
 pub fn extract_shadows(
     mut commands: Commands,
     mut extracted_box_shadows: ResMut<ExtractedBoxShadows>,
@@ -269,6 +298,7 @@ pub fn extract_shadows(
     mut nodes_processed_this_frame: Local<MainEntityHashSet>,
 ) {
     nodes_processed_this_frame.clear();
+    extracted_box_shadows.changed.clear();
 
     let mut mapping = camera_map.get_mapper();
 
@@ -281,14 +311,22 @@ pub fn extract_shadows(
     {
         let main_entity = MainEntity::from(entity);
 
-        // If there were any previous box shadows for this entity, despawn them.
-        for (render_entity, _) in extracted_box_shadows
-            .box_shadows
-            .get_mut(&main_entity)
-            .iter_mut()
-            .flat_map(|(_, shadows)| shadows.drain(..))
+        // If there were any previous box shadows for this entity, despawn them
+        // and record them as changed so the render phase entry can be removed.
+        if let Some((prev_camera_entity, mut shadows)) =
+            extracted_box_shadows.objects.remove(&main_entity)
         {
-            commands.entity(render_entity).despawn();
+            let changed = extracted_box_shadows
+                .changed
+                .entry(main_entity)
+                .or_default();
+            for (render_entity, _) in shadows.drain(..) {
+                commands.entity(render_entity).despawn();
+                changed.push(ChangedUiObject {
+                    render_entity,
+                    prev_camera_entity,
+                });
+            }
         }
 
         // Skip if no visible shadows
@@ -299,7 +337,7 @@ pub fn extract_shadows(
         let Some(extracted_camera_entity) = mapping.map(camera) else {
             continue;
         };
-        if let Some((camera_entity, _)) = extracted_box_shadows.box_shadows.get_mut(&main_entity) {
+        if let Some((camera_entity, _)) = extracted_box_shadows.objects.get_mut(&main_entity) {
             *camera_entity = extracted_camera_entity;
         }
 
@@ -347,7 +385,7 @@ pub fn extract_shadows(
             };
 
             extracted_box_shadows
-                .box_shadows
+                .objects
                 .entry(main_entity)
                 .or_insert_with(|| (extracted_camera_entity, Default::default()))
                 .1
@@ -383,81 +421,31 @@ pub fn extract_shadows(
         if nodes_processed_this_frame.contains(&main_entity) {
             continue;
         }
-        let Some((_, mut extracted_nodes)) = extracted_box_shadows.box_shadows.remove(&main_entity)
+        let Some((prev_camera_entity, mut extracted_nodes)) =
+            extracted_box_shadows.objects.remove(&main_entity)
         else {
             continue;
         };
+        let changed = extracted_box_shadows
+            .changed
+            .entry(main_entity)
+            .or_default();
         for (render_entity, _) in extracted_nodes.drain(..) {
             commands.entity(render_entity).despawn();
+            changed.push(ChangedUiObject {
+                render_entity,
+                prev_camera_entity,
+            });
         }
     }
 }
 
-#[expect(
-    clippy::too_many_arguments,
-    reason = "it's a system that needs a lot of them"
-)]
-pub fn queue_shadows(
-    extracted_box_shadows: ResMut<ExtractedBoxShadows>,
-    box_shadow_pipeline: Res<BoxShadowPipeline>,
-    mut pipelines: ResMut<SpecializedRenderPipelines<BoxShadowPipeline>>,
-    mut transparent_render_phases: ResMut<ViewSortedRenderPhases<TransparentUi>>,
-    render_views: Query<(&UiCameraView, Option<&BoxShadowSamples>), With<ExtractedView>>,
-    camera_views: Query<&ExtractedView>,
-    pipeline_cache: Res<PipelineCache>,
-    draw_functions: Res<DrawFunctions<TransparentUi>>,
-) {
-    let draw_function = draw_functions.read().id::<DrawBoxShadows>();
-    let mut current_camera_entity = Entity::PLACEHOLDER;
-    let mut current_phase = None;
-
-    for (main_entity, (extracted_camera_entity, extracted_sub_shadows)) in
-        extracted_box_shadows.box_shadows.iter()
-    {
-        if current_camera_entity != *extracted_camera_entity {
-            current_phase = render_views.get(*extracted_camera_entity).ok().and_then(
-                |(default_camera_view, shadow_samples)| {
-                    camera_views
-                        .get(default_camera_view.0)
-                        .ok()
-                        .and_then(|view| {
-                            transparent_render_phases
-                                .get_mut(&view.retained_view_entity)
-                                .map(|transparent_phase| {
-                                    let pipeline = pipelines.specialize(
-                                        &pipeline_cache,
-                                        &box_shadow_pipeline,
-                                        BoxShadowPipelineKey {
-                                            target_format: view.target_format,
-                                            samples: shadow_samples.copied().unwrap_or_default().0,
-                                        },
-                                    );
-                                    (pipeline, transparent_phase)
-                                })
-                        })
-                },
-            );
-            current_camera_entity = *extracted_camera_entity;
-        }
-
-        let Some((pipeline, transparent_phase)) = current_phase.as_mut() else {
-            continue;
-        };
-        for (entity, extracted_shadow) in extracted_sub_shadows.iter() {
-            transparent_phase.add_transient(TransparentUi {
-                draw_function,
-                pipeline: *pipeline,
-                entity: (*entity, *main_entity),
-                sort_key: FloatOrd(
-                    extracted_shadow.stack_index as f32 + stack_z_offsets::BOX_SHADOW,
-                ),
-
-                batch_range: 0..0,
-                extra_index: PhaseItemExtraIndex::None,
-                indexed: true,
-            });
-        }
-    }
+/// Information that the box shadow renderer needs from each view to construct
+/// the pipeline key.
+pub struct UiBoxShadowViewPipelineKeyBuilder {
+    /// The number of samples that this view requests to render box shadows
+    /// with.
+    box_shadow_samples: Option<BoxShadowSamples>,
 }
 
 pub fn prepare_shadows(
@@ -491,7 +479,7 @@ pub fn prepare_shadows(
             for item_index in 0..ui_phase.items.len() {
                 let item = &mut ui_phase.items[item_index];
                 let Some((extracted_camera_entity, box_shadow)) = extracted_shadows
-                    .box_shadows
+                    .objects
                     .get(&item.main_entity())
                     .and_then(|(extracted_camera_entity, sub_shadows)| {
                         sub_shadows

crates/bevy_ui_render/src/debug_overlay.rs

@@ -194,7 +194,7 @@ pub fn extract_debug_overlay(
     for (entity, uinode, stack_index, transform, visibility, maybe_clip, computed_target, debug) in
         extracted_uinodes
             .changed
-            .iter()
+            .keys()
             .flat_map(|main_entity| uinode_query.get(main_entity.entity()).ok())
     {
         let debug_options = debug.copied().unwrap_or((*debug_options.as_ref()).into());
@@ -222,7 +222,7 @@ pub fn extract_debug_overlay(
             }
 
             extracted_uinodes
-                .uinodes
+                .objects
                 .entry(entity.into())
                 .or_insert_with(|| (extracted_camera_entity, Default::default()))
                 .1