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 /// ```