Retained Gizmos

[tim-blackbird]

Objective

Add a way to use the gizmo API in a retained manner, for increased performance.

Solution

• Move gizmo API from Gizmos to GizmoBuffer, abusing 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 LineGizmos.

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

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 Gizmos

[tim-blackbird]

This shows an instance where the use of DerefMut can cause compilation errors.
This issue of partial borrows is already a problem for the Mut returned by mutable query items for example. (Polonius pls 🙏)

[IceSentry]

I kinda like GizmoAsset because it uses the asset system and it doesn't have the retained naming, but I'm honestly not sure either.

[tychedelia]

I kinda like GizmoAsset because it uses the asset system and it doesn't have the retained naming, but I'm honestly not sure either.

We just don't use FooAsset anywhere else, do we?

[pablo-lua]

Any thoughts on alternative names for LineGizmo?

None, but I think Gizmo is a good idea to follow.

[tim-blackbird]

I've thought about it a bit more and decided to go through with removing the 'line' naming from this PR, see the Rename commit(dbdb9ad) for the changes to naming and docs

[alice-i-cecile]

Bumping to 0.16, sorry. Rendering's stability is too poor to merge this right now.

[aevyrie]

This is really nice.

I realize this is a bikeshed, but I'd like to point out that the name Gizmo truly makes no sense any more. This is just polyline rendering with an immediate and retained API, and helpers to convert primitive shapes into polylines.

[alice-i-cecile]

@tim-blackbird I like this and it's well-reviewed. Can you resolve merge conflicts and ping me to merge please?

[alice-i-cecile]

Thank you to everyone involved with the authoring or reviewing of this PR! This work is relatively important and needs release notes! Head over to bevyengine/bevy-website#1963 if you'd like to help out.