Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Clarify immediate mode in Gizmos documentation #9183

Merged
merged 7 commits into from
Jul 31, 2023
Merged

Clarify immediate mode in Gizmos documentation #9183

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
6cab6d0
Clarify immediate mode in Gizmos documentation
Selene-Amanita Jul 17, 2023
ea1ceb7
Typo
Selene-Amanita Jul 17, 2023
9e05b6e
Proposed changes by SpecificProtagonist: mention Last schedule and re…
Selene-Amanita Jul 17, 2023
0be2cc4
Apply suggestions from code review
Selene-Amanita Jul 17, 2023
30daec8
Proposed changes by SpecificProtagonist: delete "end of current frame…
Selene-Amanita Jul 17, 2023
82ea9df
Update crates/bevy_gizmos/src/gizmos.rs
Selene-Amanita Jul 18, 2023
d7597a4
Proposed change by alice-i-cecile
Selene-Amanita Jul 18, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 64 additions & 21 deletions crates/bevy_gizmos/src/gizmos.rs
View file
Open in desktop
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.
///
Selene-Amanita marked this conversation as resolved.
Show resolved Hide resolved
/// # 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