From c8ed5298f023d8f05426f0947cecce8222d8e30a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9l=C3=A8ne=20Amanita?= <134181069+Selene-Amanita@users.noreply.github.com> Date: Mon, 31 Jul 2023 20:14:52 +0100 Subject: [PATCH] Clarify immediate mode in `Gizmos` documentation (#9183) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit # Objective - Repeat in `Gizmos` that they are drawned in immediate mode, which is said at the module level but not here, and detail what it means. - Clarify for every method of `Gizmos` that they should be called for every frame. - Clarify which methods belong to 3D or 2D space (kinda obvious for 2D but still) The first time I used gizmos I didn't understand how they work and was confused as to why nothing showed up. --------- Co-authored-by: François Co-authored-by: SpecificProtagonist Co-authored-by: Alice Cecile --- crates/bevy_gizmos/src/gizmos.rs | 85 ++++++++++++++++++++++++-------- 1 file changed, 64 insertions(+), 21 deletions(-) diff --git a/crates/bevy_gizmos/src/gizmos.rs b/crates/bevy_gizmos/src/gizmos.rs index 974532d11e7c9..088112d846a23 100644 --- a/crates/bevy_gizmos/src/gizmos.rs +++ b/crates/bevy_gizmos/src/gizmos.rs @@ -24,6 +24,10 @@ pub(crate) struct GizmoStorage { } /// A [`SystemParam`](bevy_ecs::system::SystemParam) for drawing gizmos. +/// +/// They are drawn in immediate mode, which means they will be rendered only for +/// the frames in which they are spawned. +/// Gizmos should be spawned before the [`Last`](bevy_app::Last) schedule to ensure they are drawn. #[derive(SystemParam)] pub struct Gizmos<'s> { buffer: Deferred<'s, GizmoBuffer>, @@ -48,7 +52,9 @@ impl SystemBuffer for GizmoBuffer { } impl<'s> Gizmos<'s> { - /// Draw a line from `start` to `end`. + /// Draw a line in 3D from `start` to `end`. + /// + /// This should be called for each frame the line needs to be rendered. /// /// # Example /// ``` @@ -66,7 +72,9 @@ impl<'s> Gizmos<'s> { self.add_list_color(color, 2); } - /// Draw a line with a color gradient from `start` to `end`. + /// Draw a line in 3D with a color gradient from `start` to `end`. + /// + /// This should be called for each frame the line needs to be rendered. /// /// # Example /// ``` @@ -84,7 +92,9 @@ impl<'s> Gizmos<'s> { self.extend_list_colors([start_color, end_color]); } - /// Draw a line from `start` to `start + vector`. + /// Draw a line in 3D from `start` to `start + vector`. + /// + /// This should be called for each frame the line needs to be rendered. /// /// # Example /// ``` @@ -101,7 +111,9 @@ impl<'s> Gizmos<'s> { self.line(start, start + vector, color); } - /// Draw a line with a color gradient from `start` to `start + vector`. + /// Draw a line in 3D with a color gradient from `start` to `start + vector`. + /// + /// This should be called for each frame the line needs to be rendered. /// /// # Example /// ``` @@ -124,7 +136,9 @@ impl<'s> Gizmos<'s> { self.line_gradient(start, start + vector, start_color, end_color); } - /// Draw lines between a list of points. + /// Draw a line in 3D made of straight segments between the points. + /// + /// This should be called for each frame the line needs to be rendered. /// /// # Example /// ``` @@ -146,7 +160,9 @@ impl<'s> Gizmos<'s> { self.buffer.strip_colors.push([f32::NAN; 4]); } - /// Draw lines between a list of points with a color gradient. + /// Draw a line in 3D made of straight segments between the points, with a color gradient. + /// + /// This should be called for each frame the lines need to be rendered. /// /// # Example /// ``` @@ -185,7 +201,9 @@ impl<'s> Gizmos<'s> { strip_colors.push([f32::NAN; 4]); } - /// Draw a circle at `position` with the flat side facing `normal`. + /// Draw a circle in 3D at `position` with the flat side facing `normal`. + /// + /// This should be called for each frame the circle needs to be rendered. /// /// # Example /// ``` @@ -221,7 +239,9 @@ impl<'s> Gizmos<'s> { } } - /// Draw a wireframe sphere made out of 3 circles. + /// Draw a wireframe sphere in 3D made out of 3 circles around the axes. + /// + /// This should be called for each frame the sphere needs to be rendered. /// /// # Example /// ``` @@ -257,7 +277,9 @@ impl<'s> Gizmos<'s> { } } - /// Draw a wireframe rectangle. + /// Draw a wireframe rectangle in 3D. + /// + /// This should be called for each frame the rectangle needs to be rendered. /// /// # Example /// ``` @@ -275,7 +297,9 @@ impl<'s> Gizmos<'s> { self.linestrip([tl, tr, br, bl, tl], color); } - /// Draw a wireframe cube. + /// Draw a wireframe cube in 3D. + /// + /// This should be called for each frame the cube needs to be rendered. /// /// # Example /// ``` @@ -308,7 +332,9 @@ impl<'s> Gizmos<'s> { self.add_list_color(color, 6); } - /// Draw a line from `start` to `end`. + /// Draw a line in 2D from `start` to `end`. + /// + /// This should be called for each frame the line needs to be rendered. /// /// # Example /// ``` @@ -325,7 +351,9 @@ impl<'s> Gizmos<'s> { self.line(start.extend(0.), end.extend(0.), color); } - /// Draw a line with a color gradient from `start` to `end`. + /// Draw a line in 2D with a color gradient from `start` to `end`. + /// + /// This should be called for each frame the line needs to be rendered. /// /// # Example /// ``` @@ -348,7 +376,9 @@ impl<'s> Gizmos<'s> { self.line_gradient(start.extend(0.), end.extend(0.), start_color, end_color); } - /// Draw lines between a list of points. + /// Draw a line in 2D made of straight segments between the points. + /// + /// This should be called for each frame the line needs to be rendered. /// /// # Example /// ``` @@ -365,7 +395,9 @@ impl<'s> Gizmos<'s> { self.linestrip(positions.into_iter().map(|vec2| vec2.extend(0.)), color); } - /// Draw lines between a list of points with a color gradient. + /// Draw a line in 2D made of straight segments between the points, with a color gradient. + /// + /// This should be called for each frame the line needs to be rendered. /// /// # Example /// ``` @@ -390,7 +422,9 @@ impl<'s> Gizmos<'s> { ); } - /// Draw a line from `start` to `start + vector`. + /// Draw a line in 2D from `start` to `start + vector`. + /// + /// This should be called for each frame the line needs to be rendered. /// /// # Example /// ``` @@ -407,7 +441,9 @@ impl<'s> Gizmos<'s> { self.line_2d(start, start + vector, color); } - /// Draw a line with a color gradient from `start` to `start + vector`. + /// Draw a line in 2D with a color gradient from `start` to `start + vector`. + /// + /// This should be called for each frame the line needs to be rendered. /// /// # Example /// ``` @@ -430,7 +466,9 @@ impl<'s> Gizmos<'s> { self.line_gradient_2d(start, start + vector, start_color, end_color); } - /// Draw a circle. + /// Draw a circle in 2D. + /// + /// This should be called for each frame the circle needs to be rendered. /// /// # Example /// ``` @@ -464,13 +502,16 @@ impl<'s> Gizmos<'s> { } } - /// Draw an arc, which is a part of the circumference of a circle. + /// Draw an arc, which is a part of the circumference of a circle, in 2D. + /// + /// This should be called for each frame the arc needs to be rendered. /// /// # Arguments /// - `position` sets the center of this circle. /// - `radius` controls the distance from `position` to this arc, and thus its curvature. - /// - `direction_angle` sets the angle in radians between `position` and the midpoint of the arc. - /// -`arc_angle` sets the length of this arc, in radians. + /// - `direction_angle` sets the clockwise angle in radians between `Vec2::Y` and + /// the vector from `position` to the midpoint of the arc. + /// - `arc_angle` sets the length of this arc, in radians. /// /// # Example /// ``` @@ -509,7 +550,9 @@ impl<'s> Gizmos<'s> { } } - /// Draw a wireframe rectangle. + /// Draw a wireframe rectangle in 2D. + /// + /// This should be called for each frame the rectangle needs to be rendered. /// /// # Example /// ```