forestia/bevy
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
dependabot/cargo/taffy-0.8
bevy/examples/ui/ui_transform.rs
ickshonpe 4836c7868c
Specialized UI transform (#16615) 
# Objective

Add specialized UI transform `Component`s and fix some related problems:
* Animating UI elements by modifying the `Transform` component of UI
nodes doesn't work very well because `ui_layout_system` overwrites the
translations each frame. The `overflow_debug` example uses a horrible
hack where it copies the transform into the position that'll likely
cause a panic if any users naively copy it.
* Picking ignores rotation and scaling and assumes UI nodes are always
axis aligned.
* The clipping geometry stored in `CalculatedClip` is wrong for rotated
and scaled elements.
* Transform propagation is unnecessary for the UI, the transforms can be
updated during layout updates.
* The UI internals use both object-centered and top-left-corner-based
coordinates systems for UI nodes. Depending on the context you have to
add or subtract the half-size sometimes before transforming between
coordinate spaces. We should just use one system consistantly so that
the transform can always be directly applied.
* `Transform` doesn't support responsive coordinates.

## Solution

* Unrequire `Transform` from `Node`.
* New components `UiTransform`, `UiGlobalTransform`:
- `Node` requires `UiTransform`, `UiTransform` requires
`UiGlobalTransform`
- `UiTransform` is a 2d-only equivalent of `Transform` with a
translation in `Val`s.
- `UiGlobalTransform` newtypes `Affine2` and is updated in
`ui_layout_system`.
* New helper functions on `ComputedNode` for mapping between viewport
and local node space.
* The cursor position is transformed to local node space during picking
so that it respects rotations and scalings.
* To check if the cursor hovers a node recursively walk up the tree to
the root checking if any of the ancestor nodes clip the point at the
cursor. If the point is clipped the interaction is ignored.
* Use object-centered coordinates for UI nodes.
* `RelativeCursorPosition`'s coordinates are now object-centered with
(0,0) at the the center of the node and the corners at (±0.5, ±0.5).
* Replaced the `normalized_visible_node_rect: Rect` field of
`RelativeCursorPosition` with `cursor_over: bool`, which is set to true
when the cursor is over an unclipped point on the node. The visible area
of the node is not necessarily a rectangle, so the previous
implementation didn't work.

This should fix all the logical bugs with non-axis aligned interactions
and clipping. Rendering still needs changes but they are far outside the
scope of this PR.

Tried and abandoned two other approaches:
* New `transform` field on `Node`, require `GlobalTransform` on `Node`,
and unrequire `Transform` on `Node`. Unrequiring `Transform` opts out of
transform propagation so there is then no conflict with updating the
`GlobalTransform` in `ui_layout_system`. This was a nice change in its
simplicity but potentially confusing for users I think, all the
`GlobalTransform` docs mention `Transform` and having special rules for
how it's updated just for the UI is unpleasently surprising.
* New `transform` field on `Node`. Unrequire `Transform` on `Node`. New
`transform: Affine2` field on `ComputedNode`.
This was okay but I think most users want a separate specialized UI
transform components. The fat `ComputedNode` doesn't work well with
change detection.

Fixes #18929, #18930

## Testing

There is an example you can look at: 
```
cargo run --example ui_transform
```

Sometimes in the example if you press the rotate button couple of times
the first glyph from the top label disappears , I'm not sure what's
causing it yet but I don't think it's related to this PR.

##  Migration Guide
New specialized 2D UI transform components `UiTransform` and
`UiGlobalTransform`. `UiTransform` is a 2d-only equivalent of
`Transform` with a translation in `Val`s. `UiGlobalTransform` newtypes
`Affine2` and is updated in `ui_layout_system`.
`Node` now requires `UiTransform` instead of `Transform`. `UiTransform`
requires `UiGlobalTransform`.

In previous versions of Bevy `ui_layout_system` would overwrite UI
node's `Transform::translation` each frame. `UiTransform`s aren't
overwritten and there is no longer any need for systems that cache and
rewrite the transform for translated UI elements.

`RelativeCursorPosition`'s coordinates are now object-centered with
(0,0) at the the center of the node and the corners at (±0.5, ±0.5). Its
`normalized_visible_node_rect` field has been removed and replaced with
a new `cursor_over: bool` field which is set to true when the cursor is
hovering an unclipped area of the UI node.

---------

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2025-06-09 19:05:49 +00:00

303 lines
12 KiB
Rust
Raw Permalink Blame History

//! An example demonstrating how to translate, rotate and scale UI elements.
use bevy::color::palettes::css::DARK_GRAY;
use bevy::color::palettes::css::RED;
use bevy::color::palettes::css::YELLOW;
use bevy::prelude::*;
use core::f32::consts::FRAC_PI_8;
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_systems(Startup, setup)
.add_systems(Update, button_system)
.add_systems(Update, translation_system)
.run();
}
const NORMAL_BUTTON: Color = Color::WHITE;
const HOVERED_BUTTON: Color = Color::Srgba(YELLOW);
const PRESSED_BUTTON: Color = Color::Srgba(RED);
/// A button that rotates the target node
#[derive(Component)]
pub struct RotateButton(pub Rot2);
/// A button that scales the target node
#[derive(Component)]
pub struct ScaleButton(pub f32);
/// Marker component so the systems know which entities to translate, rotate and scale
#[derive(Component)]
pub struct TargetNode;
/// Handles button interactions
fn button_system(
mut interaction_query: Query<
(
&Interaction,
&mut BackgroundColor,
Option<&RotateButton>,
Option<&ScaleButton>,
),
(Changed<Interaction>, With<Button>),
>,
mut rotator_query: Query<&mut UiTransform, With<TargetNode>>,
) {
for (interaction, mut color, maybe_rotate, maybe_scale) in &mut interaction_query {
match *interaction {
Interaction::Pressed => {
*color = PRESSED_BUTTON.into();
if let Some(step) = maybe_rotate {
for mut transform in rotator_query.iter_mut() {
transform.rotation *= step.0;
}
}
if let Some(step) = maybe_scale {
for mut transform in rotator_query.iter_mut() {
transform.scale += step.0;
transform.scale =
transform.scale.clamp(Vec2::splat(0.25), Vec2::splat(3.0));
}
}
}
Interaction::Hovered => {
*color = HOVERED_BUTTON.into();
}
Interaction::None => {
*color = NORMAL_BUTTON.into();
}
}
}
}
// move the rotating panel when the arrow keys are pressed
fn translation_system(
time: Res<Time>,
input: Res<ButtonInput<KeyCode>>,
mut translation_query: Query<&mut UiTransform, With<TargetNode>>,
) {
let controls = [
(KeyCode::ArrowLeft, -Vec2::X),
(KeyCode::ArrowRight, Vec2::X),
(KeyCode::ArrowUp, -Vec2::Y),
(KeyCode::ArrowDown, Vec2::Y),
];
for &(key_code, direction) in &controls {
if input.pressed(key_code) {
for mut transform in translation_query.iter_mut() {
let d = direction * 50.0 * time.delta_secs();
let (Val::Px(x), Val::Px(y)) = (transform.translation.x, transform.translation.y)
else {
continue;
};
let x = (x + d.x).clamp(-150., 150.);
let y = (y + d.y).clamp(-150., 150.);
transform.translation = Val2::px(x, y);
}
}
}
}
fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
// UI camera
commands.spawn(Camera2d);
// Root node filling the whole screen
commands.spawn((
Node {
width: Val::Percent(100.),
height: Val::Percent(100.),
align_items: AlignItems::Center,
justify_content: JustifyContent::Center,
..default()
},
BackgroundColor(Color::BLACK),
children![(
Node {
align_items: AlignItems::Center,
justify_content: JustifyContent::SpaceEvenly,
column_gap: Val::Px(25.0),
row_gap: Val::Px(25.0),
..default()
},
BackgroundColor(Color::BLACK),
children![
(
Node {
flex_direction: FlexDirection::Column,
justify_content: JustifyContent::Center,
row_gap: Val::Px(10.0),
column_gap: Val::Px(10.0),
padding: UiRect::all(Val::Px(10.0)),
..default()
},
BackgroundColor(Color::BLACK),
GlobalZIndex(1),
children![
(
Button,
Node {
height: Val::Px(50.0),
width: Val::Px(50.0),
align_items: AlignItems::Center,
justify_content: JustifyContent::Center,
..default()
},
BackgroundColor(Color::WHITE),
RotateButton(Rot2::radians(-FRAC_PI_8)),
children![(Text::new("<--"), TextColor(Color::BLACK),)]
),
(
Button,
Node {
height: Val::Px(50.0),
width: Val::Px(50.0),
align_items: AlignItems::Center,
justify_content: JustifyContent::Center,
..default()
},
BackgroundColor(Color::WHITE),
ScaleButton(-0.25),
children![(Text::new("-"), TextColor(Color::BLACK),)]
),
]
),
// Target node with its own set of buttons
(
Node {
flex_direction: FlexDirection::Column,
justify_content: JustifyContent::SpaceBetween,
align_items: AlignItems::Center,
width: Val::Px(300.0),
height: Val::Px(300.0),
..default()
},
BackgroundColor(DARK_GRAY.into()),
TargetNode,
children![
(
Button,
Node {
width: Val::Px(80.0),
height: Val::Px(80.0),
align_items: AlignItems::Center,
justify_content: JustifyContent::Center,
..default()
},
BackgroundColor(Color::WHITE),
children![(Text::new("Top"), TextColor(Color::BLACK))]
),
(
Node {
align_self: AlignSelf::Stretch,
justify_content: JustifyContent::SpaceBetween,
align_items: AlignItems::Center,
..default()
},
children![
(
Button,
Node {
width: Val::Px(80.0),
height: Val::Px(80.0),
align_items: AlignItems::Center,
justify_content: JustifyContent::Center,
..default()
},
BackgroundColor(Color::WHITE),
UiTransform::from_rotation(Rot2::radians(
-std::f32::consts::FRAC_PI_2
)),
children![(Text::new("Left"), TextColor(Color::BLACK),)]
),
(
Node {
width: Val::Px(100.),
height: Val::Px(100.),
..Default::default()
},
ImageNode {
image: asset_server.load("branding/icon.png"),
image_mode: NodeImageMode::Stretch,
..default()
}
),
(
Button,
Node {
width: Val::Px(80.0),
height: Val::Px(80.0),
align_items: AlignItems::Center,
justify_content: JustifyContent::Center,
..default()
},
UiTransform::from_rotation(Rot2::radians(
core::f32::consts::FRAC_PI_2
)),
BackgroundColor(Color::WHITE),
children![(Text::new("Right"), TextColor(Color::BLACK))]
),
]
),
(
Button,
Node {
width: Val::Px(80.0),
height: Val::Px(80.0),
align_items: AlignItems::Center,
justify_content: JustifyContent::Center,
..default()
},
BackgroundColor(Color::WHITE),
UiTransform::from_rotation(Rot2::radians(std::f32::consts::PI)),
children![(Text::new("Bottom"), TextColor(Color::BLACK),)]
),
]
),
// Right column of controls
(
Node {
flex_direction: FlexDirection::Column,
justify_content: JustifyContent::Center,
row_gap: Val::Px(10.0),
column_gap: Val::Px(10.0),
padding: UiRect::all(Val::Px(10.0)),
..default()
},
BackgroundColor(Color::BLACK),
GlobalZIndex(1),
children![
(
Button,
Node {
height: Val::Px(50.0),
width: Val::Px(50.0),
align_items: AlignItems::Center,
justify_content: JustifyContent::Center,
..default()
},
BackgroundColor(Color::WHITE),
RotateButton(Rot2::radians(FRAC_PI_8)),
children![(Text::new("-->"), TextColor(Color::BLACK),)]
),
(
Button,
Node {
height: Val::Px(50.0),
width: Val::Px(50.0),
align_items: AlignItems::Center,
justify_content: JustifyContent::Center,
..default()
},
BackgroundColor(Color::WHITE),
ScaleButton(0.25),
children![(Text::new("+"), TextColor(Color::BLACK),)]
),
]
)
]
)],
));
}
Reference in New Issue View Git Blame Copy Permalink