Rename and clarify how to embed contexts inside of eachother

crates/bevy_gizmos/src/circles.rs

@@ -237,7 +237,6 @@ where
     segments: usize,
 }
 
-
 impl<Config, Clear> Ellipse2dBuilder<'_, '_, '_, Config, Clear>
 where
     Config: GizmoConfigGroup,

crates/bevy_gizmos/src/gizmos.rs

@@ -78,11 +78,11 @@ where
     }
 }
 
-/// Swap buffer for gizmos.
+/// Swap buffer for a specific clearing context.
 ///
-/// This is to stash/store the default gizmos so another context can
+/// This is to stash/store the default/requested gizmos so another context can
 /// be substituted for that duration.
-pub(crate) struct Swap;
+pub struct Swap<Clear>(PhantomData<Clear>);
 
 /// A [`SystemParam`] for drawing gizmos.
 ///
@@ -102,7 +102,7 @@ pub(crate) struct Swap;
 /// to [`FixedMain`](bevy_app::FixedMain)):
 ///
 /// ```
-/// use bevy_gizmos::{*, gizmos::GizmoStorage};
+/// use bevy_gizmos::{prelude::*, *, gizmos::GizmoStorage};
 /// # use bevy_app::prelude::*;
 /// # use bevy_ecs::{schedule::ScheduleLabel, prelude::*};
 /// # #[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
@@ -117,16 +117,18 @@ pub(crate) struct Swap;
 /// struct ClearContextSetup;
 /// impl Plugin for ClearContextSetup {
 ///     fn build(&self, app: &mut App) {
-///         app.init_resource::<GizmoStorage<MyContext>>()
-///            .add_systems(StartOfMyContext, stash_default_gizmos)
-///            // If not running multiple times, put this with [`stash_default_gizmos`].
-///            .add_systems(StartOfRun, clear_gizmo_context::<MyContext>)
-///            // If not running multiple times, put this with [`pop_default_gizmos`].
-///            .add_systems(EndOfRun, collect_default_gizmos::<MyContext>)
-///            .add_systems(EndOfMyContext, pop_default_gizmos)
+///         app.init_resource::<GizmoStorage<DefaultGizmoConfigGroup, MyContext>>()
+///            // Make sure this context starts/ends cleanly if inside another context. E.g. it
+///            // should start after the parent context starts and end after the parent context ends.
+///            .add_systems(StartOfMyContext, start_gizmo_context::<DefaultGizmoConfigGroup, MyContext>)
+///            // If not running multiple times, put this with [`start_gizmo_context`].
+///            .add_systems(StartOfRun, clear_gizmo_context::<DefaultGizmoConfigGroup, MyContext>)
+///            // If not running multiple times, put this with [`end_gizmo_context`].
+///            .add_systems(EndOfRun, collect_requested_gizmos::<DefaultGizmoConfigGroup, MyContext>)
+///            .add_systems(EndOfMyContext, end_gizmo_context::<DefaultGizmoConfigGroup, MyContext>)
 ///            .add_systems(
 ///                Last,
-///                propagate_gizmos::<MyContext>.before(UpdateGizmoMeshes),
+///                propagate_gizmos::<DefaultGizmoConfigGroup, MyContext>.before(UpdateGizmoMeshes),
 ///            );
 ///     }
 /// }

crates/bevy_gizmos/src/lib.rs

@@ -187,18 +187,18 @@ impl AppGizmoBuilder for App {
         handles.list.insert(TypeId::of::<Config>(), None);
         handles.strip.insert(TypeId::of::<Config>(), None);
 
-        self.init_resource::<GizmoStorage<Config, Swap>>()
-            .init_resource::<GizmoStorage<Config, ()>>()
+        self.init_resource::<GizmoStorage<Config, ()>>()
             .init_resource::<GizmoStorage<Config, Fixed>>()
+            .init_resource::<GizmoStorage<Config, Swap<Fixed>>>()
             .add_systems(
                 RunFixedMainLoop,
-                stash_default_gizmos::<Config>.before(bevy_time::run_fixed_main_schedule),
+                start_gizmo_context::<Config, Fixed>.before(bevy_time::run_fixed_main_schedule),
             )
             .add_systems(FixedFirst, clear_gizmo_context::<Config, Fixed>)
-            .add_systems(FixedLast, collect_default_gizmos::<Config, Fixed>)
+            .add_systems(FixedLast, collect_requested_gizmos::<Config, Fixed>)
             .add_systems(
                 RunFixedMainLoop,
-                pop_default_gizmos::<Config>.after(bevy_time::run_fixed_main_schedule),
+                end_gizmo_context::<Config, Fixed>.after(bevy_time::run_fixed_main_schedule),
             )
             .add_systems(
                 Last,
@@ -237,28 +237,36 @@ struct LineGizmoHandles {
     strip: TypeIdMap<Option<Handle<LineGizmo>>>,
 }
 
-/// Stash the default gizmos context in the [`Swap`] gizmo storage.
-pub fn stash_default_gizmos<Config>(world: &mut World)
+/// Start a new gizmo clearing context.
+///
+/// Internally this pushes the parent default context into a swap buffer.
+/// Gizmo contexts should be handled like a stack, so if you push a new context,
+/// you must pop the context before the parent context ends.
+pub fn start_gizmo_context<Config, Clear>(world: &mut World)
 where
     Config: GizmoConfigGroup,
+    Clear: 'static + Send + Sync,
 {
     world.resource_scope(
-        |world: &mut World, mut swap: Mut<GizmoStorage<Config, Swap>>| {
+        |world: &mut World, mut swap: Mut<GizmoStorage<Config, Swap<Clear>>>| {
             let mut default = world.resource_mut::<GizmoStorage<Config, ()>>();
             default.swap(&mut *swap);
         },
     );
 }
 
-/// Pop the default gizmos context out of the [`Swap`] gizmo storage.
+/// End this gizmo clearing context.
+///
+/// Pop the default gizmos context out of the [`Swap<Clear>`] gizmo storage.
 ///
 /// This must be called before [`UpdateGizmoMeshes`] in the [`Last`] schedule.
-pub fn pop_default_gizmos<Config>(world: &mut World)
+pub fn end_gizmo_context<Config, Clear>(world: &mut World)
 where
     Config: GizmoConfigGroup,
+    Clear: 'static + Send + Sync,
 {
     world.resource_scope(
-        |world: &mut World, mut swap: Mut<GizmoStorage<Config, Swap>>| {
+        |world: &mut World, mut swap: Mut<GizmoStorage<Config, Swap<Clear>>>| {
             let mut default = world.resource_mut::<GizmoStorage<Config, ()>>();
             default.clear();
             default.swap(&mut *swap);
@@ -267,7 +275,7 @@ where
 }
 
 /// Collect the requested gizmos into a specific clear context.
-pub fn collect_default_gizmos<Config, Clear>(world: &mut World)
+pub fn collect_requested_gizmos<Config, Clear>(world: &mut World)
 where
     Config: GizmoConfigGroup,
     Clear: 'static + Send + Sync,