Meshlet rendering (initial feature) (#10164)

# Objective
- Implements a more efficient, GPU-driven
(#1342) rendering pipeline
based on meshlets.
- Meshes are split into small clusters of triangles called meshlets,
each of which acts as a mini index buffer into the larger mesh data.
Meshlets can be compressed, streamed, culled, and batched much more
efficiently than monolithic meshes.


![image](https://github.com/bevyengine/bevy/assets/47158642/cb2aaad0-7a9a-4e14-93b0-15d4e895b26a)

![image](https://github.com/bevyengine/bevy/assets/47158642/7534035b-1eb7-4278-9b99-5322e4401715)

# Misc
* Future work: #11518
* Nanite reference:
https://advances.realtimerendering.com/s2021/Karis_Nanite_SIGGRAPH_Advances_2021_final.pdf
Two pass occlusion culling explained very well:
https://medium.com/@mil_kru/two-pass-occlusion-culling-4100edcad501

---------

Co-authored-by: Ricky Taylor <[email protected]>
Co-authored-by: vero <[email protected]>
Co-authored-by: François <[email protected]>
Co-authored-by: atlas dostal <[email protected]>

Cargo.toml

@@ -321,6 +321,12 @@ embedded_watcher = ["bevy_internal/embedded_watcher"]
 # Enable stepping-based debugging of Bevy systems
 bevy_debug_stepping = ["bevy_internal/bevy_debug_stepping"]
 
+# Enables the meshlet renderer for dense high-poly scenes (experimental)
+meshlet = ["bevy_internal/meshlet"]
+
+# Enables processing meshes into meshlet meshes for bevy_pbr
+meshlet_processor = ["bevy_internal/meshlet_processor"]
+
 # Enable support for the ios_simulator by downgrading some rendering capabilities
 ios_simulator = ["bevy_internal/ios_simulator"]
 
@@ -950,6 +956,18 @@ description = "Demonstrates irradiance volumes"
 category = "3D Rendering"
 wasm = false
 
+[[example]]
+name = "meshlet"
+path = "examples/3d/meshlet.rs"
+doc-scrape-examples = true
+required-features = ["meshlet"]
+
+[package.metadata.example.meshlet]
+name = "Meshlet"
+description = "Meshlet rendering for dense high-poly scenes (experimental)"
+category = "3D Rendering"
+wasm = false
+
 [[example]]
 name = "lightmaps"
 path = "examples/3d/lightmaps.rs"

crates/bevy_core_pipeline/src/lib.rs

@@ -24,6 +24,8 @@ pub mod upscaling;
 pub use skybox::Skybox;
 
 /// Experimental features that are not yet finished. Please report any issues you encounter!
+///
+/// Expect bugs, missing features, compatibility issues, low performance, and/or future breaking changes.
 pub mod experimental {
     pub mod taa {
         pub use crate::taa::{

crates/bevy_internal/Cargo.toml

@@ -159,6 +159,12 @@ bevy_debug_stepping = [
   "bevy_app/bevy_debug_stepping",
 ]
 
+# Enables the meshlet renderer for dense high-poly scenes (experimental)
+meshlet = ["bevy_pbr?/meshlet"]
+
+# Enables processing meshes into meshlet meshes for bevy_pbr
+meshlet_processor = ["bevy_pbr?/meshlet_processor"]
+
 # Provides a collection of developer tools
 bevy_dev_tools = ["dep:bevy_dev_tools"]
 

crates/bevy_pbr/Cargo.toml

@@ -15,6 +15,10 @@ pbr_transmission_textures = []
 shader_format_glsl = ["bevy_render/shader_format_glsl"]
 trace = ["bevy_render/trace"]
 ios_simulator = ["bevy_render/ios_simulator"]
+# Enables the meshlet renderer for dense high-poly scenes (experimental)
+meshlet = []
+# Enables processing meshes into meshlet meshes
+meshlet_processor = ["dep:meshopt", "dep:thiserror"]
 
 [dependencies]
 # bevy
@@ -34,12 +38,17 @@ bevy_window = { path = "../bevy_window", version = "0.14.0-dev" }
 bevy_derive = { path = "../bevy_derive", version = "0.14.0-dev" }
 
 # other
+meshopt = { version = "0.2", optional = true }
+thiserror = { version = "1", optional = true }
 bitflags = "2.3"
 fixedbitset = "0.5"
 # direct dependency required for derive macro
 bytemuck = { version = "1", features = ["derive"] }
 radsort = "0.1"
 smallvec = "1.6"
+serde = { version = "1", features = ["derive", "rc"] }
+bincode = "1"
+range-alloc = "0.1"
 nonmax = "0.5"
 
 [lints]

crates/bevy_pbr/src/deferred/pbr_deferred_functions.wgsl

@@ -7,10 +7,16 @@
     rgb9e5,
     mesh_view_bindings::view,
     utils::{octahedral_encode, octahedral_decode},
-    prepass_io::{VertexOutput, FragmentOutput},
+    prepass_io::FragmentOutput,
     view_transformations::{position_ndc_to_world, frag_coord_to_ndc},
 }
 
+#ifdef MESHLET_MESH_MATERIAL_PASS
+#import bevy_pbr::meshlet_visibility_buffer_resolve::VertexOutput
+#else
+#import bevy_pbr::prepass_io::VertexOutput
+#endif
+
 #ifdef MOTION_VECTOR_PREPASS
     #import bevy_pbr::pbr_prepass_functions::calculate_motion_vector
 #endif
@@ -116,7 +122,11 @@ fn deferred_output(in: VertexOutput, pbr_input: PbrInput) -> FragmentOutput {
 #endif
     // motion vectors if required
 #ifdef MOTION_VECTOR_PREPASS
+#ifdef MESHLET_MESH_MATERIAL_PASS
+    out.motion_vector = in.motion_vector;
+#else
     out.motion_vector = calculate_motion_vector(in.world_position, in.previous_world_position);
+#endif
 #endif
 
     return out;

crates/bevy_pbr/src/extended_material.rs

@@ -67,6 +67,30 @@ pub trait MaterialExtension: Asset + AsBindGroup + Clone + Sized {
         ShaderRef::Default
     }
 
+    /// Returns this material's [`crate::meshlet::MeshletMesh`] fragment shader. If [`ShaderRef::Default`] is returned,
+    /// the default meshlet mesh fragment shader will be used.
+    #[allow(unused_variables)]
+    #[cfg(feature = "meshlet")]
+    fn meshlet_mesh_fragment_shader() -> ShaderRef {
+        ShaderRef::Default
+    }
+
+    /// Returns this material's [`crate::meshlet::MeshletMesh`] prepass fragment shader. If [`ShaderRef::Default`] is returned,
+    /// the default meshlet mesh prepass fragment shader will be used.
+    #[allow(unused_variables)]
+    #[cfg(feature = "meshlet")]
+    fn meshlet_mesh_prepass_fragment_shader() -> ShaderRef {
+        ShaderRef::Default
+    }
+
+    /// Returns this material's [`crate::meshlet::MeshletMesh`] deferred fragment shader. If [`ShaderRef::Default`] is returned,
+    /// the default meshlet mesh deferred fragment shader will be used.
+    #[allow(unused_variables)]
+    #[cfg(feature = "meshlet")]
+    fn meshlet_mesh_deferred_fragment_shader() -> ShaderRef {
+        ShaderRef::Default
+    }
+
     /// Customizes the default [`RenderPipelineDescriptor`] for a specific entity using the entity's
     /// [`MaterialPipelineKey`] and [`MeshVertexBufferLayoutRef`] as input.
     /// Specialization for the base material is applied before this function is called.
@@ -211,6 +235,30 @@ impl<B: Material, E: MaterialExtension> Material for ExtendedMaterial<B, E> {
         }
     }
 
+    #[cfg(feature = "meshlet")]
+    fn meshlet_mesh_fragment_shader() -> ShaderRef {
+        match E::meshlet_mesh_fragment_shader() {
+            ShaderRef::Default => B::meshlet_mesh_fragment_shader(),
+            specified => specified,
+        }
+    }
+
+    #[cfg(feature = "meshlet")]
+    fn meshlet_mesh_prepass_fragment_shader() -> ShaderRef {
+        match E::meshlet_mesh_prepass_fragment_shader() {
+            ShaderRef::Default => B::meshlet_mesh_prepass_fragment_shader(),
+            specified => specified,
+        }
+    }
+
+    #[cfg(feature = "meshlet")]
+    fn meshlet_mesh_deferred_fragment_shader() -> ShaderRef {
+        match E::meshlet_mesh_deferred_fragment_shader() {
+            ShaderRef::Default => B::meshlet_mesh_deferred_fragment_shader(),
+            specified => specified,
+        }
+    }
+
     fn specialize(
         pipeline: &MaterialPipeline<Self>,
         descriptor: &mut RenderPipelineDescriptor,

crates/bevy_pbr/src/lib.rs

@@ -6,8 +6,20 @@
     html_favicon_url = "https://bevyengine.org/assets/icon.png"
 )]
 
+#[cfg(feature = "meshlet")]
+mod meshlet;
 pub mod wireframe;
 
+/// Experimental features that are not yet finished. Please report any issues you encounter!
+///
+/// Expect bugs, missing features, compatibility issues, low performance, and/or future breaking changes.
+#[cfg(feature = "meshlet")]
+pub mod experimental {
+    pub mod meshlet {
+        pub use crate::meshlet::*;
+    }
+}
+
 mod bundle;
 pub mod deferred;
 mod extended_material;
@@ -111,6 +123,8 @@ pub const PBR_PREPASS_FUNCTIONS_SHADER_HANDLE: Handle<Shader> =
 pub const PBR_DEFERRED_TYPES_HANDLE: Handle<Shader> = Handle::weak_from_u128(3221241127431430599);
 pub const PBR_DEFERRED_FUNCTIONS_HANDLE: Handle<Shader> = Handle::weak_from_u128(72019026415438599);
 pub const RGB9E5_FUNCTIONS_HANDLE: Handle<Shader> = Handle::weak_from_u128(2659010996143919192);
+const MESHLET_VISIBILITY_BUFFER_RESOLVE_SHADER_HANDLE: Handle<Shader> =
+    Handle::weak_from_u128(2325134235233421);
 
 /// Sets up the entire PBR infrastructure of bevy.
 pub struct PbrPlugin {
@@ -236,6 +250,13 @@ impl Plugin for PbrPlugin {
             "render/view_transformations.wgsl",
             Shader::from_wgsl
         );
+        // Setup dummy shaders for when MeshletPlugin is not used to prevent shader import errors.
+        load_internal_asset!(
+            app,
+            MESHLET_VISIBILITY_BUFFER_RESOLVE_SHADER_HANDLE,
+            "meshlet/dummy_visibility_buffer_resolve.wgsl",
+            Shader::from_wgsl
+        );
 
         app.register_asset_reflect::<StandardMaterial>()
             .register_type::<AmbientLight>()

crates/bevy_pbr/src/material.rs

@@ -1,3 +1,8 @@
+#[cfg(feature = "meshlet")]
+use crate::meshlet::{
+    prepare_material_meshlet_meshes_main_opaque_pass, queue_material_meshlet_meshes,
+    MeshletGpuScene,
+};
 use crate::*;
 use bevy_asset::{Asset, AssetEvent, AssetId, AssetServer};
 use bevy_core_pipeline::{
@@ -170,6 +175,36 @@ pub trait Material: Asset + AsBindGroup + Clone + Sized {
         ShaderRef::Default
     }
 
+    /// Returns this material's [`crate::meshlet::MeshletMesh`] fragment shader. If [`ShaderRef::Default`] is returned,
+    /// the default meshlet mesh fragment shader will be used.
+    ///
+    /// This is part of an experimental feature, and is unnecessary to implement unless you are using `MeshletMesh`'s.
+    #[allow(unused_variables)]
+    #[cfg(feature = "meshlet")]
+    fn meshlet_mesh_fragment_shader() -> ShaderRef {
+        ShaderRef::Default
+    }
+
+    /// Returns this material's [`crate::meshlet::MeshletMesh`] prepass fragment shader. If [`ShaderRef::Default`] is returned,
+    /// the default meshlet mesh prepass fragment shader will be used.
+    ///
+    /// This is part of an experimental feature, and is unnecessary to implement unless you are using `MeshletMesh`'s.
+    #[allow(unused_variables)]
+    #[cfg(feature = "meshlet")]
+    fn meshlet_mesh_prepass_fragment_shader() -> ShaderRef {
+        ShaderRef::Default
+    }
+
+    /// Returns this material's [`crate::meshlet::MeshletMesh`] deferred fragment shader. If [`ShaderRef::Default`] is returned,
+    /// the default meshlet mesh deferred fragment shader will be used.
+    ///
+    /// This is part of an experimental feature, and is unnecessary to implement unless you are using `MeshletMesh`'s.
+    #[allow(unused_variables)]
+    #[cfg(feature = "meshlet")]
+    fn meshlet_mesh_deferred_fragment_shader() -> ShaderRef {
+        ShaderRef::Default
+    }
+
     /// Customizes the default [`RenderPipelineDescriptor`] for a specific entity using the entity's
     /// [`MaterialPipelineKey`] and [`MeshVertexBufferLayoutRef`] as input.
     #[allow(unused_variables)]
@@ -248,6 +283,18 @@ where
                         .after(prepare_materials::<M>),),
                 );
             }
+
+            #[cfg(feature = "meshlet")]
+            render_app.add_systems(
+                Render,
+                (
+                    prepare_material_meshlet_meshes_main_opaque_pass::<M>,
+                    queue_material_meshlet_meshes::<M>,
+                )
+                    .chain()
+                    .in_set(RenderSet::Queue)
+                    .run_if(resource_exists::<MeshletGpuScene>),
+            );
         }
 
         if self.shadows_enabled || self.prepass_enabled {

crates/bevy_pbr/src/meshlet/asset.rs

@@ -0,0 +1,102 @@
+use bevy_asset::{
+    io::{Reader, Writer},
+    saver::{AssetSaver, SavedAsset},
+    Asset, AssetLoader, AsyncReadExt, AsyncWriteExt, LoadContext,
+};
+use bevy_math::Vec3;
+use bevy_reflect::TypePath;
+use bytemuck::{Pod, Zeroable};
+use serde::{Deserialize, Serialize};
+use std::sync::Arc;
+
+/// A mesh that has been pre-processed into multiple small clusters of triangles called meshlets.
+///
+/// A [`bevy_render::mesh::Mesh`] can be converted to a [`MeshletMesh`] using `MeshletMesh::from_mesh` when the `meshlet_processor` cargo feature is enabled.
+/// The conversion step is very slow, and is meant to be ran once ahead of time, and not during runtime. This type of mesh is not suitable for
+/// dynamically generated geometry.
+///
+/// There are restrictions on the [`crate::Material`] functionality that can be used with this type of mesh.
+/// * Materials have no control over the vertex shader or vertex attributes.
+/// * Materials must be opaque. Transparent, alpha masked, and transmissive materials are not supported.
+/// * Materials must use the [`crate::Material::meshlet_mesh_fragment_shader`] method (and similar variants for prepass/deferred shaders)
+///   which requires certain shader patterns that differ from the regular material shaders.
+/// * Limited control over [`bevy_render::render_resource::RenderPipelineDescriptor`] attributes.
+///
+/// See also [`super::MaterialMeshletMeshBundle`] and [`super::MeshletPlugin`].
+#[derive(Asset, TypePath, Serialize, Deserialize, Clone)]
+pub struct MeshletMesh {
+    /// The total amount of triangles summed across all meshlets in the mesh.
+    pub total_meshlet_triangles: u64,
+    /// Raw vertex data bytes for the overall mesh.
+    pub vertex_data: Arc<[u8]>,
+    /// Indices into `vertex_data`.
+    pub vertex_ids: Arc<[u32]>,
+    /// Indices into `vertex_ids`.
+    pub indices: Arc<[u8]>,
+    /// The list of meshlets making up this mesh.
+    pub meshlets: Arc<[Meshlet]>,
+    /// A list of spherical bounding volumes, 1 per meshlet.
+    pub meshlet_bounding_spheres: Arc<[MeshletBoundingSphere]>,
+}
+
+/// A single meshlet within a [`MeshletMesh`].
+#[derive(Serialize, Deserialize, Copy, Clone, Pod, Zeroable)]
+#[repr(C)]
+pub struct Meshlet {
+    /// The offset within the parent mesh's [`MeshletMesh::vertex_ids`] buffer where the indices for this meshlet begin.
+    pub start_vertex_id: u32,
+    /// The offset within the parent mesh's [`MeshletMesh::indices`] buffer where the indices for this meshlet begin.
+    pub start_index_id: u32,
+    /// The amount of triangles in this meshlet.
+    pub triangle_count: u32,
+}
+
+/// A spherical bounding volume used for culling a [`Meshlet`].
+#[derive(Serialize, Deserialize, Copy, Clone, Pod, Zeroable)]
+#[repr(C)]
+pub struct MeshletBoundingSphere {
+    pub center: Vec3,
+    pub radius: f32,
+}
+
+/// An [`AssetLoader`] and [`AssetSaver`] for `.meshlet_mesh` [`MeshletMesh`] assets.
+pub struct MeshletMeshSaverLoad;
+
+impl AssetLoader for MeshletMeshSaverLoad {
+    type Asset = MeshletMesh;
+    type Settings = ();
+    type Error = bincode::Error;
+
+    async fn load<'a>(
+        &'a self,
+        reader: &'a mut Reader<'_>,
+        _settings: &'a Self::Settings,
+        _load_context: &'a mut LoadContext<'_>,
+    ) -> Result<Self::Asset, Self::Error> {
+        let mut bytes = Vec::new();
+        reader.read_to_end(&mut bytes).await?;
+        bincode::deserialize(&bytes)
+    }
+
+    fn extensions(&self) -> &[&str] {
+        &["meshlet_mesh"]
+    }
+}
+
+impl AssetSaver for MeshletMeshSaverLoad {
+    type Asset = MeshletMesh;
+    type Settings = ();
+    type OutputLoader = Self;
+    type Error = bincode::Error;
+
+    async fn save<'a>(
+        &'a self,
+        writer: &'a mut Writer,
+        asset: SavedAsset<'a, Self::Asset>,
+        _settings: &'a Self::Settings,
+    ) -> Result<(), Self::Error> {
+        let bytes = bincode::serialize(asset.get())?;
+        writer.write_all(&bytes).await?;
+        Ok(())
+    }
+}

crates/bevy_pbr/src/meshlet/copy_material_depth.wgsl

@@ -0,0 +1,10 @@
+#import bevy_core_pipeline::fullscreen_vertex_shader::FullscreenVertexOutput
+
+@group(0) @binding(0) var material_depth: texture_2d<u32>;
+
+/// This pass copies the R16Uint material depth texture to an actual Depth16Unorm depth texture.
+
+@fragment
+fn copy_material_depth(in: FullscreenVertexOutput) -> @builtin(frag_depth) f32 {
+    return f32(textureLoad(material_depth, vec2<i32>(in.position.xy), 0).r) / 65535.0;
+}