From f4800c24ba48b81a6aecf5ab96b53c95dcdbb84c Mon Sep 17 00:00:00 2001 From: ickshonpe Date: Thu, 12 Dec 2024 04:33:44 +0000 Subject: [PATCH] `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 --- .../src/texture_slice/border_rect.rs | 39 ++++++++++--------- .../bevy_sprite/src/texture_slice/slicer.rs | 2 +- crates/bevy_ui/src/render/debug_overlay.rs | 2 +- crates/bevy_ui/src/render/mod.rs | 2 +- examples/2d/sprite_slice.rs | 8 ++-- examples/ui/ui_texture_atlas_slice.rs | 2 +- examples/ui/ui_texture_slice.rs | 2 +- examples/ui/ui_texture_slice_flip_and_tile.rs | 2 +- 8 files changed, 30 insertions(+), 29 deletions(-) diff --git a/crates/bevy_sprite/src/texture_slice/border_rect.rs b/crates/bevy_sprite/src/texture_slice/border_rect.rs index fc15b42851..adc90a626a 100644 --- a/crates/bevy_sprite/src/texture_slice/border_rect.rs +++ b/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 for BorderRect { - fn from(v: f32) -> Self { - Self::square(v) + fn from(extent: f32) -> Self { + Self::all(extent) } } diff --git a/crates/bevy_sprite/src/texture_slice/slicer.rs b/crates/bevy_sprite/src/texture_slice/slicer.rs index 325e7ccb2b..310be42979 100644 --- a/crates/bevy_sprite/src/texture_slice/slicer.rs +++ b/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, diff --git a/crates/bevy_ui/src/render/debug_overlay.rs b/crates/bevy_ui/src/render/debug_overlay.rs index 4d716bde88..fb735ce5ec 100644 --- a/crates/bevy_ui/src/render/debug_overlay.rs +++ b/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(), diff --git a/crates/bevy_ui/src/render/mod.rs b/crates/bevy_ui/src/render/mod.rs index b7801584fe..8dd0e17411 100644 --- a/crates/bevy_ui/src/render/mod.rs +++ b/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, }, diff --git a/examples/2d/sprite_slice.rs b/examples/2d/sprite_slice.rs index 2542eb44c6..5669fba1f3 100644 --- a/examples/2d/sprite_slice.rs +++ b/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, diff --git a/examples/ui/ui_texture_atlas_slice.rs b/examples/ui/ui_texture_atlas_slice.rs index 733807701c..8102810aa5 100644 --- a/examples/ui/ui_texture_atlas_slice.rs +++ b/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, diff --git a/examples/ui/ui_texture_slice.rs b/examples/ui/ui_texture_slice.rs index cc0f496694..c62bfe00fb 100644 --- a/examples/ui/ui_texture_slice.rs +++ b/examples/ui/ui_texture_slice.rs @@ -48,7 +48,7 @@ fn setup(mut commands: Commands, asset_server: Res) { 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, diff --git a/examples/ui/ui_texture_slice_flip_and_tile.rs b/examples/ui/ui_texture_slice_flip_and_tile.rs index 7b8153965a..3eaf4277f5 100644 --- a/examples/ui/ui_texture_slice_flip_and_tile.rs +++ b/examples/ui/ui_texture_slice_flip_and_tile.rs @@ -28,7 +28,7 @@ fn setup(mut commands: Commands, asset_server: Res) { 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. },