BorderRect maintenance (#16727)

# Objective

The doc comments and function namings for `BorderRect` feel imprecise to
me. Particularly the `square` function which is used to define a uniform
`BorderRect` with equal widths on each edge. But this is potentially
confusing since this "square" border could be around an oblong shape.

Using "padding" to refer to the border extents seems undesirable too
since "padding" is typically used to refer to the area between border
and content, not the border itself.

## Solution
* Rename `square` to `all` (this matches the name of the similar method
on `UiRect`).
* Rename `rectangle` to `axes` (this matches the name of the similar
method on `UiRect`).
* Update doc comments. 

## Migration Guide
The `square` and `rectangle` functions belonging to `BorderRect` have
been renamed to `all` and `axes`.

---------

Co-authored-by: Alice Cecile <[email protected]>

Author: ickshonpe

crates/bevy_sprite/src/texture_slice/border_rect.rs

@@ -1,40 +1,41 @@
 use bevy_reflect::Reflect;
 
-/// Struct defining a [`Sprite`](crate::Sprite) border with padding values
+/// Defines the extents of the border of a rectangle.
+///
+/// This struct is used to represent thickness or offsets from the edges
+/// of a rectangle (left, right, top, and bottom), with values increasing inwards.
 #[derive(Default, Copy, Clone, PartialEq, Debug, Reflect)]
 pub struct BorderRect {
-    /// Pixel padding to the left
+    /// Extent of the border along the left edge
     pub left: f32,
-    /// Pixel padding to the right
+    /// Extent of the border along the right edge
     pub right: f32,
-    /// Pixel padding to the top
+    /// Extent of the border along the top edge
     pub top: f32,
-    /// Pixel padding to the bottom
+    /// Extent of the border along the bottom edge
     pub bottom: f32,
 }
 
 impl BorderRect {
-    /// An empty border with zero padding values in each direction
-    pub const ZERO: Self = Self::square(0.);
+    /// An empty border with zero thickness along each edge
+    pub const ZERO: Self = Self::all(0.);
 
-    /// Creates a new border as a square, with identical pixel padding values on every direction
+    /// Creates a border with the same `extent` along each edge
     #[must_use]
     #[inline]
-    pub const fn square(value: f32) -> Self {
+    pub const fn all(extent: f32) -> Self {
         Self {
-            left: value,
-            right: value,
-            top: value,
-            bottom: value,
+            left: extent,
+            right: extent,
+            top: extent,
+            bottom: extent,
         }
     }
 
-    /// Creates a new border as a rectangle, with:
-    /// - `horizontal` for left and right pixel padding
-    /// - `vertical` for top and bottom pixel padding
+    /// Creates a new border with the `left` and `right` extents equal to `horizontal`, and `top` and `bottom` extents equal to `vertical`.
     #[must_use]
     #[inline]
-    pub const fn rectangle(horizontal: f32, vertical: f32) -> Self {
+    pub const fn axes(horizontal: f32, vertical: f32) -> Self {
         Self {
             left: horizontal,
             right: horizontal,
@@ -45,8 +46,8 @@ impl BorderRect {
 }
 
 impl From<f32> for BorderRect {
-    fn from(v: f32) -> Self {
-        Self::square(v)
+    fn from(extent: f32) -> Self {
+        Self::all(extent)
     }
 }
 

crates/bevy_sprite/src/texture_slice/slicer.rs

@@ -12,7 +12,7 @@ use bevy_reflect::Reflect;
 /// See [9-sliced](https://en.wikipedia.org/wiki/9-slice_scaling) textures.
 #[derive(Debug, Clone, Reflect, PartialEq)]
 pub struct TextureSlicer {
-    /// The sprite borders, defining the 9 sections of the image
+    /// Inset values in pixels that define the four slicing lines dividing the texture into nine sections.
     pub border: BorderRect,
     /// Defines how the center part of the 9 slices will scale
     pub center_scale_mode: SliceScaleMode,

crates/bevy_ui/src/render/debug_overlay.rs

@@ -96,7 +96,7 @@ pub fn extract_debug_overlay(
                     transform: transform.compute_matrix(),
                     flip_x: false,
                     flip_y: false,
-                    border: BorderRect::square(
+                    border: BorderRect::all(
                         debug_options.line_width / uinode.inverse_scale_factor(),
                     ),
                     border_radius: uinode.border_radius(),

crates/bevy_ui/src/render/mod.rs

@@ -511,7 +511,7 @@ pub fn extract_uinode_borders(
                         atlas_scaling: None,
                         flip_x: false,
                         flip_y: false,
-                        border: BorderRect::square(computed_node.outline_width()),
+                        border: BorderRect::all(computed_node.outline_width()),
                         border_radius: computed_node.outline_radius(),
                         node_type: NodeType::Border,
                     },

examples/2d/sprite_slice.rs

@@ -38,7 +38,7 @@ fn spawn_sprites(
             style.clone(),
             Vec2::new(100.0, 200.0),
             SpriteImageMode::Sliced(TextureSlicer {
-                border: BorderRect::square(slice_border),
+                border: BorderRect::all(slice_border),
                 center_scale_mode: SliceScaleMode::Stretch,
                 ..default()
             }),
@@ -49,7 +49,7 @@ fn spawn_sprites(
             style.clone(),
             Vec2::new(100.0, 200.0),
             SpriteImageMode::Sliced(TextureSlicer {
-                border: BorderRect::square(slice_border),
+                border: BorderRect::all(slice_border),
                 center_scale_mode: SliceScaleMode::Tile { stretch_value: 0.5 },
                 sides_scale_mode: SliceScaleMode::Tile { stretch_value: 0.2 },
                 ..default()
@@ -61,7 +61,7 @@ fn spawn_sprites(
             style.clone(),
             Vec2::new(300.0, 200.0),
             SpriteImageMode::Sliced(TextureSlicer {
-                border: BorderRect::square(slice_border),
+                border: BorderRect::all(slice_border),
                 center_scale_mode: SliceScaleMode::Tile { stretch_value: 0.2 },
                 sides_scale_mode: SliceScaleMode::Tile { stretch_value: 0.3 },
                 ..default()
@@ -73,7 +73,7 @@ fn spawn_sprites(
             style,
             Vec2::new(300.0, 200.0),
             SpriteImageMode::Sliced(TextureSlicer {
-                border: BorderRect::square(slice_border),
+                border: BorderRect::all(slice_border),
                 center_scale_mode: SliceScaleMode::Tile { stretch_value: 0.1 },
                 sides_scale_mode: SliceScaleMode::Tile { stretch_value: 0.2 },
                 max_corner_scale: 0.2,

examples/ui/ui_texture_atlas_slice.rs

@@ -58,7 +58,7 @@ fn setup(
     let atlas_layout_handle = texture_atlases.add(atlas_layout);
 
     let slicer = TextureSlicer {
-        border: BorderRect::square(24.0),
+        border: BorderRect::all(24.0),
         center_scale_mode: SliceScaleMode::Stretch,
         sides_scale_mode: SliceScaleMode::Stretch,
         max_corner_scale: 1.0,

examples/ui/ui_texture_slice.rs

@@ -48,7 +48,7 @@ fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
     let image = asset_server.load("textures/fantasy_ui_borders/panel-border-010.png");
 
     let slicer = TextureSlicer {
-        border: BorderRect::square(22.0),
+        border: BorderRect::all(22.0),
         center_scale_mode: SliceScaleMode::Stretch,
         sides_scale_mode: SliceScaleMode::Stretch,
         max_corner_scale: 1.0,

examples/ui/ui_texture_slice_flip_and_tile.rs

@@ -28,7 +28,7 @@ fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
 
     let slicer = TextureSlicer {
         // `numbered_slices.png` is 48 pixels square. `BorderRect::square(16.)` insets the slicing line from each edge by 16 pixels, resulting in nine slices that are each 16 pixels square.
-        border: BorderRect::square(16.),
+        border: BorderRect::all(16.),
         // With `SliceScaleMode::Tile` the side and center slices are tiled to fill the side and center sections of the target.
         // And with a `stretch_value` of `1.` the tiles will have the same size as the corresponding slices in the source image.
         center_scale_mode: SliceScaleMode::Tile { stretch_value: 1. },