bevy/crates/bevy_gizmos/src/grid.rs
Tim d2a07f9f72
Retained Gizmos (#15473)
# Objective
Add a way to use the gizmo API in a retained manner, for increased
performance.

## Solution
- Move gizmo API from `Gizmos` to `GizmoBuffer`, ~ab~using `Deref` to
keep usage the same as before.
- Merge non-strip and strip variant of `LineGizmo` into one, storing the
data in a `GizmoBuffer` to have the same API for retained `LineGizmo`s.

### Review guide
- The meat of the changes are in `lib.rs`, `retained.rs`, `gizmos.rs`,
`pipeline_3d.rs` and `pipeline_2d.rs`
- The other files contain almost exclusively the churn from moving the
gizmo API from `Gizmos` to `GizmoBuffer`

## Testing
### Performance

Performance compared to the immediate mode API is from 65 to 80 times
better for static lines.

```
7900 XTX, 3700X
1707.9k lines/ms: gizmos_retained (21.3ms)
3488.5k lines/ms: gizmos_retained_continuous_polyline (31.3ms)
   0.5k lines/ms: gizmos_retained_separate (97.7ms)

3054.9k lines/ms: bevy_polyline_retained_nan (16.8ms)
3596.3k lines/ms: bevy_polyline_retained_continuous_polyline (14.2ms)
   0.6k lines/ms: bevy_polyline_retained_separate (78.9ms)

  26.9k lines/ms: gizmos_immediate (14.9ms)
  43.8k lines/ms: gizmos_immediate_continuous_polyline (18.3ms)
```
Looks like performance is good enough, being close to par with
`bevy_polyline`.

Benchmarks can be found here: 
This branch:
https://github.com/tim-blackbird/line_racing/tree/retained-gizmos
Bevy 0.14: https://github.com/DGriffin91/line_racing

## Showcase
```rust 
fn setup(
    mut commands: Commands,
    mut gizmo_assets: ResMut<Assets<GizmoAsset>>
) {
    let mut gizmo = GizmoAsset::default();

    // A sphere made out of one million lines!
    gizmo
        .sphere(default(), 1., CRIMSON)
        .resolution(1_000_000 / 3);

    commands.spawn(Gizmo {
        handle: gizmo_assets.add(gizmo),
        ..default()
    });
}
```

## Follow-up work
- Port over to the retained rendering world proper
- Calculate visibility and cull `Gizmo`s
2024-12-04 21:21:06 +00:00

434 lines
14 KiB
Rust

//! Additional [`GizmoBuffer`] Functions -- Grids
//!
//! Includes the implementation of [`GizmoBuffer::grid`] and [`GizmoBuffer::grid_2d`].
//! and assorted support items.
use crate::{gizmos::GizmoBuffer, prelude::GizmoConfigGroup};
use bevy_color::Color;
use bevy_math::{ops, Isometry2d, Isometry3d, Quat, UVec2, UVec3, Vec2, Vec3, Vec3Swizzles};
/// A builder returned by [`GizmoBuffer::grid_3d`]
pub struct GridBuilder3d<'a, Config, Clear>
where
Config: GizmoConfigGroup,
Clear: 'static + Send + Sync,
{
gizmos: &'a mut GizmoBuffer<Config, Clear>,
isometry: Isometry3d,
spacing: Vec3,
cell_count: UVec3,
skew: Vec3,
outer_edges: [bool; 3],
color: Color,
}
/// A builder returned by [`GizmoBuffer::grid`] and [`GizmoBuffer::grid_2d`]
pub struct GridBuilder2d<'a, Config, Clear>
where
Config: GizmoConfigGroup,
Clear: 'static + Send + Sync,
{
gizmos: &'a mut GizmoBuffer<Config, Clear>,
isometry: Isometry3d,
spacing: Vec2,
cell_count: UVec2,
skew: Vec2,
outer_edges: [bool; 2],
color: Color,
}
impl<Config, Clear> GridBuilder3d<'_, Config, Clear>
where
Config: GizmoConfigGroup,
Clear: 'static + Send + Sync,
{
/// Skews the grid by `tan(skew)` in the x direction.
/// `skew` is in radians
pub fn skew_x(mut self, skew: f32) -> Self {
self.skew.x = skew;
self
}
/// Skews the grid by `tan(skew)` in the y direction.
/// `skew` is in radians
pub fn skew_y(mut self, skew: f32) -> Self {
self.skew.y = skew;
self
}
/// Skews the grid by `tan(skew)` in the z direction.
/// `skew` is in radians
pub fn skew_z(mut self, skew: f32) -> Self {
self.skew.z = skew;
self
}
/// Skews the grid by `tan(skew)` in the x, y and z directions.
/// `skew` is in radians
pub fn skew(mut self, skew: Vec3) -> Self {
self.skew = skew;
self
}
/// Declare that the outer edges of the grid along the x axis should be drawn.
/// By default, the outer edges will not be drawn.
pub fn outer_edges_x(mut self) -> Self {
self.outer_edges[0] = true;
self
}
/// Declare that the outer edges of the grid along the y axis should be drawn.
/// By default, the outer edges will not be drawn.
pub fn outer_edges_y(mut self) -> Self {
self.outer_edges[1] = true;
self
}
/// Declare that the outer edges of the grid along the z axis should be drawn.
/// By default, the outer edges will not be drawn.
pub fn outer_edges_z(mut self) -> Self {
self.outer_edges[2] = true;
self
}
/// Declare that all outer edges of the grid should be drawn.
/// By default, the outer edges will not be drawn.
pub fn outer_edges(mut self) -> Self {
self.outer_edges.fill(true);
self
}
}
impl<Config, Clear> GridBuilder2d<'_, Config, Clear>
where
Config: GizmoConfigGroup,
Clear: 'static + Send + Sync,
{
/// Skews the grid by `tan(skew)` in the x direction.
/// `skew` is in radians
pub fn skew_x(mut self, skew: f32) -> Self {
self.skew.x = skew;
self
}
/// Skews the grid by `tan(skew)` in the y direction.
/// `skew` is in radians
pub fn skew_y(mut self, skew: f32) -> Self {
self.skew.y = skew;
self
}
/// Skews the grid by `tan(skew)` in the x and y directions.
/// `skew` is in radians
pub fn skew(mut self, skew: Vec2) -> Self {
self.skew = skew;
self
}
/// Declare that the outer edges of the grid along the x axis should be drawn.
/// By default, the outer edges will not be drawn.
pub fn outer_edges_x(mut self) -> Self {
self.outer_edges[0] = true;
self
}
/// Declare that the outer edges of the grid along the y axis should be drawn.
/// By default, the outer edges will not be drawn.
pub fn outer_edges_y(mut self) -> Self {
self.outer_edges[1] = true;
self
}
/// Declare that all outer edges of the grid should be drawn.
/// By default, the outer edges will not be drawn.
pub fn outer_edges(mut self) -> Self {
self.outer_edges.fill(true);
self
}
}
impl<Config, Clear> Drop for GridBuilder3d<'_, Config, Clear>
where
Config: GizmoConfigGroup,
Clear: 'static + Send + Sync,
{
/// Draws a grid, by drawing lines with the stored [`GizmoBuffer`]
fn drop(&mut self) {
draw_grid(
self.gizmos,
self.isometry,
self.spacing,
self.cell_count,
self.skew,
self.outer_edges,
self.color,
);
}
}
impl<Config, Clear> Drop for GridBuilder2d<'_, Config, Clear>
where
Config: GizmoConfigGroup,
Clear: 'static + Send + Sync,
{
fn drop(&mut self) {
draw_grid(
self.gizmos,
self.isometry,
self.spacing.extend(0.),
self.cell_count.extend(0),
self.skew.extend(0.),
[self.outer_edges[0], self.outer_edges[1], true],
self.color,
);
}
}
impl<Config, Clear> GizmoBuffer<Config, Clear>
where
Config: GizmoConfigGroup,
Clear: 'static + Send + Sync,
{
/// Draw a 2D grid in 3D.
///
/// This should be called for each frame the grid needs to be rendered.
///
/// The grid's default orientation aligns with the XY-plane.
///
/// # Arguments
///
/// - `isometry` defines the translation and rotation of the grid.
/// - the translation specifies the center of the grid
/// - defines the orientation of the grid, by default
/// we assume the grid is contained in a plane parallel
/// to the XY plane
/// - `cell_count`: defines the amount of cells in the x and y axes
/// - `spacing`: defines the distance between cells along the x and y axes
/// - `color`: color of the grid
///
/// # Builder methods
///
/// - The skew of the grid can be adjusted using the `.skew(...)`, `.skew_x(...)` or `.skew_y(...)` methods. They behave very similar to their CSS equivalents.
/// - All outer edges can be toggled on or off using `.outer_edges(...)`. Alternatively you can use `.outer_edges_x(...)` or `.outer_edges_y(...)` to toggle the outer edges along an axis.
///
/// # Example
/// ```
/// # use bevy_gizmos::prelude::*;
/// # use bevy_math::prelude::*;
/// # use bevy_color::palettes::basic::GREEN;
/// fn system(mut gizmos: Gizmos) {
/// gizmos.grid(
/// Isometry3d::IDENTITY,
/// UVec2::new(10, 10),
/// Vec2::splat(2.),
/// GREEN
/// )
/// .skew_x(0.25)
/// .outer_edges();
/// }
/// # bevy_ecs::system::assert_is_system(system);
/// ```
pub fn grid(
&mut self,
isometry: impl Into<Isometry3d>,
cell_count: UVec2,
spacing: Vec2,
color: impl Into<Color>,
) -> GridBuilder2d<'_, Config, Clear> {
GridBuilder2d {
gizmos: self,
isometry: isometry.into(),
spacing,
cell_count,
skew: Vec2::ZERO,
outer_edges: [false, false],
color: color.into(),
}
}
/// Draw a 3D grid of voxel-like cells.
///
/// This should be called for each frame the grid needs to be rendered.
///
/// # Arguments
///
/// - `isometry` defines the translation and rotation of the grid.
/// - the translation specifies the center of the grid
/// - defines the orientation of the grid, by default
/// we assume the grid is aligned with all axes
/// - `cell_count`: defines the amount of cells in the x, y and z axes
/// - `spacing`: defines the distance between cells along the x, y and z axes
/// - `color`: color of the grid
///
/// # Builder methods
///
/// - The skew of the grid can be adjusted using the `.skew(...)`, `.skew_x(...)`, `.skew_y(...)` or `.skew_z(...)` methods. They behave very similar to their CSS equivalents.
/// - All outer edges can be toggled on or off using `.outer_edges(...)`. Alternatively you can use `.outer_edges_x(...)`, `.outer_edges_y(...)` or `.outer_edges_z(...)` to toggle the outer edges along an axis.
///
/// # Example
/// ```
/// # use bevy_gizmos::prelude::*;
/// # use bevy_math::prelude::*;
/// # use bevy_color::palettes::basic::GREEN;
/// fn system(mut gizmos: Gizmos) {
/// gizmos.grid_3d(
/// Isometry3d::IDENTITY,
/// UVec3::new(10, 2, 10),
/// Vec3::splat(2.),
/// GREEN
/// )
/// .skew_x(0.25)
/// .outer_edges();
/// }
/// # bevy_ecs::system::assert_is_system(system);
/// ```
pub fn grid_3d(
&mut self,
isometry: impl Into<Isometry3d>,
cell_count: UVec3,
spacing: Vec3,
color: impl Into<Color>,
) -> GridBuilder3d<'_, Config, Clear> {
GridBuilder3d {
gizmos: self,
isometry: isometry.into(),
spacing,
cell_count,
skew: Vec3::ZERO,
outer_edges: [false, false, false],
color: color.into(),
}
}
/// Draw a grid in 2D.
///
/// This should be called for each frame the grid needs to be rendered.
///
/// # Arguments
///
/// - `isometry` defines the translation and rotation of the grid.
/// - the translation specifies the center of the grid
/// - defines the orientation of the grid, by default
/// we assume the grid is aligned with all axes
/// - `cell_count`: defines the amount of cells in the x and y axes
/// - `spacing`: defines the distance between cells along the x and y axes
/// - `color`: color of the grid
///
/// # Builder methods
///
/// - The skew of the grid can be adjusted using the `.skew(...)`, `.skew_x(...)` or `.skew_y(...)` methods. They behave very similar to their CSS equivalents.
/// - All outer edges can be toggled on or off using `.outer_edges(...)`. Alternatively you can use `.outer_edges_x(...)` or `.outer_edges_y(...)` to toggle the outer edges along an axis.
///
/// # Example
/// ```
/// # use bevy_gizmos::prelude::*;
/// # use bevy_math::prelude::*;
/// # use bevy_color::palettes::basic::GREEN;
/// fn system(mut gizmos: Gizmos) {
/// gizmos.grid_2d(
/// Isometry2d::IDENTITY,
/// UVec2::new(10, 10),
/// Vec2::splat(1.),
/// GREEN
/// )
/// .skew_x(0.25)
/// .outer_edges();
/// }
/// # bevy_ecs::system::assert_is_system(system);
/// ```
pub fn grid_2d(
&mut self,
isometry: impl Into<Isometry2d>,
cell_count: UVec2,
spacing: Vec2,
color: impl Into<Color>,
) -> GridBuilder2d<'_, Config, Clear> {
let isometry = isometry.into();
GridBuilder2d {
gizmos: self,
isometry: Isometry3d::new(
isometry.translation.extend(0.0),
Quat::from_rotation_z(isometry.rotation.as_radians()),
),
spacing,
cell_count,
skew: Vec2::ZERO,
outer_edges: [false, false],
color: color.into(),
}
}
}
#[allow(clippy::too_many_arguments)]
fn draw_grid<Config, Clear>(
gizmos: &mut GizmoBuffer<Config, Clear>,
isometry: Isometry3d,
spacing: Vec3,
cell_count: UVec3,
skew: Vec3,
outer_edges: [bool; 3],
color: Color,
) where
Config: GizmoConfigGroup,
Clear: 'static + Send + Sync,
{
if !gizmos.enabled {
return;
}
#[inline]
fn or_zero(cond: bool, val: Vec3) -> Vec3 {
if cond {
val
} else {
Vec3::ZERO
}
}
// Offset between two adjacent grid cells along the x/y-axis and accounting for skew.
let skew_tan = Vec3::from(skew.to_array().map(ops::tan));
let dx = or_zero(
cell_count.x != 0,
spacing.x * Vec3::new(1., skew_tan.y, skew_tan.z),
);
let dy = or_zero(
cell_count.y != 0,
spacing.y * Vec3::new(skew_tan.x, 1., skew_tan.z),
);
let dz = or_zero(
cell_count.z != 0,
spacing.z * Vec3::new(skew_tan.x, skew_tan.y, 1.),
);
// Bottom-left-front corner of the grid
let cell_count_half = cell_count.as_vec3() * 0.5;
let grid_start = -cell_count_half.x * dx - cell_count_half.y * dy - cell_count_half.z * dz;
let outer_edges_u32 = UVec3::from(outer_edges.map(|v| v as u32));
let line_count = outer_edges_u32 * cell_count.saturating_add(UVec3::ONE)
+ (UVec3::ONE - outer_edges_u32) * cell_count.saturating_sub(UVec3::ONE);
let x_start = grid_start + or_zero(!outer_edges[0], dy + dz);
let y_start = grid_start + or_zero(!outer_edges[1], dx + dz);
let z_start = grid_start + or_zero(!outer_edges[2], dx + dy);
fn iter_lines(
delta_a: Vec3,
delta_b: Vec3,
delta_c: Vec3,
line_count: UVec2,
cell_count: u32,
start: Vec3,
) -> impl Iterator<Item = [Vec3; 2]> {
let dline = delta_a * cell_count as f32;
(0..line_count.x).map(|v| v as f32).flat_map(move |b| {
(0..line_count.y).map(|v| v as f32).map(move |c| {
let line_start = start + b * delta_b + c * delta_c;
let line_end = line_start + dline;
[line_start, line_end]
})
})
}
// Lines along the x direction
let x_lines = iter_lines(dx, dy, dz, line_count.yz(), cell_count.x, x_start);
// Lines along the y direction
let y_lines = iter_lines(dy, dz, dx, line_count.zx(), cell_count.y, y_start);
// Lines along the z direction
let z_lines = iter_lines(dz, dx, dy, line_count.xy(), cell_count.z, z_start);
x_lines
.chain(y_lines)
.chain(z_lines)
.map(|vec3s| vec3s.map(|vec3| isometry * vec3))
.for_each(|[start, end]| {
gizmos.line(start, end, color);
});
}