Meshlet rendering (initial feature)

Cargo.toml

@@ -321,6 +321,9 @@ embedded_watcher = ["bevy_internal/embedded_watcher"]
 # Enable stepping-based debugging of Bevy systems
 bevy_debug_stepping = ["bevy_internal/bevy_debug_stepping"]
 
+# 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"]
 
@@ -949,6 +952,17 @@ description = "Demonstrates irradiance volumes"
 category = "3D Rendering"
 wasm = false
 
+[[example]]
+name = "meshlet"
+path = "examples/3d/meshlet.rs"
+doc-scrape-examples = true
+
+[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

@@ -20,6 +20,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

@@ -158,6 +158,9 @@ bevy_debug_stepping = [
   "bevy_app/bevy_debug_stepping",
 ]
 
+# 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,8 @@ pbr_transmission_textures = []
 shader_format_glsl = ["bevy_render/shader_format_glsl"]
 trace = ["bevy_render/trace"]
 ios_simulator = ["bevy_render/ios_simulator"]
+# Enables processing meshes into meshlet meshes
+meshlet_processor = ["dep:meshopt", "dep:thiserror"]
 
 [dependencies]
 # bevy
@@ -34,12 +36,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,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 [`MeshVertexBufferLayoutRef`] 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

@@ -2,8 +2,18 @@
 #![allow(missing_docs)]
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
 
+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.
+pub mod experimental {
+    pub mod meshlet {
+        pub use crate::meshlet::*;
+    }
+}
+
 mod bundle;
 pub mod deferred;
 mod extended_material;
@@ -65,7 +75,9 @@ pub mod graph {
     }
 }
 
-use crate::{deferred::DeferredPbrLightingPlugin, graph::NodePbr};
+use crate::{
+    deferred::DeferredPbrLightingPlugin, graph::NodePbr, meshlet::MeshletDummyShaderPlugin,
+};
 use bevy_app::prelude::*;
 use bevy_asset::{load_internal_asset, AssetApp, Assets, Handle};
 use bevy_core_pipeline::core_3d::graph::{Core3d, Node3d};
@@ -256,6 +268,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,10 @@
-use crate::*;
+use crate::{
+    meshlet::{
+        prepare_material_meshlet_meshes_main_opaque_pass, queue_material_meshlet_meshes,
+        MeshletGpuScene,
+    },
+    *,
+};
 use bevy_asset::{Asset, AssetEvent, AssetId, AssetServer};
 use bevy_core_pipeline::{
     core_3d::{
@@ -170,6 +176,33 @@ 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)]
+    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)]
+    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)]
+    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)]
@@ -237,6 +270,13 @@ where
                         queue_material_meshes::<M>
                             .in_set(RenderSet::QueueMeshes)
                             .after(prepare_materials::<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.
+/// * 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;
+
+    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;
+}