Named UI paint layers

_release-content/migration-guides/named_ui_z_layers.md

@@ -0,0 +1,15 @@
+---
+title: "`stack_z_offsets` has been replaced by named z layers"
+pull_requests: [26260]
+---
+
+Instead of using explicit `f32` z-offsets, `bevy_ui_render` now has named paint layers.
+The z offset constants in the `stack_z_offsets` module have been replaced by named `PaintLayer` constants.
+The list of layers is stored in back-to-front order in the `PaintOrder` resource.
+
+`TransparentUi::sort_key` now uses `UiSortKey` instead of `FloatOrd`. UI phase items are ordered first by stack index, then by paint layer index. Use `PaintOrder::get_layer_index` to look up a layer's index, then construct a `UiSortKey` with `UiSortKey::new(stack_index, paint_layer)`
+
+`ExtractedUiNode::z_order` has been replaced by `stack_index: ComputedStackIndex` and `paint_layer: usize`.
+The `stack_index` fields on `ExtractedBoxShadow`, `ExtractedGradient`, `ExtractedUiMaterialNode`, and `ExtractedUiTextureSlice` now take `ComputedStackIndex` instead of `u32`.
+
+The `UiMaterial` trait's `stack_z_offset` method has been replaced by `paint_layer`, which should return the `PaintLayer` the material is intended to be drawn to.

_release-content/release-notes/ui_paint_layers.md

@@ -0,0 +1,36 @@
+---
+title: Paint layers
+authors: ["@Ickshonpe"]
+pull_requests: [26260]
+---
+
+`bevy_ui_render` now has paint layers.
+
+The `PaintOrder` resource holds the list of paint layers, in the order they’re drawn from back to front.
+
+The built-in layers are identified by named `PaintLayer` constants such as `BOX_SHADOW_PAINT_LAYER` and `TEXT_PAINT_LAYER`.
+
+`UiRenderPlugin` initializes `PaintOrder` with all the builtin layers in the correct order.
+
+To create a new `PaintLayer`, give it a string name:
+
+```rust
+pub const MY_PAINT_LAYER: PaintLayer = PaintLayer::new_static("my_plugin.overlay");
+```
+
+The `PaintOrder` resource exposes `IndexSet`’s methods through dereferencing, plus these helpers:
+
+- `insert_before_layer` / `insert_after_layer` place a layer directly below or above an existing layer.
+- `insert_top` / `insert_bottom` place a layer above or below all the other layers.
+- `remove_layer` removes a layer. A built-in element whose layer is removed isn't drawn.
+
+The insert methods move a layer if it is already present.
+
+The `UiMaterial` trait has a new `paint_layer()` method that chooses the layer the layer the material is drawn to.
+It defaults to `MATERIAL_PAINT_LAYER`.
+
+UI render items are sorted using `UiSortKey`, first by `ComputedStackIndex` and then by paint-layer index.
+
+Extraction functions should look up their layer index with `PaintOrder::get_layer_index` once at the start of the function. Extracted items store `ComputedStackIndex` directly, and `ExtractedUiNode` also stores the paint-layer index. Queue functions construct the sort key with `UiSortKey::new(stack_index, paint_layer)`. The `PaintOrder` resource is also extracted separately, so some queue functions look up the layer index there instead.
+
+Changing `PaintOrder` at all is expensive, as it triggers a reextraction of all elements.

crates/bevy_ui/src/stack.rs

@@ -14,7 +14,9 @@ use core::ops::Range;
 /// Nodes with a higher stack index are drawn on top of and receive interactions before nodes with lower stack indices.
 ///
 /// Automatically calculated in [`UiSystems::Stack`](`super::UiSystems::Stack`).
-#[derive(Component, Default, PartialEq, Eq, Deref, DerefMut, Reflect)]
+#[derive(
+    Component, Default, Clone, Copy, Ord, Debug, PartialEq, PartialOrd, Eq, Deref, DerefMut, Reflect,
+)]
 #[reflect(Component, Default)]
 pub struct ComputedStackIndex(pub u32);
 

crates/bevy_ui_render/Cargo.toml

@@ -44,10 +44,17 @@ derive_more = { version = "2", default-features = false, features = ["from"] }
 tracing = { version = "0.1", default-features = false, features = ["std"] }
 indexmap = { version = "2" }
 smallvec = { version = "1", default-features = false }
+smol_str = { version = "0.2", default-features = false }
+serde = { version = "1", features = ["derive"], optional = true }
 
 [features]
 default = ["bevy_ui_debug"]
-serialize = ["bevy_math/serialize", "bevy_platform/serialize"]
+serialize = [
+  "bevy_math/serialize",
+  "bevy_platform/serialize",
+  "dep:serde",
+  "smol_str/serde",
+]
 bevy_ui_debug = []
 
 [lints]

crates/bevy_ui_render/src/box_shadow.rs

@@ -15,7 +15,7 @@ use bevy_ecs::{
         *,
     },
 };
-use bevy_math::{vec2, Affine2, FloatOrd, Vec2};
+use bevy_math::{vec2, Affine2, Vec2};
 use bevy_mesh::VertexBufferLayout;
 use bevy_render::sync_world::{MainEntity, MainEntityHashMap, MainEntityHashSet};
 use bevy_render::{
@@ -34,11 +34,13 @@ use bevy_ui::{
 use bevy_utils::default;
 use bytemuck::{Pod, Zeroable};
 
+use crate::UiSortKey;
 use crate::{
     clipping::clip_polygon, BoxShadowSamples, RenderUiSystems, TransparentUi, UiCameraMap,
 };
 
-use super::{stack_z_offsets, UiCameraView, QUAD_VERTEX_POSITIONS};
+use super::{UiCameraView, QUAD_VERTEX_POSITIONS};
+use crate::paint_layers::{PaintOrder, BOX_SHADOW_PAINT_LAYER};
 
 /// A plugin that enables the rendering of box shadows.
 pub struct BoxShadowPlugin;
@@ -186,7 +188,7 @@ impl SpecializedRenderPipeline for BoxShadowPipeline {
 
 /// Description of a shadow to be sorted and queued for rendering
 pub struct ExtractedBoxShadow {
-    pub stack_index: u32,
+    pub stack_index: ComputedStackIndex,
     pub transform: Affine2,
     pub bounds: Vec2,
     pub clip: Option<CalculatedClip>,
@@ -358,7 +360,7 @@ pub fn extract_shadows(
                 .insert(
                     commands.spawn_empty().id(),
                     ExtractedBoxShadow {
-                        stack_index: stack_index.0,
+                        stack_index: *stack_index,
                         transform: Affine2::from(transform) * Affine2::from_translation(offset),
                         color: drop_shadow.color.into(),
                         bounds: shadow_size + 6. * blur_radius,
@@ -401,6 +403,7 @@ pub fn extract_shadows(
     reason = "it's a system that needs a lot of them"
 )]
 pub fn queue_shadows(
+    paint_order: Res<PaintOrder>,
     extracted_box_shadows: ResMut<ExtractedBoxShadows>,
     box_shadow_pipeline: Res<BoxShadowPipeline>,
     mut pipelines: ResMut<SpecializedRenderPipelines<BoxShadowPipeline>>,
@@ -410,6 +413,10 @@ pub fn queue_shadows(
     pipeline_cache: Res<PipelineCache>,
     draw_functions: Res<DrawFunctions<TransparentUi>>,
 ) {
+    let Ok(paint_layer) = paint_order.get_layer_index(BOX_SHADOW_PAINT_LAYER) else {
+        return;
+    };
+
     let draw_function = draw_functions.read().id::<DrawBoxShadows>();
     let mut current_camera_entity = Entity::PLACEHOLDER;
     let mut current_phase = None;
@@ -451,10 +458,7 @@ pub fn queue_shadows(
                 draw_function,
                 pipeline: *pipeline,
                 entity: (*entity, *main_entity),
-                sort_key: FloatOrd(
-                    extracted_shadow.stack_index as f32 + stack_z_offsets::BOX_SHADOW,
-                ),
-
+                sort_key: UiSortKey::new(extracted_shadow.stack_index, paint_layer),
                 batch_range: 0..0,
                 extra_index: PhaseItemExtraIndex::None,
                 indexed: true,

crates/bevy_ui_render/src/debug_overlay.rs

@@ -212,7 +212,7 @@ pub fn extract_debug_overlay(
         let color = debug_options
             .line_color_override
             .unwrap_or_else(|| Hsla::sequential_dispersed(entity.index_u32()).into());
-        let z_order = (ui_stack.uinodes.len() as u32 + stack_index.0) as f32;
+        let stack_index = ComputedStackIndex(ui_stack.uinodes.len() as u32 + stack_index.0);
         let border = BorderRect::all(debug_options.line_width / uinode.inverse_scale_factor());
         let transform = transform.affine();
 
@@ -229,8 +229,8 @@ pub fn extract_debug_overlay(
                 .insert(
                     commands.spawn_empty().id(),
                     ExtractedUiNode {
-                        // Keep all overlays above UI, and nudge each type slightly in Z so ordering is stable.
-                        z_order,
+                        stack_index,
+                        paint_layer: 0,
                         clip: maybe_clip.filter(|_| !debug_options.show_clipped).cloned(),
                         image: AssetId::default(),
                         transform: transform * Affine2::from_translation(rect.center()),

crates/bevy_ui_render/src/gradient.rs

@@ -6,6 +6,7 @@ use core::{
 
 use super::shader_flags::BORDER_ALL;
 use crate::clipping::clip_polygon;
+use crate::paint_layers::{BORDER_GRADIENT_PAINT_LAYER, GRADIENT_PAINT_LAYER};
 use crate::*;
 use bevy_asset::*;
 use bevy_color::{ColorToComponents, Hsla, Hsva, LinearRgba, Okhsla, Oklaba, Oklcha, Srgba};
@@ -231,7 +232,7 @@ pub enum ResolvedGradient {
 }
 
 pub struct ExtractedGradient {
-    pub stack_index: u32,
+    pub stack_index: ComputedStackIndex,
     pub transform: Affine2,
     pub rect: Rect,
     pub clip: Option<CalculatedClip>,
@@ -486,7 +487,7 @@ pub fn extract_gradients(
                         .insert(
                             commands.spawn_empty().id(),
                             ExtractedGradient {
-                                stack_index: stack_index.0,
+                                stack_index: *stack_index,
                                 transform: transform.into(),
                                 stops: extracted_stops,
                                 rect: Rect {
@@ -529,7 +530,7 @@ pub fn extract_gradients(
                             .insert(
                                 commands.spawn_empty().id(),
                                 ExtractedGradient {
-                                    stack_index: stack_index.0,
+                                    stack_index: *stack_index,
                                     transform: transform.into(),
                                     stops: extracted_stops,
                                     rect: Rect {
@@ -588,7 +589,7 @@ pub fn extract_gradients(
                             .insert(
                                 commands.spawn_empty().id(),
                                 ExtractedGradient {
-                                    stack_index: stack_index.0,
+                                    stack_index: *stack_index,
                                     transform: transform.into(),
                                     stops: computed_stops,
                                     rect: Rect {
@@ -649,7 +650,7 @@ pub fn extract_gradients(
                             .insert(
                                 commands.spawn_empty().id(),
                                 ExtractedGradient {
-                                    stack_index: stack_index.0,
+                                    stack_index: *stack_index,
                                     transform: transform.into(),
                                     stops: extracted_color_stops,
                                     rect: Rect {
@@ -704,6 +705,7 @@ pub fn extract_gradients(
     reason = "it's a system that needs a lot of them"
 )]
 pub fn queue_gradient(
+    paint_order: Res<PaintOrder>,
     extracted_gradients: ResMut<ExtractedGradients>,
     gradients_pipeline: Res<GradientPipeline>,
     mut pipelines: ResMut<SpecializedRenderPipelines<GradientPipeline>>,
@@ -741,6 +743,13 @@ pub fn queue_gradient(
             continue;
         };
         for (render_entity, gradient) in sub_gradients.iter() {
+            let Ok(paint_layer) = paint_order.get_layer_index(match gradient.node_type {
+                NodeType::Rect | NodeType::Inverted => GRADIENT_PAINT_LAYER,
+                NodeType::Border(_) => BORDER_GRADIENT_PAINT_LAYER,
+            }) else {
+                continue;
+            };
+
             let pipeline = pipelines.specialize(
                 &pipeline_cache,
                 &gradients_pipeline,
@@ -755,13 +764,7 @@ pub fn queue_gradient(
                 draw_function,
                 pipeline,
                 entity: (*render_entity, *main_entity),
-                sort_key: FloatOrd(
-                    gradient.stack_index as f32
-                        + match gradient.node_type {
-                            NodeType::Rect | NodeType::Inverted => stack_z_offsets::GRADIENT,
-                            NodeType::Border(_) => stack_z_offsets::BORDER_GRADIENT,
-                        },
-                ),
+                sort_key: UiSortKey::new(gradient.stack_index, paint_layer),
                 batch_range: 0..0,
                 extra_index: PhaseItemExtraIndex::None,
                 indexed: true,