Improve frustum culling of skinned meshes through per-joint bounds

Cargo.toml

@@ -4607,6 +4607,14 @@ doc-scrape-examples = true
 [package.metadata.example.test_invalid_skinned_mesh]
 hidden = true
 
+[[example]]
+name = "test_skinned_mesh_bounds"
+path = "tests/3d/test_skinned_mesh_bounds.rs"
+doc-scrape-examples = true
+
+[package.metadata.example.test_skinned_mesh_bounds]
+hidden = true
+
 [profile.wasm-release]
 inherits = "release"
 opt-level = "z"

crates/bevy_camera/src/visibility/mod.rs

@@ -6,6 +6,9 @@ use core::any::TypeId;
 use bevy_ecs::entity::{EntityHashMap, EntityHashSet};
 use bevy_ecs::lifecycle::HookContext;
 use bevy_ecs::world::DeferredWorld;
+use bevy_mesh::skinning::{
+    entity_aabb_from_skinned_mesh_bounds, SkinnedMesh, SkinnedMeshInverseBindposes,
+};
 use derive_more::derive::{Deref, DerefMut};
 pub use range::*;
 pub use render_layers::*;
@@ -216,6 +219,19 @@ impl ViewVisibility {
 #[reflect(Component, Default, Debug)]
 pub struct NoFrustumCulling;
 
+/// Use this component to enable dynamic skinned mesh bounds. The [`Aabb`]
+/// component of the skinned mesh will be automatically updated each frame based
+/// on the current joint transforms.
+///
+/// `DynamicSkinnedMeshBounds` depends on data from `Mesh::skinned_mesh_bounds`
+/// and `SkinnedMesh`. The resulting `Aabb` will reliably enclose meshes where
+/// vertex positions are only affected by skinning. But the `Aabb` may be larger
+/// than is optimal, and doesn't account for morph targets, vertex shaders, and
+/// anything else that modifies vertex positions.
+#[derive(Debug, Component, Default, Reflect)]
+#[reflect(Component, Default, Debug)]
+pub struct DynamicSkinnedMeshBounds;
+
 /// Collection of entities visible from the current view.
 ///
 /// This component contains all entities which are visible from the currently
@@ -368,7 +384,9 @@ impl Plugin for VisibilityPlugin {
             .add_systems(
                 PostUpdate,
                 (
-                    calculate_bounds.in_set(CalculateBounds),
+                    (calculate_bounds, update_skinned_mesh_bounds)
+                        .chain()
+                        .in_set(CalculateBounds),
                     (visibility_propagate_system, reset_view_visibility)
                         .in_set(VisibilityPropagate),
                     check_visibility.in_set(CheckVisibility),
@@ -402,6 +420,36 @@ pub fn calculate_bounds(
     }
 }
 
+// Update the `Aabb` component of all skinned mesh entities with a `DynamicSkinnedMeshBounds`
+// component.
+fn update_skinned_mesh_bounds(
+    inverse_bindposes_assets: Res<Assets<SkinnedMeshInverseBindposes>>,
+    mesh_assets: Res<Assets<Mesh>>,
+    mut mesh_entities: Query<
+        (&mut Aabb, &Mesh3d, &SkinnedMesh, Option<&GlobalTransform>),
+        With<DynamicSkinnedMeshBounds>,
+    >,
+    joint_entities: Query<&GlobalTransform>,
+) {
+    mesh_entities
+        .par_iter_mut()
+        .for_each(|(mut aabb, mesh, skinned_mesh, world_from_entity)| {
+            if let Some(inverse_bindposes_asset) =
+                inverse_bindposes_assets.get(&skinned_mesh.inverse_bindposes)
+                && let Some(mesh_asset) = mesh_assets.get(mesh)
+                && let Ok(skinned_aabb) = entity_aabb_from_skinned_mesh_bounds(
+                    &joint_entities,
+                    mesh_asset,
+                    skinned_mesh,
+                    inverse_bindposes_asset,
+                    world_from_entity,
+                )
+            {
+                *aabb = skinned_aabb.into();
+            }
+        });
+}
+
 /// Updates [`Frustum`].
 ///
 /// This system is used in [`CameraProjectionPlugin`](crate::CameraProjectionPlugin).

crates/bevy_gizmos/Cargo.toml

@@ -22,6 +22,7 @@ bevy_reflect = { path = "../bevy_reflect", version = "0.18.0-dev" }
 bevy_transform = { path = "../bevy_transform", version = "0.18.0-dev" }
 bevy_gizmos_macros = { path = "macros", version = "0.18.0-dev" }
 bevy_time = { path = "../bevy_time", version = "0.18.0-dev" }
+bevy_mesh = { path = "../bevy_mesh", version = "0.18.0-dev", optional = true }
 
 [lints]
 workspace = true

crates/bevy_gizmos/src/lib.rs

@@ -38,13 +38,22 @@ pub mod rounded_box;
 #[cfg(feature = "bevy_light")]
 pub mod light;
 
+#[cfg(feature = "bevy_mesh")]
+pub mod skinned_mesh_bounds;
+
 /// The gizmos prelude.
 ///
 /// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::aabb::{AabbGizmoConfigGroup, ShowAabbGizmo};
 
+    #[doc(hidden)]
+    #[cfg(feature = "bevy_mesh")]
+    pub use crate::skinned_mesh_bounds::{
+        ShowSkinnedMeshBoundsGizmo, SkinnedMeshBoundsGizmoConfigGroup,
+    };
+
     #[doc(hidden)]
     pub use crate::{
         config::{
@@ -78,9 +87,13 @@ use bevy_utils::TypeIdMap;
 use config::{DefaultGizmoConfigGroup, GizmoConfig, GizmoConfigGroup, GizmoConfigStore};
 use core::{any::TypeId, marker::PhantomData, mem};
 use gizmos::{GizmoStorage, Swap};
+
 #[cfg(feature = "bevy_light")]
 use light::LightGizmoPlugin;
 
+#[cfg(feature = "bevy_mesh")]
+use crate::skinned_mesh_bounds::SkinnedMeshBoundsGizmoPlugin;
+
 /// A [`Plugin`] that provides an immediate mode drawing api for visual debugging.
 #[derive(Default)]
 pub struct GizmoPlugin;
@@ -96,6 +109,9 @@ impl Plugin for GizmoPlugin {
 
         #[cfg(feature = "bevy_light")]
         app.add_plugins(LightGizmoPlugin);
+
+        #[cfg(feature = "bevy_mesh")]
+        app.add_plugins(SkinnedMeshBoundsGizmoPlugin);
     }
 }
 

crates/bevy_gizmos/src/skinned_mesh_bounds.rs

@@ -0,0 +1,164 @@
+//! A module adding debug visualization of [`DynamicSkinnedMeshBounds`].
+
+use bevy_app::{Plugin, PostUpdate};
+use bevy_asset::Assets;
+use bevy_camera::visibility::DynamicSkinnedMeshBounds;
+use bevy_color::Color;
+use bevy_ecs::{
+    component::Component,
+    query::{With, Without},
+    reflect::ReflectComponent,
+    schedule::IntoScheduleConfigs,
+    system::{Query, Res},
+};
+use bevy_math::Affine3A;
+use bevy_mesh::{
+    mark_3d_meshes_as_changed_if_their_assets_changed,
+    skinning::{SkinnedMesh, SkinnedMeshInverseBindposes},
+    Mesh, Mesh3d,
+};
+use bevy_reflect::{std_traits::ReflectDefault, Reflect};
+use bevy_transform::{components::GlobalTransform, TransformSystems};
+
+use crate::{
+    config::{GizmoConfigGroup, GizmoConfigStore},
+    gizmos::Gizmos,
+    AppGizmoBuilder,
+};
+
+/// A [`Plugin`] that provides visualization of entities with [`DynamicSkinnedMeshBounds`].
+pub struct SkinnedMeshBoundsGizmoPlugin;
+
+impl Plugin for SkinnedMeshBoundsGizmoPlugin {
+    fn build(&self, app: &mut bevy_app::App) {
+        app.init_gizmo_group::<SkinnedMeshBoundsGizmoConfigGroup>()
+            .add_systems(
+                PostUpdate,
+                (
+                    draw_skinned_mesh_bounds,
+                    draw_all_skinned_mesh_bounds.run_if(|config: Res<GizmoConfigStore>| {
+                        config
+                            .config::<SkinnedMeshBoundsGizmoConfigGroup>()
+                            .1
+                            .draw_all
+                    }),
+                )
+                    .after(TransformSystems::Propagate)
+                    .ambiguous_with(mark_3d_meshes_as_changed_if_their_assets_changed),
+            );
+    }
+}
+/// The [`GizmoConfigGroup`] used for debug visualizations of entities with [`DynamicSkinnedMeshBounds`]
+#[derive(Clone, Reflect, GizmoConfigGroup)]
+#[reflect(Clone, Default)]
+pub struct SkinnedMeshBoundsGizmoConfigGroup {
+    /// When set to `true`, draws all the bounds that contribute to skinned mesh
+    /// bounds.
+    ///
+    /// To draw a specific entity's skinned mesh bounds, you can add the [`ShowSkinnedMeshBoundsGizmo`] component.
+    ///
+    /// Defaults to `false`.
+    pub draw_all: bool,
+    /// The default color for skinned mesh bounds gizmos.
+    pub default_color: Color,
+}
+
+impl Default for SkinnedMeshBoundsGizmoConfigGroup {
+    fn default() -> Self {
+        Self {
+            draw_all: false,
+            default_color: Color::WHITE,
+        }
+    }
+}
+
+/// Add this [`Component`] to an entity to draw its [`DynamicSkinnedMeshBounds`] component.
+#[derive(Component, Reflect, Default, Debug)]
+#[reflect(Component, Default, Debug)]
+pub struct ShowSkinnedMeshBoundsGizmo {
+    /// The color of the bounds.
+    ///
+    /// The default color from the [`SkinnedMeshBoundsGizmoConfigGroup`] config is used if `None`,
+    pub color: Option<Color>,
+}
+
+fn draw(
+    color: Color,
+    mesh: &Mesh3d,
+    mesh_assets: &Res<Assets<Mesh>>,
+    skinned_mesh: &SkinnedMesh,
+    joint_entities: &Query<&GlobalTransform>,
+    inverse_bindposes_assets: &Res<Assets<SkinnedMeshInverseBindposes>>,
+    gizmos: &mut Gizmos<SkinnedMeshBoundsGizmoConfigGroup>,
+) {
+    if let Some(mesh_asset) = mesh_assets.get(mesh)
+        && let Some(bounds) = mesh_asset.skinned_mesh_bounds()
+        && let Some(inverse_bindposes_asset) =
+            inverse_bindposes_assets.get(&skinned_mesh.inverse_bindposes)
+    {
+        for (&joint_index, &joint_aabb) in bounds.iter() {
+            let joint_index = joint_index.0 as usize;
+
+            if let Some(&joint_entity) = skinned_mesh.joints.get(joint_index)
+                && let Ok(&world_from_joint) = joint_entities.get(joint_entity)
+                && let Some(&joint_from_mesh) = inverse_bindposes_asset.get(joint_index)
+            {
+                let world_from_mesh =
+                    world_from_joint.affine() * Affine3A::from_mat4(joint_from_mesh);
+
+                gizmos.aabb_3d(joint_aabb, world_from_mesh, color);
+            }
+        }
+    }
+}
+
+fn draw_skinned_mesh_bounds(
+    mesh_entities: Query<
+        (&Mesh3d, &SkinnedMesh, &ShowSkinnedMeshBoundsGizmo),
+        With<DynamicSkinnedMeshBounds>,
+    >,
+    joint_entities: Query<&GlobalTransform>,
+    mesh_assets: Res<Assets<Mesh>>,
+    inverse_bindposes_assets: Res<Assets<SkinnedMeshInverseBindposes>>,
+    mut gizmos: Gizmos<SkinnedMeshBoundsGizmoConfigGroup>,
+) {
+    for (mesh, skinned_mesh, gizmo) in mesh_entities {
+        let color = gizmo.color.unwrap_or(gizmos.config_ext.default_color);
+
+        draw(
+            color,
+            mesh,
+            &mesh_assets,
+            skinned_mesh,
+            &joint_entities,
+            &inverse_bindposes_assets,
+            &mut gizmos,
+        );
+    }
+}
+
+fn draw_all_skinned_mesh_bounds(
+    mesh_entities: Query<
+        (&Mesh3d, &SkinnedMesh),
+        (
+            With<DynamicSkinnedMeshBounds>,
+            Without<ShowSkinnedMeshBoundsGizmo>,
+        ),
+    >,
+    joint_entities: Query<&GlobalTransform>,
+    mesh_assets: Res<Assets<Mesh>>,
+    inverse_bindposes_assets: Res<Assets<SkinnedMeshInverseBindposes>>,
+    mut gizmos: Gizmos<SkinnedMeshBoundsGizmoConfigGroup>,
+) {
+    for (mesh, skinned_mesh) in mesh_entities {
+        draw(
+            gizmos.config_ext.default_color,
+            mesh,
+            &mesh_assets,
+            skinned_mesh,
+            &joint_entities,
+            &inverse_bindposes_assets,
+            &mut gizmos,
+        );
+    }
+}

crates/bevy_gltf/src/lib.rs

@@ -136,6 +136,7 @@ mod vertex_attributes;
 extern crate alloc;
 
 use alloc::sync::Arc;
+use serde::{Deserialize, Serialize};
 use std::sync::Mutex;
 use tracing::warn;
 
@@ -189,6 +190,23 @@ impl DefaultGltfImageSampler {
     }
 }
 
+/// Controls the bounds related components that are assigned to skinned mesh
+/// entities. These components are used by systems like frustum culling.
+#[derive(Copy, Clone, PartialEq, Serialize, Deserialize)]
+pub enum GltfSkinnedMeshBoundsPolicy {
+    /// Skinned meshes are assigned an `Aabb` component calculated from the bind
+    /// pose `Mesh`.
+    BindPose,
+    /// Skinned meshes are created with [`SkinnedMeshBounds`](bevy_mesh::skinning::SkinnedMeshBounds)
+    /// and assigned a [`DynamicSkinnedMeshBounds`](bevy_camera::visibility::DynamicSkinnedMeshBounds)
+    /// component. See `DynamicSkinnedMeshBounds` for details.
+    Dynamic,
+    /// Same as `BindPose`, but also assign a `NoFrustumCulling` component. That
+    /// component tells the `bevy_camera` plugin to avoid frustum culling the
+    /// skinned mesh.
+    NoFrustumCulling,
+}
+
 /// Adds support for glTF file loading to the app.
 pub struct GltfPlugin {
     /// The default image sampler to lay glTF sampler data on top of.
@@ -214,6 +232,10 @@ pub struct GltfPlugin {
     ///
     /// To specify, use [`GltfPlugin::add_custom_vertex_attribute`].
     pub custom_vertex_attributes: HashMap<Box<str>, MeshVertexAttribute>,
+
+    /// The default policy for skinned mesh bounds. Can be overridden by
+    /// [`GltfLoaderSettings::skinned_mesh_bounds_policy`].
+    pub skinned_mesh_bounds_policy: GltfSkinnedMeshBoundsPolicy,
 }
 
 impl Default for GltfPlugin {
@@ -222,6 +244,7 @@ impl Default for GltfPlugin {
             default_sampler: ImageSamplerDescriptor::linear(),
             custom_vertex_attributes: HashMap::default(),
             use_model_forward_direction: false,
+            skinned_mesh_bounds_policy: GltfSkinnedMeshBoundsPolicy::Dynamic,
         }
     }
 }
@@ -272,6 +295,7 @@ impl Plugin for GltfPlugin {
             custom_vertex_attributes: self.custom_vertex_attributes.clone(),
             default_sampler,
             default_use_model_forward_direction: self.use_model_forward_direction,
+            default_skinned_mesh_bounds_policy: self.skinned_mesh_bounds_policy,
         });
     }
 }