forestia/bevy
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Clarify immediate mode in Gizmos documentation (#9183)

Browse Source 
# 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 <mockersf@gmail.com>
Co-authored-by: SpecificProtagonist <vincentjunge@posteo.net>
Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
This commit is contained in:
Sélène Amanita 2023-07-31 20:14:52 +01:00 committed by GitHub
parent 6993a78a56
commit 8320dc31df
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 64 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
crates/bevy_gizmos/src/gizmos.rs
View File

@ -24,6 +24,10 @@ pub(crate) struct GizmoStorage {
} }
/// A [`SystemParam`](bevy_ecs::system::SystemParam) for drawing gizmos. /// 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)] #[derive(SystemParam)]
pub struct Gizmos<'s> { pub struct Gizmos<'s> {
buffer: Deferred<'s, GizmoBuffer>, buffer: Deferred<'s, GizmoBuffer>,
@ -48,7 +52,9 @@ impl SystemBuffer for GizmoBuffer {
} }
impl<'s> Gizmos<'s> { 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 /// # Example
/// ``` /// ```
@ -66,7 +72,9 @@ impl<'s> Gizmos<'s> {
self.add_list_color(color, 2); 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 /// # Example
/// ``` /// ```
@ -84,7 +92,9 @@ impl<'s> Gizmos<'s> {
self.extend_list_colors([start_color, end_color]); 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 /// # Example
/// ``` /// ```
@ -101,7 +111,9 @@ impl<'s> Gizmos<'s> {
self.line(start, start + vector, color); 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 /// # Example
/// ``` /// ```
@ -124,7 +136,9 @@ impl<'s> Gizmos<'s> {
self.line_gradient(start, start + vector, start_color, end_color); 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 /// # Example
/// ``` /// ```
@ -146,7 +160,9 @@ impl<'s> Gizmos<'s> {
self.buffer.strip_colors.push([f32::NAN; 4]); 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 /// # Example
/// ``` /// ```
@ -185,7 +201,9 @@ impl<'s> Gizmos<'s> {
strip_colors.push([f32::NAN; 4]); 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 /// # 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 /// # 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 /// # Example
/// ``` /// ```
@ -275,7 +297,9 @@ impl<'s> Gizmos<'s> {
self.linestrip([tl, tr, br, bl, tl], color); 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 /// # Example
/// ``` /// ```
@ -308,7 +332,9 @@ impl<'s> Gizmos<'s> {
self.add_list_color(color, 6); 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 /// # Example
/// ``` /// ```
@ -325,7 +351,9 @@ impl<'s> Gizmos<'s> {
self.line(start.extend(0.), end.extend(0.), color); 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 /// # Example
/// ``` /// ```
@ -348,7 +376,9 @@ impl<'s> Gizmos<'s> {
self.line_gradient(start.extend(0.), end.extend(0.), start_color, end_color); 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 /// # Example
/// ``` /// ```
@ -365,7 +395,9 @@ impl<'s> Gizmos<'s> {
self.linestrip(positions.into_iter().map(|vec2| vec2.extend(0.)), color); 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 /// # 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 /// # Example
/// ``` /// ```
@ -407,7 +441,9 @@ impl<'s> Gizmos<'s> {
self.line_2d(start, start + vector, color); 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 /// # Example
/// ``` /// ```
@ -430,7 +466,9 @@ impl<'s> Gizmos<'s> {
self.line_gradient_2d(start, start + vector, start_color, end_color); 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 /// # 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 /// # Arguments
/// - `position` sets the center of this circle. /// - `position` sets the center of this circle.
/// - `radius` controls the distance from `position` to this arc, and thus its curvature. /// - `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. /// - `direction_angle` sets the clockwise angle in radians between `Vec2::Y` and
/// -`arc_angle` sets the length of this arc, in radians. /// the vector from `position` to the midpoint of the arc.
/// - `arc_angle` sets the length of this arc, in radians.
/// ///
/// # Example /// # 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 /// # Example
/// ``` /// ```