Skip to content

Commit

Permalink
Clarify immediate mode in Gizmos documentation (#9183)
Browse files Browse the repository at this point in the history 
# 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>
  • Loading branch information
@Selene-Amanita @mockersf
@SpecificProtagonist @alice-i-cecile @cart
4 people authored and cart committed Aug 10, 2023
1 parent 812d11b commit c8ed529
Showing 1 changed file with 64 additions and 21 deletions.
85 changes: 64 additions & 21 deletions crates/bevy_gizmos/src/gizmos.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>,
Expand All @@ -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
/// ```
Expand All @@ -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
/// ```
Expand All @@ -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
/// ```
Expand All @@ -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
/// ```
Expand All @@ -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
/// ```
Expand All @@ -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
/// ```
Expand Down Expand Up @@ -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
/// ```
Expand Down Expand Up @@ -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
/// ```
Expand Down Expand Up @@ -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
/// ```
Expand All @@ -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
/// ```
Expand Down Expand Up @@ -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
/// ```
Expand All @@ -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
/// ```
Expand All @@ -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
/// ```
Expand All @@ -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
/// ```
Expand All @@ -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
/// ```
Expand All @@ -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
/// ```
Expand All @@ -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
/// ```
Expand Down Expand Up @@ -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
/// ```
Expand Down Expand Up @@ -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
/// ```
Expand Down

0 comments on commit c8ed529

Please sign in to comment.