Add a gizmo-based overlay to show UI node outlines (Adopted) (#11237)

# Objective

- This is an adopted version of #10420
- The objective is to help debugging the Ui layout tree with helpful
outlines, that can be easily enabled/disabled

## Solution

- Like #10420, the solution is using the bevy_gizmos in outlining the
nodes

---

## Changelog

### Added
- Added debug_overlay mod to `bevy_dev_tools`
- Added bevy_ui_debug feature to `bevy_dev_tools`

## How to use
- The user must use `bevy_dev_tools` feature in TOML
- The user must use the plugin UiDebugPlugin, that can be found on
`bevy::dev_tools::debug_overlay`
- Finally, to enable the function, the user must set
`UiDebugOptions::enabled` to true
Someone can easily toggle the function with something like:

```rust
fn toggle_overlay(input: Res<ButtonInput<KeyCode>>, options: ResMut<UiDebugOptions>) {
   if input.just_pressed(KeyCode::Space) {
      // The toggle method will enable if disabled and disable if enabled
      options.toggle();
   }
}
```

Note that this feature can be disabled from dev_tools, as its in fact
behind a default feature there, being the feature bevy_ui_debug.

# Limitations
Currently, due to limitations with gizmos itself, it's not possible to
support this feature to more the one window, so this tool is limited to
the primary window only.

# Showcase


![image](https://github.com/bevyengine/bevy/assets/126117294/ce9d70e6-0a57-4fa9-9753-ff5a9d82c009)
Ui example with debug_overlay enabled


![image](https://github.com/bevyengine/bevy/assets/126117294/e945015c-5bab-4d7f-9273-472aabaf25a9)
And disabled

---------

Co-authored-by: Nicola Papale <nico@nicopap.ch>
Co-authored-by: Pablo Reinhardt <pabloreinhardt@gmail.com>
Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

crates/bevy_dev_tools/Cargo.toml

@@ -9,15 +9,26 @@ license = "MIT OR Apache-2.0"
 keywords = ["bevy"]
 
 [features]
+default = ["bevy_ui_debug"]
 bevy_ci_testing = ["serde", "ron"]
+bevy_ui_debug = []
 
 [dependencies]
 # bevy
 bevy_app = { path = "../bevy_app", version = "0.14.0-dev" }
-bevy_utils = { path = "../bevy_utils", version = "0.14.0-dev" }
+bevy_color = { path = "../bevy_color", version = "0.14.0-dev" }
+bevy_core = { path = "../bevy_core", version = "0.14.0-dev" }
+bevy_core_pipeline = { path = "../bevy_core_pipeline", version = "0.14.0-dev" }
 bevy_ecs = { path = "../bevy_ecs", version = "0.14.0-dev" }
+bevy_gizmos = { path = "../bevy_gizmos", version = "0.14.0-dev" }
+bevy_hierarchy = { path = "../bevy_hierarchy", version = "0.14.0-dev" }
+bevy_math = { path = "../bevy_math", version = "0.14.0-dev" }
+bevy_reflect = { path = "../bevy_reflect", version = "0.14.0-dev" }
 bevy_render = { path = "../bevy_render", version = "0.14.0-dev" }
 bevy_time = { path = "../bevy_time", version = "0.14.0-dev" }
+bevy_transform = { path = "../bevy_transform", version = "0.14.0-dev" }
+bevy_ui = { path = "../bevy_ui", version = "0.14.0-dev" }
+bevy_utils = { path = "../bevy_utils", version = "0.14.0-dev" }
 bevy_window = { path = "../bevy_window", version = "0.14.0-dev" }
 bevy_asset = { path = "../bevy_asset", version = "0.14.0-dev" }
 bevy_ui = { path = "../bevy_ui", version = "0.14.0-dev" }

crates/bevy_dev_tools/src/debug_overlay/inset.rs

@@ -0,0 +1,192 @@
+use bevy_color::Color;
+use bevy_gizmos::{config::GizmoConfigGroup, prelude::Gizmos};
+use bevy_math::{Vec2, Vec2Swizzles};
+use bevy_reflect::Reflect;
+use bevy_transform::prelude::GlobalTransform;
+use bevy_utils::HashMap;
+
+use super::{CameraQuery, LayoutRect};
+
+// Function used here so we don't need to redraw lines that are fairly close to each other.
+fn approx_eq(compared: f32, other: f32) -> bool {
+ (compared - other).abs() < 0.001
+}
+
+fn rect_border_axis(rect: LayoutRect) -> (f32, f32, f32, f32) {
+ let pos = rect.pos;
+ let size = rect.size;
+ let offset = pos + size;
+ (pos.x, offset.x, pos.y, offset.y)
+}
+
+#[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Copy, Debug)]
+enum Dir {
+ Start,
+ End,
+}
+impl Dir {
+ const fn increments(self) -> i64 {
+ match self {
+ Dir::Start => 1,
+ Dir::End => -1,
+ }
+ }
+}
+impl From<i64> for Dir {
+ fn from(value: i64) -> Self {
+ if value.is_positive() {
+ Dir::Start
+ } else {
+ Dir::End
+ }
+ }
+}
+/// Collection of axis aligned "lines" (actually just their coordinate on
+/// a given axis).
+#[derive(Debug, Clone)]
+struct DrawnLines {
+ lines: HashMap<i64, Dir>,
+ width: f32,
+}
+#[allow(clippy::cast_precision_loss, clippy::cast_possible_truncation)]
+impl DrawnLines {
+ fn new(width: f32) -> Self {
+ DrawnLines {
+ lines: HashMap::new(),
+ width,
+ }
+ }
+ /// Return `value` offset by as many `increment`s as necessary to make it
+ /// not overlap with already drawn lines.
+ fn inset(&self, value: f32) -> f32 {
+ let scaled = value / self.width;
+ let fract = scaled.fract();
+ let mut on_grid = scaled.floor() as i64;
+ for _ in 0..10 {
+ let Some(dir) = self.lines.get(&on_grid) else {
+ break;
+ };
+ // TODO(clean): This fixes a panic, but I'm not sure how valid this is
+ let Some(added) = on_grid.checked_add(dir.increments()) else {
+ break;
+ };
+ on_grid = added;
+ }
+ ((on_grid as f32) + fract) * self.width
+ }
+ /// Remove a line from the collection of drawn lines.
+ ///
+ /// Typically, we only care for pre-existing lines when drawing the children
+ /// of a container, nothing more. So we remove it after we are done with
+ /// the children.
+ fn remove(&mut self, value: f32, increment: i64) {
+ let mut on_grid = (value / self.width).floor() as i64;
+ loop {
+ // TODO(clean): This fixes a panic, but I'm not sure how valid this is
+ let Some(next_cell) = on_grid.checked_add(increment) else {
+ return;
+ };
+ if !self.lines.contains_key(&next_cell) {
+ self.lines.remove(&on_grid);
+ return;
+ }
+ on_grid = next_cell;
+ }
+ }
+ /// Add a line from the collection of drawn lines.
+ fn add(&mut self, value: f32, increment: i64) {
+ let mut on_grid = (value / self.width).floor() as i64;
+ loop {
+ let old_value = self.lines.insert(on_grid, increment.into());
+ if old_value.is_none() {
+ return;
+ }
+ // TODO(clean): This fixes a panic, but I'm not sure how valid this is
+ let Some(added) = on_grid.checked_add(increment) else {
+ return;
+ };
+ on_grid = added;
+ }
+ }
+}
+
+#[derive(GizmoConfigGroup, Reflect, Default)]
+pub struct UiGizmosDebug;
+
+pub(super) struct InsetGizmo<'w, 's> {
+ draw: Gizmos<'w, 's, UiGizmosDebug>,
+ cam: CameraQuery<'w, 's>,
+ known_y: DrawnLines,
+ known_x: DrawnLines,
+}
+impl<'w, 's> InsetGizmo<'w, 's> {
+ pub(super) fn new(
+ draw: Gizmos<'w, 's, UiGizmosDebug>,
+ cam: CameraQuery<'w, 's>,
+ line_width: f32,
+ ) -> Self {
+ InsetGizmo {
+ draw,
+ cam,
+ known_y: DrawnLines::new(line_width),
+ known_x: DrawnLines::new(line_width),
+ }
+ }
+ fn relative(&self, mut position: Vec2) -> Vec2 {
+ let zero = GlobalTransform::IDENTITY;
+ let Ok(cam) = self.cam.get_single() else {
+ return Vec2::ZERO;
+ };
+ if let Some(new_position) = cam.world_to_viewport(&zero, position.extend(0.)) {
+ position = new_position;
+ };
+ position.xy()
+ }
+ fn line_2d(&mut self, mut start: Vec2, mut end: Vec2, color: Color) {
+ if approx_eq(start.x, end.x) {
+ start.x = self.known_x.inset(start.x);
+ end.x = start.x;
+ } else if approx_eq(start.y, end.y) {
+ start.y = self.known_y.inset(start.y);
+ end.y = start.y;
+ }
+ let (start, end) = (self.relative(start), self.relative(end));
+ self.draw.line_2d(start, end, color);
+ }
+ pub(super) fn set_scope(&mut self, rect: LayoutRect) {
+ let (left, right, top, bottom) = rect_border_axis(rect);
+ self.known_x.add(left, 1);
+ self.known_x.add(right, -1);
+ self.known_y.add(top, 1);
+ self.known_y.add(bottom, -1);
+ }
+ pub(super) fn clear_scope(&mut self, rect: LayoutRect) {
+ let (left, right, top, bottom) = rect_border_axis(rect);
+ self.known_x.remove(left, 1);
+ self.known_x.remove(right, -1);
+ self.known_y.remove(top, 1);
+ self.known_y.remove(bottom, -1);
+ }
+ pub(super) fn rect_2d(&mut self, rect: LayoutRect, color: Color) {
+ let (left, right, top, bottom) = rect_border_axis(rect);
+ if approx_eq(left, right) {
+ self.line_2d(Vec2::new(left, top), Vec2::new(left, bottom), color);
+ } else if approx_eq(top, bottom) {
+ self.line_2d(Vec2::new(left, top), Vec2::new(right, top), color);
+ } else {
+ let inset_x = |v| self.known_x.inset(v);
+ let inset_y = |v| self.known_y.inset(v);
+ let (left, right) = (inset_x(left), inset_x(right));
+ let (top, bottom) = (inset_y(top), inset_y(bottom));
+ let strip = [
+ Vec2::new(left, top),
+ Vec2::new(left, bottom),
+ Vec2::new(right, bottom),
+ Vec2::new(right, top),
+ Vec2::new(left, top),
+ ];
+ self.draw
+ .linestrip_2d(strip.map(|v| self.relative(v)), color);
+ }
+ }
+}