Meshlet rendering (initial feature)

Cargo.toml

@@ -289,6 +289,9 @@ file_watcher = ["bevy_internal/file_watcher"]
 # Enables watching in memory asset providers for Bevy Asset hot-reloading
 embedded_watcher = ["bevy_internal/embedded_watcher"]
 
+# Enables processing meshes into meshlet meshes for bevy_pbr
+meshlet_processor = ["bevy_internal/meshlet_processor"]
+
 [dependencies]
 bevy_dylib = { path = "crates/bevy_dylib", version = "0.12.0", default-features = false, optional = true }
 bevy_internal = { path = "crates/bevy_internal", version = "0.12.0", default-features = false }
@@ -902,6 +905,17 @@ description = "Showcases wireframe rendering"
 category = "3D Rendering"
 wasm = false
 
+[[example]]
+name = "meshlet"
+path = "examples/3d/meshlet.rs"
+doc-scrape-examples = true
+
+[package.metadata.example.meshlet]
+name = "Meshlet"
+description = "GPU-driven meshlet-based rendering"
+category = "3D Rendering"
+wasm = false
+
 [[example]]
 name = "lightmaps"
 path = "examples/3d/lightmaps.rs"

crates/bevy_internal/Cargo.toml

@@ -148,6 +148,9 @@ file_watcher = ["bevy_asset?/file_watcher"]
 # Enables watching embedded files for Bevy Asset hot-reloading
 embedded_watcher = ["bevy_asset?/embedded_watcher"]
 
+# Enables processing meshes into meshlet meshes for bevy_pbr
+meshlet_processor = ["bevy_pbr?/meshlet_processor"]
+
 [dependencies]
 # bevy
 bevy_a11y = { path = "../bevy_a11y", version = "0.12.0" }

crates/bevy_pbr/Cargo.toml

@@ -12,6 +12,8 @@ keywords = ["bevy"]
 webgl = []
 shader_format_glsl = ["naga_oil/glsl"]
 pbr_transmission_textures = []
+# Enables processing meshes into meshlet meshes
+meshlet_processor = ["dep:meshopt"]
 
 [dependencies]
 # bevy
@@ -30,13 +32,17 @@ bevy_window = { path = "../bevy_window", version = "0.12.0" }
 bevy_derive = { path = "../bevy_derive", version = "0.12.0" }
 
 # other
+meshopt = { version = "0.2", optional = true }
 bitflags = "2.3"
 fixedbitset = "0.4"
 # direct dependency required for derive macro
 bytemuck = { version = "1", features = ["derive"] }
 radsort = "0.1"
 smallvec = "1.6"
 thread_local = "1.0"
+serde = { version = "1", features = ["derive", "rc"] }
+bincode = "1"
+range-alloc = "0.1"
 
 [target.'cfg(target_arch = "wasm32")'.dependencies]
 naga_oil = { version = "0.11" }

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
@@ -117,7 +123,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,27 @@ 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)]
+    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)]
+    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)]
+    fn meshlet_mesh_deferred_fragment_shader() -> ShaderRef {
+        ShaderRef::Default
+    }
+
     /// Customizes the default [`RenderPipelineDescriptor`] for a specific entity using the entity's
     /// [`MaterialPipelineKey`] and [`MeshVertexBufferLayout`] as input.
     /// Specialization for the base material is applied before this function is called.
@@ -211,6 +232,27 @@ impl<B: Material, E: MaterialExtension> Material for ExtendedMaterial<B, E> {
         }
     }
 
+    fn meshlet_mesh_fragment_shader() -> ShaderRef {
+        match E::meshlet_mesh_fragment_shader() {
+            ShaderRef::Default => B::meshlet_mesh_fragment_shader(),
+            specified => specified,
+        }
+    }
+
+    fn meshlet_mesh_prepass_fragment_shader() -> ShaderRef {
+        match E::meshlet_mesh_prepass_fragment_shader() {
+            ShaderRef::Default => B::meshlet_mesh_prepass_fragment_shader(),
+            specified => specified,
+        }
+    }
+
+    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

@@ -1,3 +1,4 @@
+pub mod meshlet;
 pub mod wireframe;
 
 mod alpha;
@@ -75,7 +76,7 @@ use bevy_render::{
 };
 use bevy_transform::TransformSystem;
 
-use crate::deferred::DeferredPbrLightingPlugin;
+use crate::{deferred::DeferredPbrLightingPlugin, meshlet::MeshletDummyShaderPlugin};
 
 pub const PBR_TYPES_SHADER_HANDLE: Handle<Shader> = Handle::weak_from_u128(1708015359337029744);
 pub const PBR_BINDINGS_SHADER_HANDLE: Handle<Shader> = Handle::weak_from_u128(5635987986427308186);
@@ -252,6 +253,7 @@ impl Plugin for PbrPlugin {
             .init_resource::<DefaultOpaqueRendererMethod>()
             .add_plugins((
                 MeshRenderPlugin,
+                MeshletDummyShaderPlugin,
                 MaterialPlugin::<StandardMaterial> {
                     prepass_enabled: self.prepass_enabled,
                     ..Default::default()

crates/bevy_pbr/src/material.rs

@@ -1,4 +1,11 @@
-use crate::{environment_map::RenderViewEnvironmentMaps, *};
+use crate::{
+    environment_map::RenderViewEnvironmentMaps,
+    meshlet::{
+        prepare_material_meshlet_meshes_main_opaque_pass, queue_material_meshlet_meshes,
+        MeshletGpuScene,
+    },
+    *,
+};
 use bevy_app::{App, Plugin};
 use bevy_asset::{Asset, AssetApp, AssetEvent, AssetId, AssetServer, Assets, Handle};
 use bevy_core_pipeline::{
@@ -168,6 +175,27 @@ 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.
+    #[allow(unused_variables)]
+    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)]
+    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)]
+    fn meshlet_mesh_deferred_fragment_shader() -> ShaderRef {
+        ShaderRef::Default
+    }
+
     /// Customizes the default [`RenderPipelineDescriptor`] for a specific entity using the entity's
     /// [`MaterialPipelineKey`] and [`MeshVertexBufferLayout`] as input.
     #[allow(unused_variables)]
@@ -237,6 +265,13 @@ where
                             .after(prepare_materials::<M>)
                             // queue_material_meshes only writes to `material_bind_group_id`, which `queue_shadows` doesn't read
                             .ambiguous_with(render::queue_shadows::<M>),
+                        (
+                            prepare_material_meshlet_meshes_main_opaque_pass::<M>,
+                            queue_material_meshlet_meshes::<M>,
+                        )
+                            .chain()
+                            .in_set(RenderSet::Queue)
+                            .run_if(resource_exists::<MeshletGpuScene>),
                     ),
                 );
         }

crates/bevy_pbr/src/meshlet/asset.rs

@@ -0,0 +1,107 @@
+use bevy_asset::{
+    io::{Reader, Writer},
+    saver::{AssetSaver, SavedAsset},
+    Asset, AssetLoader, AsyncReadExt, AsyncWriteExt, LoadContext,
+};
+use bevy_math::Vec3;
+use bevy_reflect::TypePath;
+use bevy_utils::BoxedFuture;
+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, and can only have a custom fragment shader.
+/// * 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 similiar 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`].
+#[derive(Asset, TypePath, Serialize, Deserialize, Clone)]
+pub struct MeshletMesh {
+    /// The total amount of indices in the overall mesh (sum of meshlet triangle_counts * 3).
+    pub total_meshlet_indices: 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;
+
+    fn load<'a>(
+        &'a self,
+        reader: &'a mut Reader,
+        _settings: &'a Self::Settings,
+        _load_context: &'a mut LoadContext,
+    ) -> BoxedFuture<'a, Result<Self::Asset, Self::Error>> {
+        Box::pin(async move {
+            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;
+
+    fn save<'a>(
+        &'a self,
+        writer: &'a mut Writer,
+        asset: SavedAsset<'a, Self::Asset>,
+        _settings: &'a Self::Settings,
+    ) -> BoxedFuture<'a, Result<<Self::OutputLoader as AssetLoader>::Settings, Self::Error>> {
+        Box::pin(async move {
+            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;
+}