Simplified ui_stack_system

crates/bevy_ui/src/stack.rs

@@ -3,7 +3,7 @@
 use bevy_ecs::prelude::*;
 use bevy_hierarchy::prelude::*;
 
-use crate::{Node, ZIndex};
+use crate::{GlobalZIndex, Node, ZIndex};
 
 /// The current UI stack, which contains all UI nodes ordered by their depth (back-to-front).
 ///
@@ -15,102 +15,78 @@ pub struct UiStack {
  pub uinodes: Vec<Entity>,
 }
 
-#[derive(Default)]
-struct StackingContext {
- pub entries: Vec<StackingContextEntry>,
-}
+fn update_uistack_recursively(
+ entity: Entity,
+ uinodes: &mut Vec<Entity>,
+ children_query: &Query<&Children>,
+ zindex_query: &Query<Option<&ZIndex>, (With<Node>, Without<GlobalZIndex>)>,
+) {
+ uinodes.push(entity);
 
-struct StackingContextEntry {
- pub z_index: i32,
- pub entity: Entity,
- pub stack: StackingContext,
+ if let Ok(children) = children_query.get(entity) {
+ let mut z_children: Vec<(Entity, i32)> = children
+ .iter()
+ .filter_map(|entity| {
+ zindex_query
+ .get(*entity)
+ .ok()
+ .map(|zindex| (*entity, zindex.map(|zindex| zindex.0).unwrap_or(0)))
+ })
+ .collect();
+ z_children.sort_by_key(|k| k.1);
+ for (child_id, _) in z_children {
+ update_uistack_recursively(child_id, uinodes, children_query, zindex_query);
+ }
+ }
 }
 
 /// Generates the render stack for UI nodes.
-///
-/// First generate a UI node tree (`StackingContext`) based on z-index.
-/// Then flatten that tree into back-to-front ordered `UiStack`.
 pub fn ui_stack_system(
  mut ui_stack: ResMut<UiStack>,
- root_node_query: Query<Entity, (With<Node>, Without<Parent>)>,
- zindex_query: Query<&ZIndex, With<Node>>,
+ root_node_query: Query<
+ (Entity, Option<&GlobalZIndex>, Option<&ZIndex>),
+ (With<Node>, Without<Parent>),
+ >,
+ zindex_global_node_query: Query<
+ (Entity, &GlobalZIndex, Option<&ZIndex>),
+ (With<Node>, With<Parent>),
+ >,
  children_query: Query<&Children>,
+ zindex_query: Query<Option<&ZIndex>, (With<Node>, Without<GlobalZIndex>)>,
 ) {
- // Generate `StackingContext` tree
- let mut global_context = StackingContext::default();
- let mut total_entry_count: usize = 0;
-
- for entity in &root_node_query {
- insert_context_hierarchy(
- &zindex_query,
- &children_query,
- entity,
- &mut global_context,
- None,
- &mut total_entry_count,
- );
- }
-
- // Flatten `StackingContext` into `UiStack`
  ui_stack.uinodes.clear();
- ui_stack.uinodes.reserve(total_entry_count);
- fill_stack_recursively(&mut ui_stack.uinodes, &mut global_context);
-}
-
-/// Generate z-index based UI node tree
-fn insert_context_hierarchy(
- zindex_query: &Query<&ZIndex, With<Node>>,
- children_query: &Query<&Children>,
- entity: Entity,
- global_context: &mut StackingContext,
- parent_context: Option<&mut StackingContext>,
- total_entry_count: &mut usize,
-) {
- let mut new_context = StackingContext::default();
+ let uinodes = &mut ui_stack.uinodes;
 
- if let Ok(children) = children_query.get(entity) {
- // Reserve space for all children. In practice, some may not get pushed since
- // nodes with `ZIndex::Global` are pushed to the global (root) context.
- new_context.entries.reserve_exact(children.len());
-
- for entity in children {
- insert_context_hierarchy(
- zindex_query,
- children_query,
- *entity,
- global_context,
- Some(&mut new_context),
- total_entry_count,
- );
- }
- }
+ let global_nodes = zindex_global_node_query
+ .iter()
+ .map(|(id, global_zindex, maybe_zindex)| {
+ (
+ id,
+ (
+ global_zindex.0,
+ maybe_zindex.map(|zindex| zindex.0).unwrap_or(0),
+ ),
+ )
+ });
 
- // The node will be added either to global/parent based on its z-index type: global/local.
- let z_index = zindex_query.get(entity).unwrap_or(&ZIndex::Local(0));
- let (entity_context, z_index) = match z_index {
- ZIndex::Local(value) => (parent_context.unwrap_or(global_context), *value),
- ZIndex::Global(value) => (global_context, *value),
- };
+ let mut root_nodes: Vec<_> = root_node_query
+ .iter()
+ .map(|(root_id, maybe_global_zindex, maybe_zindex)| {
+ (
+ root_id,
+ (
+ maybe_global_zindex.map(|zindex| zindex.0).unwrap_or(0),
+ maybe_zindex.map(|zindex| zindex.0).unwrap_or(0),
+ ),
+ )
+ })
+ .chain(global_nodes)
+ .collect();
 
- *total_entry_count += 1;
- entity_context.entries.push(StackingContextEntry {
- z_index,
- entity,
- stack: new_context,
- });
-}
+ root_nodes.sort_by_key(|(_, z)| *z);
 
-/// Flatten `StackingContext` (z-index based UI node tree) into back-to-front entities list
-fn fill_stack_recursively(result: &mut Vec<Entity>, stack: &mut StackingContext) {
- // Sort entries by ascending z_index, while ensuring that siblings
- // with the same local z_index will keep their ordering. This results
- // in `back-to-front` ordering, low z_index = back; high z_index = front.
- stack.entries.sort_by_key(|e| e.z_index);
-
- for entry in &mut stack.entries {
- // Parent node renders before/behind child nodes
- result.push(entry.entity);
- fill_stack_recursively(result, &mut entry.stack);
+ for (entity, _) in root_nodes {
+ update_uistack_recursively(entity, uinodes, &children_query, &zindex_query);
  }
 }
 
@@ -124,15 +100,35 @@ mod tests {
  };
  use bevy_hierarchy::BuildChildren;
 
- use crate::{Node, UiStack, ZIndex};
+ use crate::{GlobalZIndex, Node, UiStack, ZIndex};
 
  use super::ui_stack_system;
 
  #[derive(Component, PartialEq, Debug, Clone)]
  struct Label(&'static str);
 
- fn node_with_zindex(name: &'static str, z_index: ZIndex) -> (Label, Node, ZIndex) {
- (Label(name), Node::default(), z_index)
+ fn node_with_global_and_local_zindex(
+ name: &'static str,
+ global_zindex: i32,
+ local_zindex: i32,
+ ) -> (Label, Node, GlobalZIndex, ZIndex) {
+ (
+ Label(name),
+ Node::default(),
+ GlobalZIndex(global_zindex),
+ ZIndex(local_zindex),
+ )
+ }
+
+ fn node_with_global_zindex(
+ name: &'static str,
+ global_zindex: i32,
+ ) -> (Label, Node, GlobalZIndex) {
+ (Label(name), Node::default(), GlobalZIndex(global_zindex))
+ }
+
+ fn node_with_zindex(name: &'static str, zindex: i32) -> (Label, Node, ZIndex) {
+ (Label(name), Node::default(), ZIndex(zindex))
  }
 
  fn node_without_zindex(name: &'static str) -> (Label, Node) {
@@ -152,24 +148,24 @@ mod tests {
 
  let mut queue = CommandQueue::default();
  let mut commands = Commands::new(&mut queue, &world);
- commands.spawn(node_with_zindex("0", ZIndex::Global(2)));
+ commands.spawn(node_with_global_zindex("0", 2));
 
  commands
- .spawn(node_with_zindex("1", ZIndex::Local(1)))
+ .spawn(node_with_zindex("1", 1))
  .with_children(|parent| {
  parent
  .spawn(node_without_zindex("1-0"))
  .with_children(|parent| {
  parent.spawn(node_without_zindex("1-0-0"));
  parent.spawn(node_without_zindex("1-0-1"));
- parent.spawn(node_with_zindex("1-0-2", ZIndex::Local(-1)));
+ parent.spawn(node_with_zindex("1-0-2", -1));
  });
  parent.spawn(node_without_zindex("1-1"));
  parent
- .spawn(node_with_zindex("1-2", ZIndex::Global(-1)))
+ .spawn(node_with_global_zindex("1-2", -1))
  .with_children(|parent| {
  parent.spawn(node_without_zindex("1-2-0"));
- parent.spawn(node_with_zindex("1-2-1", ZIndex::Global(-3)));
+ parent.spawn(node_with_global_zindex("1-2-1", -3));
  parent
  .spawn(node_without_zindex("1-2-2"))
  .with_children(|_| ());
@@ -191,7 +187,7 @@ mod tests {
  });
  });
 
- commands.spawn(node_with_zindex("3", ZIndex::Global(-2)));
+ commands.spawn(node_with_global_zindex("3", -2));
 
  queue.apply(&mut world);
 
@@ -207,25 +203,74 @@ mod tests {
  .map(|entity| query.get(&world, *entity).unwrap().clone())
  .collect::<Vec<_>>();
  let expected_result = vec![
- (Label("1-2-1")), // ZIndex::Global(-3)
- (Label("3")), // ZIndex::Global(-2)
- (Label("1-2")), // ZIndex::Global(-1)
+ (Label("1-2-1")), // GlobalZIndex(-3)
+ (Label("3")), // GlobalZIndex(-2)
+ (Label("1-2")), // GlobalZIndex(-1)
  (Label("1-2-0")),
  (Label("1-2-2")),
  (Label("1-2-3")),
  (Label("2")),
  (Label("2-0")),
  (Label("2-1")),
  (Label("2-1-0")),
- (Label("1")), // ZIndex::Local(1)
+ (Label("1")), // ZIndex(1)
  (Label("1-0")),
- (Label("1-0-2")), // ZIndex::Local(-1)
+ (Label("1-0-2")), // ZIndex(-1)
  (Label("1-0-0")),
  (Label("1-0-1")),
  (Label("1-1")),
  (Label("1-3")),
- (Label("0")), // ZIndex::Global(2)
+ (Label("0")), // GlobalZIndex(2)
  ];
  assert_eq!(actual_result, expected_result);
  }
+
+ #[test]
+ fn test_with_equal_global_zindex_zindex_decides_order() {
+ let mut world = World::default();
+ world.init_resource::<UiStack>();
+
+ let mut queue = CommandQueue::default();
+ let mut commands = Commands::new(&mut queue, &world);
+ commands.spawn(node_with_global_and_local_zindex("0", -1, 1));
+ commands.spawn(node_with_global_and_local_zindex("1", -1, 2));
+ commands.spawn(node_with_global_and_local_zindex("2", 1, 3));
+ commands.spawn(node_with_global_and_local_zindex("3", 1, -3));
+ commands
+ .spawn(node_without_zindex("4"))
+ .with_children(|builder| {
+ builder.spawn(node_with_global_and_local_zindex("5", 0, -1));
+ builder.spawn(node_with_global_and_local_zindex("6", 0, 1));
+ builder.spawn(node_with_global_and_local_zindex("7", -1, -1));
+ builder.spawn(node_with_global_zindex("8", 1));
+ });
+
+ queue.apply(&mut world);
+
+ let mut schedule = Schedule::default();
+ schedule.add_systems(ui_stack_system);
+ schedule.run(&mut world);
+
+ let mut query = world.query::<&Label>();
+ let ui_stack = world.resource::<UiStack>();
+ let actual_result = ui_stack
+ .uinodes
+ .iter()
+ .map(|entity| query.get(&world, *entity).unwrap().clone())
+ .collect::<Vec<_>>();
+
+ let expected_result = vec![
+ (Label("7")),
+ (Label("0")),
+ (Label("1")),
+ (Label("5")),
+ (Label("4")),
+ (Label("6")),
+ (Label("3")),
+ (Label("8")),
+ (Label("2")),
+ ];
+
+ assert_eq!(actual_result, expected_result);
+ }
 }

crates/bevy_ui/src/ui_node.rs

@@ -1505,26 +1505,20 @@ pub struct CalculatedClip {
 /// appear in the UI hierarchy. In such a case, the last node to be added to its parent
 /// will appear in front of this parent's other children.
 ///
-/// Internally, nodes with a global z-index share the stacking context of root UI nodes
-/// (nodes that have no parent). Because of this, there is no difference between using
-/// [`ZIndex::Local(n)`] and [`ZIndex::Global(n)`] for root nodes.
-///
-/// Nodes without this component will be treated as if they had a value of [`ZIndex::Local(0)`].
-#[derive(Component, Copy, Clone, Debug, Reflect)]
+/// Nodes without this component will be treated as if they had a value of [`ZIndex(0)`].
+#[derive(Component, Copy, Clone, Debug, Default, Reflect)]
 #[reflect(Component)]
-pub enum ZIndex {
- /// Indicates the order in which this node should be rendered relative to its siblings.
- Local(i32),
- /// Indicates the order in which this node should be rendered relative to root nodes and
- /// all other nodes that have a global z-index.
- Global(i32),
-}
+pub struct ZIndex(pub i32);
 
-impl Default for ZIndex {
- fn default() -> Self {
- Self::Local(0)
- }
-}
+/// `GlobalZIndex` allows a node anywhere in the UI hierarchy to escape the implicit draw ordering of the UI's layout tree and
+/// be rendered above above or below other UI nodes.
+/// Nodes with a `GlobalZIndex` of greater than 0 will be drawn on top of nodes without a `GlobalZIndex` or nodes with a lower `GlobalZIndex`.
+/// Nodes with a `GlobalZIndex` of less than 0 will be drawn below nodes without a `GlobalZIndex` or nodes with a greater `GlobalZIndex`.
+///
+/// If two Nodes have the same `GlobalZIndex`, the node with the greater [`ZIndex`] will be drawn on top.
+#[derive(Component, Copy, Clone, Debug, Default, Reflect)]
+#[reflect(Component)]
+pub struct GlobalZIndex(pub i32);
 
 #[cfg(test)]
 mod tests {

examples/stress_tests/bevymark.rs

@@ -219,16 +219,18 @@ fn setup(
 
  commands.spawn(Camera2dBundle::default());
  commands
- .spawn(NodeBundle {
- style: Style {
- position_type: PositionType::Absolute,
- padding: UiRect::all(Val::Px(5.0)),
+ .spawn((
+ NodeBundle {
+ style: Style {
+ position_type: PositionType::Absolute,
+ padding: UiRect::all(Val::Px(5.0)),
+ ..default()
+ },
+ background_color: Color::BLACK.with_a(0.75).into(),
  ..default()
  },
- z_index: ZIndex::Global(i32::MAX),
- background_color: Color::BLACK.with_a(0.75).into(),
- ..default()
- })
+ GlobalZIndex(i32::MAX),
+ ))
  .with_children(|c| {
  c.spawn((
  TextBundle::from_sections([