Add GlobalOutlineMode. Change plugin to not be ZST.

komadori · komadori · commit 6902a1a1bf57 · 2026-05-21T23:53:34.000+01:00
diff --git a/examples/alpha_mask.rs b/examples/alpha_mask.rs
@@ -5,7 +5,7 @@ use std::f32::consts::TAU;
 fn main() {
     App::new()
         .insert_resource(ClearColor(Color::srgb(0.1, 0.1, 0.1)))
-        .add_plugins((DefaultPlugins, OutlinePlugin))
+        .add_plugins((DefaultPlugins, OutlinePlugin::JUMP_FLOOD))
         .add_systems(Startup, setup)
         .add_systems(Update, pulse_outline_thickness)
         .run();
@@ -64,7 +64,6 @@ fn setup(
             colour: Color::srgb(1.0, 1.0, 0.0),
             width: 0.0,
         },
-        OutlineMode::FloodFlat,
         OutlineAlphaMask {
             texture: Some(alpha_mask_handle),
             channel: TextureChannel::R,
diff --git a/examples/animated_fox.rs b/examples/animated_fox.rs
@@ -12,7 +12,7 @@ fn main() {
     App::new()
         .add_plugins((
             DefaultPlugins,
-            OutlinePlugin,
+            OutlinePlugin::EXTRUDE_VERTEX,
             AutoGenerateOutlineNormalsPlugin::default(),
         ))
         .insert_resource(GlobalAmbientLight::default())
diff --git a/examples/bloom.rs b/examples/bloom.rs
@@ -12,7 +12,7 @@ use bevy_mod_outline::*;
 fn main() {
     App::new()
         .insert_resource(ClearColor(Color::BLACK))
-        .add_plugins((DefaultPlugins, OutlinePlugin))
+        .add_plugins((DefaultPlugins, OutlinePlugin::EXTRUDE_VERTEX))
         .add_systems(Startup, setup)
         .add_systems(Update, (rotates, pulses))
         .run();
diff --git a/examples/flying_objects.rs b/examples/flying_objects.rs
@@ -8,7 +8,7 @@ use bevy_mod_outline::*;
 fn main() {
     App::new()
         .insert_resource(ClearColor(Color::BLACK))
-        .add_plugins((DefaultPlugins, OutlinePlugin))
+        .add_plugins((DefaultPlugins, OutlinePlugin::EXTRUDE_VERTEX))
         .add_systems(Startup, setup)
         .add_systems(Update, (spawn_objects, move_objects, despawn_objects))
         .run();
diff --git a/examples/hollow.rs b/examples/hollow.rs
@@ -14,7 +14,7 @@ fn main() {
                     .add_custom_vertex_attribute("_OUTLINE_NORMAL", ATTRIBUTE_OUTLINE_NORMAL),
             ),
         )
-        .add_plugins(OutlinePlugin)
+        .add_plugins(OutlinePlugin::EXTRUDE_VERTEX)
         .insert_resource(GlobalAmbientLight::default())
         .add_systems(Startup, setup)
         .add_systems(
diff --git a/examples/morph_targets.rs b/examples/morph_targets.rs
@@ -22,7 +22,7 @@ fn main() {
                 }),
                 ..default()
             }),
-            OutlinePlugin,
+            OutlinePlugin::EXTRUDE_VERTEX,
             AutoGenerateOutlineNormalsPlugin::default(),
         ))
         .insert_resource(GlobalAmbientLight::default())
diff --git a/examples/picking.rs b/examples/picking.rs
@@ -7,7 +7,7 @@ struct Selected;
 
 fn main() {
     App::new()
-        .add_plugins((DefaultPlugins, MeshPickingPlugin, OutlinePlugin))
+        .add_plugins((DefaultPlugins, MeshPickingPlugin, OutlinePlugin::JUMP_FLOOD))
         .add_systems(Startup, setup)
         .add_systems(Update, rotate_selected)
         .run();
@@ -50,7 +50,6 @@ fn setup(
                     width: 5.0f32,
                     ..default()
                 },
-                OutlineMode::FloodFlat,
                 Pickable::default(),
             ))
             .observe(on_click);
diff --git a/examples/pieces.rs b/examples/pieces.rs
@@ -8,7 +8,7 @@ use bevy_mod_outline::*;
 fn main() {
     App::new()
         .insert_resource(ClearColor(Color::BLACK))
-        .add_plugins((DefaultPlugins, OutlinePlugin))
+        .add_plugins((DefaultPlugins, OutlinePlugin::EXTRUDE_VERTEX))
         .add_systems(Startup, setup)
         .add_systems(Update, rotates)
         .run();
diff --git a/examples/render_layers.rs b/examples/render_layers.rs
@@ -11,7 +11,7 @@ use bevy_mod_outline::{OutlinePlugin, OutlineRenderLayers, OutlineVolume};
 fn main() {
     App::new()
         .insert_resource(ClearColor(Color::BLACK))
-        .add_plugins((DefaultPlugins, OutlinePlugin))
+        .add_plugins((DefaultPlugins, OutlinePlugin::EXTRUDE_VERTEX))
         .add_systems(Startup, setup)
         .add_systems(Update, set_camera_viewports)
         .run();
diff --git a/examples/shapes.rs b/examples/shapes.rs
@@ -8,7 +8,7 @@ use bevy_mod_outline::*;
 fn main() {
     App::new()
         .insert_resource(ClearColor(Color::BLACK))
-        .add_plugins((DefaultPlugins, OutlinePlugin))
+        .add_plugins((DefaultPlugins, OutlinePlugin::EXTRUDE_VERTEX))
         .add_systems(Startup, setup)
         .add_systems(Update, (wobble, orbit))
         .run();
diff --git a/examples/ui_aa.rs b/examples/ui_aa.rs
@@ -13,7 +13,7 @@ use bevy_mod_outline::*;
 fn main() {
     App::new()
         .insert_resource(ClearColor(Color::BLACK))
-        .add_plugins((DefaultPlugins, OutlinePlugin))
+        .add_plugins((DefaultPlugins, OutlinePlugin::EXTRUDE_VERTEX))
         .insert_state(AAMode::NoAA)
         .add_systems(Startup, setup)
         .add_systems(Update, (bounce, highlight, interaction))
diff --git a/examples/ui_mode.rs b/examples/ui_mode.rs
@@ -15,7 +15,7 @@ fn main() {
         .insert_resource(ClearColor(Color::BLACK))
         .add_plugins((
             DefaultPlugins,
-            OutlinePlugin,
+            OutlinePlugin::EXTRUDE_VERTEX,
             WireframePlugin {
                 debug_flags: RenderDebugFlags::empty(),
             },
diff --git a/src/computed.rs b/src/computed.rs
@@ -3,8 +3,9 @@ use bevy::{camera::visibility::RenderLayers, ecs::query::QueryItem, prelude::*};
 use crate::{
     pipeline_key::ComputedOutlineKey,
     uniforms::{DepthMode, DrawMode},
-    InheritOutline, OutlineAlphaMask, OutlineFace, OutlineMode, OutlinePlaneDepth,
-    OutlineRenderLayers, OutlineStencil, OutlineStencilEnabled, OutlineVolume, OutlineWarmUp,
+    GlobalOutlineMode, InheritOutline, OutlineAlphaMask, OutlineFace, OutlineMode,
+    OutlinePlaneDepth, OutlineRenderLayers, OutlineStencil, OutlineStencilEnabled, OutlineVolume,
+    OutlineWarmUp,
 };
 
 #[derive(Clone)]
@@ -156,6 +157,7 @@ type OutlineComponents<'a> = (
 
 #[allow(clippy::type_complexity)]
 pub(crate) fn compute_outline(
+    global_outline_mode: Res<GlobalOutlineMode>,
     mut root_query: Query<
         (
             Entity,
@@ -169,7 +171,14 @@ pub(crate) fn compute_outline(
     child_query: Query<&Children>,
 ) {
     for (entity, mut computed, components, children) in root_query.iter_mut() {
-        let changed = update_computed_outline(&mut computed, components, None, None, false);
+        let changed = update_computed_outline(
+            &mut computed,
+            components,
+            None,
+            None,
+            global_outline_mode.is_changed(),
+            &global_outline_mode,
+        );
         if let Some(cs) = children {
             let parent_computed = computed.0.as_ref().unwrap();
             for child in cs.iter() {
@@ -180,6 +189,7 @@ pub(crate) fn compute_outline(
                     child,
                     &mut child_query_mut,
                     &child_query,
+                    &global_outline_mode,
                 );
             }
         }
@@ -193,6 +203,7 @@ fn propagate_computed_outline(
     entity: Entity,
     child_query_mut: &mut Query<(&mut ComputedOutline, OutlineComponents), With<InheritOutline>>,
     child_query: &Query<&Children>,
+    global_outline_mode: &GlobalOutlineMode,
 ) {
     if let Ok((mut computed, components)) = child_query_mut.get_mut(entity) {
         let changed = update_computed_outline(
@@ -201,6 +212,7 @@ fn propagate_computed_outline(
             Some(parent_computed),
             Some(parent_entity),
             parent_changed,
+            global_outline_mode,
         );
         if let Ok(cs) = child_query.get(entity) {
             let parent_computed = &computed.0.as_ref().unwrap().clone();
@@ -212,6 +224,7 @@ fn propagate_computed_outline(
                     child,
                     child_query_mut,
                     child_query,
+                    global_outline_mode,
                 );
             }
         }
@@ -236,6 +249,7 @@ fn update_computed_outline(
     parent_computed: Option<&ComputedInternal>,
     parent_entity: Option<Entity>,
     force_update: bool,
+    global_outline_mode: &GlobalOutlineMode,
 ) -> bool {
     let has_parent = parent_computed.is_some();
     let changed = force_update
@@ -280,8 +294,9 @@ fn update_computed_outline(
                     offset: sten.offset,
                 },
             ),
-            mode: Sourced::set(
+            mode: Sourced::set_with_default(
                 mode,
+                &global_outline_mode.0,
                 parent_computed.map(|p| p.mode.value.clone()),
                 |mode| match mode {
                     OutlineMode::ExtrudeFlat => ComputedMode {
@@ -352,6 +367,7 @@ mod tests {
 
     fn setup() -> (App, Entity) {
         let mut app = App::new();
+        app.init_resource::<GlobalOutlineMode>();
         app.add_systems(Update, compute_outline);
         let entity = app
             .world_mut()
diff --git a/src/lib.rs b/src/lib.rs
@@ -21,13 +21,20 @@
 //! Outlines can be inherited from the parent via the [`InheritOutline`]
 //! component.
 //!
-//! Vertex extrusion works best with meshes that have smooth surfaces. To
-//! avoid visual artefacts when outlining meshes with hard edges, see the
-//! [`OutlineMeshExt::generate_outline_normals`] function and the
-//! [`AutoGenerateOutlineNormalsPlugin`].
+//! There are two methods available for rendering outlines: vertex extrusion
+//! and jump flood. The default method is selected by adding either
+//! [`OutlinePlugin::EXTRUDE_VERTEX`] or [`OutlinePlugin::JUMP_FLOOD`], and
+//! can be overridden for individual entities via the [`OutlineMode`]
+//! component.
+//!
+//! Vertex extrusion is generally more performant, but is sensitive to the
+//! fidelity of meshes and requires smooth outline normals to avoid visual
+//! artefacts. See the [`OutlineMeshExt::generate_outline_normals`] function
+//! and the [`AutoGenerateOutlineNormalsPlugin`] for help generating these.
 //!
-//! Jump flood support is currently experimental and can be enabled by
-//! adding the [`OutlineMode::FloodFlat`] component.
+//! Jump flood, as a screen-space technique, is more robust especially with
+//! thicker outlines. However, it requires `log2(n)` shader passes over the
+//! outline's bounding box where `n` is the thickness in screen pixels.
 
 use std::any::TypeId;
 
@@ -270,11 +277,19 @@ pub enum OutlineMode {
     ExtrudeFlat,
     /// Vertex extrusion in real model-space.
     ExtrudeReal,
-    // Jump-flood into a billboard.
+    /// Jump-flood into a billboard.
     #[cfg(feature = "flood")]
     FloodFlat,
 }
 
+/// A resource which controls the default [`OutlineMode`] used when an entity
+/// does not have an [`OutlineMode`] component and does not inherit one from
+/// a parent.
+#[derive(Clone, Default, Resource, Deref)]
+#[cfg_attr(feature = "reflect", derive(Reflect))]
+#[cfg_attr(feature = "reflect", reflect(Resource, Default))]
+pub struct GlobalOutlineMode(pub OutlineMode);
+
 /// A component which controls which faces of an outline are rendered.
 #[derive(Clone, Component, Default)]
 #[cfg_attr(feature = "reflect", derive(Reflect))]
@@ -433,7 +448,24 @@ fn add_dummy_phase_buffers(
 }
 
 /// Adds support for rendering outlines.
-pub struct OutlinePlugin;
+pub struct OutlinePlugin {
+    mode: OutlineMode,
+}
+
+impl OutlinePlugin {
+    /// An [`OutlinePlugin`] configured to use vertex extrusion outlines by
+    /// default. See [`OutlineMode::ExtrudeFlat`].
+    pub const EXTRUDE_VERTEX: Self = Self {
+        mode: OutlineMode::ExtrudeFlat,
+    };
+
+    /// An [`OutlinePlugin`] configured to use jump-flood outlines by default.
+    /// See [`OutlineMode::FloodFlat`].
+    #[cfg(feature = "flood")]
+    pub const JUMP_FLOOD: Self = Self {
+        mode: OutlineMode::FloodFlat,
+    };
+}
 
 impl Plugin for OutlinePlugin {
     fn build(&self, app: &mut App) {
@@ -467,6 +499,7 @@ impl Plugin for OutlinePlugin {
         .register_required_components::<OutlineStencil, ComputedOutline>()
         .register_required_components::<OutlineVolume, ComputedOutline>()
         .register_required_components::<InheritOutline, ComputedOutline>()
+        .insert_resource(GlobalOutlineMode(self.mode.clone()))
         .init_resource::<OutlineEntitiesNeedingSpecialisation>()
         .init_resource::<OutlineVisibleEntities>()
         .add_systems(
@@ -561,6 +594,7 @@ impl Plugin for OutlinePlugin {
             .register_type::<OutlineVolume>()
             .register_type::<OutlineRenderLayers>()
             .register_type::<OutlineMode>()
+            .register_type::<GlobalOutlineMode>()
             .register_type::<OutlineFace>()
             .register_type::<OutlineAlphaMask>()
             .register_type::<InheritOutline>()

Original file line number	Diff line number	Diff line change
`@@ -14,7 +14,7 @@ fn main() {`
`14`	`14`	`.add_custom_vertex_attribute("_OUTLINE_NORMAL", ATTRIBUTE_OUTLINE_NORMAL),`
`15`	`15`	`),`
`16`	`16`	`)`
`17`		`- .add_plugins(OutlinePlugin)`
	`17`	`+ .add_plugins(OutlinePlugin::EXTRUDE_VERTEX)`
`18`	`18`	`.insert_resource(GlobalAmbientLight::default())`
`19`	`19`	`.add_systems(Startup, setup)`
`20`	`20`	`.add_systems(`