Mirrors/bevy
2
0
Fork 0
mirror of https://github.com/bevyengine/bevy synced 2024-09-20 06:22:01 +00:00
Code Issues Projects Releases Packages 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 Carter Anderson
parent 812d11b1e3
commit c8ed5298f0
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.
///
/// 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
/// ```