From e7b88d8fe5c0b1db71a62a4bb210020286e1fcb3 Mon Sep 17 00:00:00 2001 From: Matty Date: Thu, 29 Feb 2024 18:52:05 -0500 Subject: [PATCH] Add coordinate axes gizmo (#12211) # Objective - We introduce a gizmo that displays coordinate axes relative to a Transform*, primarily for debugging purposes. - See #9400 ## Solution A new method, `Gizmos::axes`, takes a `Transform`* as input and displays the standard coordinate axes, transformed according to it; its signature looks like this: ````rust pub fn axes(&mut self, transform: into TransformPoint, base_length: f32) { //... } ```` If my carefully placed asterisks hadn't already tipped you off, the argument here is not actually a `Transform` but instead anything which implements `TransformPoint`, which allows it to work also with `GlobalTransform` (and also `Mat4` and `Affine3A`, if the user happens to be hand-rolling transformations in some way). The `base_length` parameter is a scaling factor applied to the coordinate vectors before the transformation takes place; in other words, the caller can use this to help size the coordinate axes appropriately for the entity that they are attached to. An example invocation of this method looks something like this: ````rust fn draw_axes_system( mut gizmos: Gizmos, query: Query<&Transform, With>, ) { for &transform in &query { gizmos.axes(transform, 2.); } } ```` The result is the three coordinate axes, X, Y, Z (colored red, green, and blue, respectively), drawn onto the entity: Screenshot 2024-02-29 at 2 41 45 PM Note that, if scaling was applied as part of the given transformation, it shows up in scaling on the axes as well: Screenshot 2024-02-29 at 2 43 53 PM --- ## Changelog - Added `Gizmos::axes` in bevy_gizmos/src/arrows.rs - Fixed a minor issue with `ArrowBuilder::with_tip_length` not correctly implementing builder style (no external impact) --- ## Discussion ### Design considerations I feel pretty strongly that having no default length scale is for the best, at least for the time being, since it's very easy for the length scale to be too small, leading to the axes being hidden inside the body of the object they are associated with. That is, if the API instead looked like this: ````rust gizmos.axes(transform); // or gizmos.axes(transform).with_length_scale(3.0); ```` then I think it's a reasonable expectation that the first thing would "just work" for most applications, and it wouldn't, which would be kind of a footgun. ### Future steps There are a few directions that this might expand in the future: 1. Introduce additional options via the standard builder pattern; i.e. introducing `AxesBuilder` so that people can configure the axis colors, normalize all axes to a fixed length independent of scale deformations, etc. 2. Fold this functionality into a plugin (like AabbGizmoPlugin) so that the functionality becomes more-or-less automatic based on certain fixed marker components. This wouldn't be very hard to implement, and it has the benefit of making the axes more frictionless to use. Furthermore, if we coupled this to the AABB functionality we already have, we could also ensure that the plugin automatically sizes the axes (by coupling their size to the dimensions of the AABB, for example). 3. Implement something similar for 2d. Honestly, I have no idea if this is desired/useful, but I could probably just implement it in this PR if that's the case. --- crates/bevy_gizmos/src/arrows.rs | 44 ++++++++++++++++++++++++++++++-- 1 file changed, 42 insertions(+), 2 deletions(-) diff --git a/crates/bevy_gizmos/src/arrows.rs b/crates/bevy_gizmos/src/arrows.rs index ddac8a8c7c5471..5571fecf9a24e5 100644 --- a/crates/bevy_gizmos/src/arrows.rs +++ b/crates/bevy_gizmos/src/arrows.rs @@ -4,8 +4,12 @@ //! and assorted support items. use crate::prelude::{GizmoConfigGroup, Gizmos}; -use bevy_color::Color; +use bevy_color::{ + palettes::basic::{BLUE, GREEN, RED}, + Color, +}; use bevy_math::{Quat, Vec2, Vec3}; +use bevy_transform::TransformPoint; /// A builder returned by [`Gizmos::arrow`] and [`Gizmos::arrow_2d`] pub struct ArrowBuilder<'a, 'w, 's, T: GizmoConfigGroup> { @@ -33,8 +37,9 @@ impl ArrowBuilder<'_, '_, '_, T> { /// # bevy_ecs::system::assert_is_system(system); /// ``` #[doc(alias = "arrow_head_length")] - pub fn with_tip_length(&mut self, length: f32) { + pub fn with_tip_length(mut self, length: f32) -> Self { self.tip_length = length; + self } } @@ -123,3 +128,38 @@ impl<'w, 's, T: GizmoConfigGroup> Gizmos<'w, 's, T> { self.arrow(start.extend(0.), end.extend(0.), color) } } + +impl<'w, 's, T: GizmoConfigGroup> Gizmos<'w, 's, T> { + /// Draw a set of axes local to the given transform (`transform`), with length scaled by a factor + /// of `base_length`. + /// + /// This should be called for each frame the axes need to be rendered. + /// + /// # Example + /// ``` + /// # use bevy_gizmos::prelude::*; + /// # use bevy_ecs::prelude::*; + /// # use bevy_transform::components::Transform; + /// # #[derive(Component)] + /// # struct MyComponent; + /// fn draw_axes( + /// mut gizmos: Gizmos, + /// query: Query<&Transform, With>, + /// ) { + /// for &transform in &query { + /// gizmos.axes(transform, 1.); + /// } + /// } + /// # bevy_ecs::system::assert_is_system(draw_axes); + /// ``` + pub fn axes(&mut self, transform: impl TransformPoint, base_length: f32) { + let start = transform.transform_point(Vec3::ZERO); + let end_x = transform.transform_point(base_length * Vec3::X); + let end_y = transform.transform_point(base_length * Vec3::Y); + let end_z = transform.transform_point(base_length * Vec3::Z); + + self.arrow(start, end_x, RED); + self.arrow(start, end_y, GREEN); + self.arrow(start, end_z, BLUE); + } +}