From 804fca6eefbecfd636f3d7dd6abca397d9990345 Mon Sep 17 00:00:00 2001
From: IceSentry <c.giguere42@gmail.com>
Date: Fri, 15 Nov 2024 23:14:25 -0500
Subject: [PATCH 01/17] wip

---
 Cargo.toml                             |  12 ++
 examples/shader/custom_render_phase.rs | 176 +++++++++++++++++++++++++
 2 files changed, 188 insertions(+)
 create mode 100644 examples/shader/custom_render_phase.rs

diff --git a/Cargo.toml b/Cargo.toml
index 56aac74f53cb9..a1d38c2b15b7f 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -2608,6 +2608,18 @@ description = "A shader that renders a mesh multiple times in one draw call usin
 category = "Shaders"
 wasm = true
 
+[[example]]
+name = "custom_render_phase"
+path = "examples/shader/custom_render_phase.rs"
+doc-scrape-examples = true
+
+[package.metadata.example.custom_render_phase]
+name = "Custom Render Phase"
+description = "Shows how to make a complete render phase"
+category = "Shaders"
+wasm = true
+
+
 [[example]]
 name = "automatic_instancing"
 path = "examples/shader/automatic_instancing.rs"
diff --git a/examples/shader/custom_render_phase.rs b/examples/shader/custom_render_phase.rs
new file mode 100644
index 0000000000000..b2e362cc07bb3
--- /dev/null
+++ b/examples/shader/custom_render_phase.rs
@@ -0,0 +1,176 @@
+use bevy::{
+    core_pipeline::oit::OrderIndependentTransparencySettings, prelude::*, scene::SceneInstance,
+    window::WindowResized,
+};
+use bevy_render::camera::Viewport;
+use rand::Rng;
+
+fn main() {
+    App::new()
+        .add_plugins(DefaultPlugins.set(WindowPlugin {
+            primary_window: Some(Window {
+                resolution: Vec2::new(1920.0, 1080.0).into(),
+                ..default()
+            }),
+            ..default()
+        }))
+        .add_systems(Startup, setup)
+        .add_systems(
+            Update,
+            (exit, set_camera_viewports, rotate, replace_scene_materials),
+        )
+        .run();
+}
+
+fn setup(
+    mut commands: Commands,
+    asset_server: Res<AssetServer>,
+    mut meshes: ResMut<Assets<Mesh>>,
+    mut materials: ResMut<Assets<StandardMaterial>>,
+) {
+    // circular base
+    //commands.spawn((
+    //    Mesh3d(meshes.add(Circle::new(4.0))),
+    //    MeshMaterial3d(materials.add(Color::WHITE)),
+    //    Transform::from_rotation(Quat::from_rotation_x(-std::f32::consts::FRAC_PI_2)),
+    //));
+    // light
+    commands.spawn((
+        PointLight {
+            shadows_enabled: true,
+            ..default()
+        },
+        Transform::from_xyz(4.0, 8.0, 4.0),
+    ));
+
+    commands.spawn((
+        SceneRoot(
+            asset_server
+                .load(GltfAssetLabel::Scene(0).from_asset("models/reconstructed_engine.glb")),
+        ),
+        //Transform::from_scale(Vec3::splat(0.035)),
+        Transform::from_scale(Vec3::splat(0.85)),
+        Rotate,
+        ReplaceStandardMaterial,
+    ));
+
+    let camera_pos =
+        Transform::from_xyz(0.0, 5.0, 10.0).looking_at(Vec3::new(0.0, 0.5, 0.0), Vec3::Y);
+    let text = ["OIT enabled", "OIT disabled"];
+    for index in 0..2 {
+        let mut camera = commands.spawn((
+            Camera3d::default(),
+            camera_pos.clone(),
+            Camera {
+                order: index as isize,
+                ..default()
+            },
+            CameraPosition {
+                pos: UVec2::new((index % 2) as u32, (index / 2) as u32),
+            },
+            Msaa::Off,
+        ));
+        if index == 0 {
+            camera.insert(OrderIndependentTransparencySettings {
+                layer_count: 32,
+                //alpha_threshold: 0.05,
+                ..default()
+            });
+        }
+        let camera_id = camera.id();
+        // Set up UI
+        commands
+            .spawn((
+                TargetCamera(camera_id),
+                Node {
+                    width: Val::Percent(100.),
+                    height: Val::Percent(100.),
+                    ..default()
+                },
+            ))
+            .with_children(|parent| {
+                parent.spawn((
+                    Text::new(text[index]),
+                    TextFont {
+                        font_size: 24.0,
+                        ..default()
+                    },
+                    Node {
+                        position_type: PositionType::Absolute,
+                        top: Val::Px(12.),
+                        left: Val::Px(12.),
+                        ..default()
+                    },
+                ));
+            });
+    }
+}
+
+fn exit(input: Res<ButtonInput<KeyCode>>) {
+    if input.just_pressed(KeyCode::KeyQ) {
+        std::process::exit(0);
+    }
+}
+
+#[derive(Component)]
+struct CameraPosition {
+    pos: UVec2,
+}
+
+fn set_camera_viewports(
+    windows: Query<&Window>,
+    mut resize_events: EventReader<WindowResized>,
+    mut query: Query<(&CameraPosition, &mut Camera)>,
+) {
+    // We need to dynamically resize the camera's viewports whenever the window size changes
+    // so then each camera always takes up half the screen.
+    // A resize_event is sent when the window is first created, allowing us to reuse this system for initial setup.
+    for resize_event in resize_events.read() {
+        let window = windows.get(resize_event.window).unwrap();
+        let size = UVec2::new(window.physical_size().x / 2, window.physical_size().y);
+
+        for (camera_position, mut camera) in &mut query {
+            camera.viewport = Some(Viewport {
+                physical_position: camera_position.pos * size,
+                physical_size: size,
+                ..default()
+            });
+        }
+    }
+}
+#[derive(Component)]
+struct Rotate;
+
+fn rotate(mut q: Query<&mut Transform, With<Rotate>>, time: Res<Time>) {
+    for mut transform in &mut q {
+        transform.rotate_axis(Dir3::Y, std::f32::consts::PI * time.delta_secs() * 0.25);
+    }
+}
+
+#[derive(Component)]
+struct ReplaceStandardMaterial;
+fn replace_scene_materials(
+    mut commands: Commands,
+    unloaded_instances: Query<(Entity, &SceneInstance), With<ReplaceStandardMaterial>>,
+    handles: Query<(Entity, &MeshMaterial3d<StandardMaterial>)>,
+    mut pbr_materials: ResMut<Assets<StandardMaterial>>,
+    scene_manager: Res<SceneSpawner>,
+) {
+    for (entity, instance) in unloaded_instances.iter() {
+        println!("replace");
+        if scene_manager.instance_is_ready(**instance) {
+            commands.entity(entity).remove::<ReplaceStandardMaterial>();
+        }
+        let handles = handles.iter_many(scene_manager.iter_instance_entities(**instance));
+        let mut rng = rand::thread_rng();
+        for (_entity, material_handle) in handles {
+            let Some(material) = pbr_materials.get_mut(material_handle) else {
+                continue;
+            };
+            // TODO random colors
+            //material.base_color.set_alpha(0.25);
+            material.base_color = Color::srgba(rng.gen(), rng.gen(), rng.gen(), 0.25);
+            material.alpha_mode = AlphaMode::Blend;
+        }
+    }
+}

From e3581545669f1964609d641f0c8d9965438ba514 Mon Sep 17 00:00:00 2001
From: IceSentry <c.giguere42@gmail.com>
Date: Tue, 3 Dec 2024 20:30:24 -0500
Subject: [PATCH 02/17] wip

---
 examples/shader/custom_render_phase.rs | 368 +++++++++++++++----------
 1 file changed, 226 insertions(+), 142 deletions(-)

diff --git a/examples/shader/custom_render_phase.rs b/examples/shader/custom_render_phase.rs
index b2e362cc07bb3..0b0c96b06686d 100644
--- a/examples/shader/custom_render_phase.rs
+++ b/examples/shader/custom_render_phase.rs
@@ -1,176 +1,260 @@
+use std::ops::Range;
+
 use bevy::{
-    core_pipeline::oit::OrderIndependentTransparencySettings, prelude::*, scene::SceneInstance,
-    window::WindowResized,
+    asset::UntypedAssetId,
+    core_pipeline::{
+        core_2d::Opaque2dBinKey,
+        tonemapping::{DebandDither, Tonemapping},
+    },
+    ecs::entity::{EntityHash, EntityHashSet},
+    pbr::tonemapping_pipeline_key,
+    prelude::*,
+    sprite::{Material2dKey, Mesh2dPipelineKey, RenderMesh2dInstances},
+};
+use bevy_render::{
+    mesh::RenderMesh,
+    render_asset::RenderAssets,
+    render_phase::{
+        BinnedPhaseItem, BinnedRenderPhaseType, CachedRenderPipelinePhaseItem, DrawFunctionId,
+        DrawFunctions, PhaseItem, PhaseItemExtraIndex, ViewBinnedRenderPhases,
+    },
+    render_resource::{BindGroupId, CachedRenderPipelineId, PipelineCache},
+    sync_world::MainEntity,
+    view::{ExtractedView, VisibleEntities},
+    Extract, Render, RenderApp,
 };
-use bevy_render::camera::Viewport;
-use rand::Rng;
 
 fn main() {
     App::new()
-        .add_plugins(DefaultPlugins.set(WindowPlugin {
-            primary_window: Some(Window {
-                resolution: Vec2::new(1920.0, 1080.0).into(),
-                ..default()
-            }),
-            ..default()
-        }))
+        .add_plugins((DefaultPlugins, CustomPhasPlugin))
         .add_systems(Startup, setup)
-        .add_systems(
-            Update,
-            (exit, set_camera_viewports, rotate, replace_scene_materials),
-        )
         .run();
 }
 
-fn setup(
-    mut commands: Commands,
-    asset_server: Res<AssetServer>,
-    mut meshes: ResMut<Assets<Mesh>>,
-    mut materials: ResMut<Assets<StandardMaterial>>,
-) {
-    // circular base
-    //commands.spawn((
-    //    Mesh3d(meshes.add(Circle::new(4.0))),
-    //    MeshMaterial3d(materials.add(Color::WHITE)),
-    //    Transform::from_rotation(Quat::from_rotation_x(-std::f32::consts::FRAC_PI_2)),
-    //));
-    // light
-    commands.spawn((
-        PointLight {
-            shadows_enabled: true,
-            ..default()
-        },
-        Transform::from_xyz(4.0, 8.0, 4.0),
-    ));
-
+fn setup(mut commands: Commands) {
+    // camera
     commands.spawn((
-        SceneRoot(
-            asset_server
-                .load(GltfAssetLabel::Scene(0).from_asset("models/reconstructed_engine.glb")),
-        ),
-        //Transform::from_scale(Vec3::splat(0.035)),
-        Transform::from_scale(Vec3::splat(0.85)),
-        Rotate,
-        ReplaceStandardMaterial,
+        Camera3d::default(),
+        Transform::from_xyz(-2.0, 2.5, 5.0).looking_at(Vec3::ZERO, Vec3::Y),
     ));
+}
 
-    let camera_pos =
-        Transform::from_xyz(0.0, 5.0, 10.0).looking_at(Vec3::new(0.0, 0.5, 0.0), Vec3::Y);
-    let text = ["OIT enabled", "OIT disabled"];
-    for index in 0..2 {
-        let mut camera = commands.spawn((
-            Camera3d::default(),
-            camera_pos.clone(),
-            Camera {
-                order: index as isize,
-                ..default()
-            },
-            CameraPosition {
-                pos: UVec2::new((index % 2) as u32, (index / 2) as u32),
-            },
-            Msaa::Off,
-        ));
-        if index == 0 {
-            camera.insert(OrderIndependentTransparencySettings {
-                layer_count: 32,
-                //alpha_threshold: 0.05,
-                ..default()
-            });
-        }
-        let camera_id = camera.id();
-        // Set up UI
-        commands
-            .spawn((
-                TargetCamera(camera_id),
-                Node {
-                    width: Val::Percent(100.),
-                    height: Val::Percent(100.),
-                    ..default()
-                },
-            ))
-            .with_children(|parent| {
-                parent.spawn((
-                    Text::new(text[index]),
-                    TextFont {
-                        font_size: 24.0,
-                        ..default()
-                    },
-                    Node {
-                        position_type: PositionType::Absolute,
-                        top: Val::Px(12.),
-                        left: Val::Px(12.),
-                        ..default()
-                    },
-                ));
-            });
+struct CustomPhasPlugin;
+impl Plugin for CustomPhasPlugin {
+    fn build(&self, app: &mut App) {
+        // We need to get the render app from the main app
+        let Some(render_app) = app.get_sub_app_mut(RenderApp) else {
+            return;
+        };
+        render_app
+            .init_resource::<DrawFunctions<CustomPhase>>()
+            .init_resource::<ViewBinnedRenderPhases<CustomPhase>>()
+            .add_systems(Render, extract_camera_phases);
+        //.add_systems(
+        //    Render,
+        //    (batch_and_prepare_binned_render_phase::<CustomPhase>,),
+        //);
+    }
+    fn finish(&self, app: &mut App) {
+        // We need to get the render app from the main app
+        let Some(render_app) = app.get_sub_app_mut(RenderApp) else {
+            return;
+        };
     }
 }
 
-fn exit(input: Res<ButtonInput<KeyCode>>) {
-    if input.just_pressed(KeyCode::KeyQ) {
-        std::process::exit(0);
-    }
+// TODO Phase
+// TODO Phase Item
+// TODO ViewNode
+
+pub struct CustomPhase {
+    /// The key, which determines which can be batched.
+    pub key: CustomPhaseBinKey,
+    /// An entity from which data will be fetched, including the mesh if
+    /// applicable.
+    pub representative_entity: (Entity, MainEntity),
+    /// The ranges of instances.
+    pub batch_range: Range<u32>,
+    /// An extra index, which is either a dynamic offset or an index in the
+    /// indirect parameters list.
+    pub extra_index: PhaseItemExtraIndex,
 }
 
-#[derive(Component)]
-struct CameraPosition {
-    pos: UVec2,
+/// Data that must be identical in order to batch phase items together.
+#[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct CustomPhaseBinKey {
+    /// The identifier of the render pipeline.
+    pub pipeline: CachedRenderPipelineId,
+    /// The function used to draw.
+    pub draw_function: DrawFunctionId,
+    /// The asset that this phase item is associated with.
+    ///
+    /// Normally, this is the ID of the mesh, but for non-mesh items it might be
+    /// the ID of another type of asset.
+    pub asset_id: UntypedAssetId,
+    /// The ID of a bind group specific to the material.
+    pub material_bind_group_id: Option<BindGroupId>,
 }
 
-fn set_camera_viewports(
-    windows: Query<&Window>,
-    mut resize_events: EventReader<WindowResized>,
-    mut query: Query<(&CameraPosition, &mut Camera)>,
-) {
-    // We need to dynamically resize the camera's viewports whenever the window size changes
-    // so then each camera always takes up half the screen.
-    // A resize_event is sent when the window is first created, allowing us to reuse this system for initial setup.
-    for resize_event in resize_events.read() {
-        let window = windows.get(resize_event.window).unwrap();
-        let size = UVec2::new(window.physical_size().x / 2, window.physical_size().y);
-
-        for (camera_position, mut camera) in &mut query {
-            camera.viewport = Some(Viewport {
-                physical_position: camera_position.pos * size,
-                physical_size: size,
-                ..default()
-            });
+impl PhaseItem for CustomPhase {
+    #[inline]
+    fn entity(&self) -> Entity {
+        self.representative_entity.0
+    }
+
+    fn main_entity(&self) -> MainEntity {
+        self.representative_entity.1
+    }
+
+    #[inline]
+    fn draw_function(&self) -> DrawFunctionId {
+        self.key.draw_function
+    }
+
+    #[inline]
+    fn batch_range(&self) -> &Range<u32> {
+        &self.batch_range
+    }
+
+    #[inline]
+    fn batch_range_mut(&mut self) -> &mut Range<u32> {
+        &mut self.batch_range
+    }
+
+    fn extra_index(&self) -> PhaseItemExtraIndex {
+        self.extra_index
+    }
+
+    fn batch_range_and_extra_index_mut(&mut self) -> (&mut Range<u32>, &mut PhaseItemExtraIndex) {
+        (&mut self.batch_range, &mut self.extra_index)
+    }
+}
+
+impl BinnedPhaseItem for CustomPhase {
+    type BinKey = CustomPhaseBinKey;
+
+    fn new(
+        key: Self::BinKey,
+        representative_entity: (Entity, MainEntity),
+        batch_range: Range<u32>,
+        extra_index: PhaseItemExtraIndex,
+    ) -> Self {
+        CustomPhase {
+            key,
+            representative_entity,
+            batch_range,
+            extra_index,
         }
     }
 }
-#[derive(Component)]
-struct Rotate;
 
-fn rotate(mut q: Query<&mut Transform, With<Rotate>>, time: Res<Time>) {
-    for mut transform in &mut q {
-        transform.rotate_axis(Dir3::Y, std::f32::consts::PI * time.delta_secs() * 0.25);
+impl CachedRenderPipelinePhaseItem for CustomPhase {
+    #[inline]
+    fn cached_pipeline(&self) -> CachedRenderPipelineId {
+        self.key.pipeline
     }
 }
 
-#[derive(Component)]
-struct ReplaceStandardMaterial;
-fn replace_scene_materials(
+fn extract_camera_phases(
     mut commands: Commands,
-    unloaded_instances: Query<(Entity, &SceneInstance), With<ReplaceStandardMaterial>>,
-    handles: Query<(Entity, &MeshMaterial3d<StandardMaterial>)>,
-    mut pbr_materials: ResMut<Assets<StandardMaterial>>,
-    scene_manager: Res<SceneSpawner>,
+    mut custom_phases: ResMut<ViewBinnedRenderPhases<CustomPhase>>,
+    cameras: Extract<Query<(Entity, &Camera), With<Camera3d>>>,
+    mut live_entities: Local<EntityHashSet>,
 ) {
-    for (entity, instance) in unloaded_instances.iter() {
-        println!("replace");
-        if scene_manager.instance_is_ready(**instance) {
-            commands.entity(entity).remove::<ReplaceStandardMaterial>();
+    live_entities.clear();
+    for (entity, camera) in &cameras {
+        if !camera.is_active {
+            continue;
         }
-        let handles = handles.iter_many(scene_manager.iter_instance_entities(**instance));
-        let mut rng = rand::thread_rng();
-        for (_entity, material_handle) in handles {
-            let Some(material) = pbr_materials.get_mut(material_handle) else {
+        commands.get_or_spawn(entity);
+        custom_phases.insert_or_clear(entity);
+        live_entities.insert(entity);
+    }
+    // Clear out all dead views.
+    custom_phases.retain(|camera_entity, _| live_entities.contains(camera_entity));
+}
+
+#[allow(clippy::too_many_arguments)]
+pub fn queue_material2d_meshes(
+    opaque_draw_functions: Res<DrawFunctions<CustomPhase>>,
+    pipeline_cache: Res<PipelineCache>,
+    render_meshes: Res<RenderAssets<RenderMesh>>,
+    mut render_mesh_instances: ResMut<RenderMesh2dInstances>,
+    mut opaque_render_phases: ResMut<ViewBinnedRenderPhases<CustomPhase>>,
+    mut views: Query<(
+        Entity,
+        &ExtractedView,
+        &VisibleEntities,
+        &Msaa,
+        Option<&Tonemapping>,
+        Option<&DebandDither>,
+    )>,
+) {
+    if render_material_instances.is_empty() {
+        return;
+    }
+    for (view_entity, view, visible_entities, msaa, tonemapping, dither) in &mut views {
+        let Some(opaque_phase) = opaque_render_phases.get_mut(&view_entity) else {
+            continue;
+        };
+        let draw_opaque_2d = opaque_draw_functions.read().id::<DrawMaterial2d<M>>();
+        let mut view_key = Mesh2dPipelineKey::from_msaa_samples(msaa.samples())
+            | Mesh2dPipelineKey::from_hdr(view.hdr);
+        if !view.hdr {
+            if let Some(tonemapping) = tonemapping {
+                view_key |= Mesh2dPipelineKey::TONEMAP_IN_SHADER;
+                view_key |= tonemapping_pipeline_key(*tonemapping);
+            }
+            if let Some(DebandDither::Enabled) = dither {
+                view_key |= Mesh2dPipelineKey::DEBAND_DITHER;
+            }
+        }
+        for visible_entity in visible_entities.iter::<WithMesh2d>() {
+            let Some(material_asset_id) = render_material_instances.get(visible_entity) else {
+                continue;
+            };
+            let Some(mesh_instance) = render_mesh_instances.get_mut(visible_entity) else {
                 continue;
             };
-            // TODO random colors
-            //material.base_color.set_alpha(0.25);
-            material.base_color = Color::srgba(rng.gen(), rng.gen(), rng.gen(), 0.25);
-            material.alpha_mode = AlphaMode::Blend;
+            let Some(material_2d) = render_materials.get(*material_asset_id) else {
+                continue;
+            };
+            let Some(mesh) = render_meshes.get(mesh_instance.mesh_asset_id) else {
+                continue;
+            };
+            let mesh_key = view_key
+                | Mesh2dPipelineKey::from_primitive_topology(mesh.primitive_topology())
+                | material_2d.properties.mesh_pipeline_key_bits;
+            let pipeline_id = pipelines.specialize(
+                &pipeline_cache,
+                &material2d_pipeline,
+                Material2dKey {
+                    mesh_key,
+                    bind_group_data: material_2d.key.clone(),
+                },
+                &mesh.layout,
+            );
+            let pipeline_id = match pipeline_id {
+                Ok(id) => id,
+                Err(err) => {
+                    error!("{}", err);
+                    continue;
+                }
+            };
+            mesh_instance.material_bind_group_id = material_2d.get_bind_group_id();
+            let mesh_z = mesh_instance.transforms.world_from_local.translation.z;
+
+            let bin_key = Opaque2dBinKey {
+                pipeline: pipeline_id,
+                draw_function: draw_opaque_2d,
+                asset_id: mesh_instance.mesh_asset_id.into(),
+                material_bind_group_id: material_2d.get_bind_group_id().0,
+            };
+            opaque_phase.add(
+                bin_key,
+                *visible_entity,
+                BinnedRenderPhaseType::mesh(mesh_instance.automatic_batching),
+            );
         }
     }
 }

From 949bbc1db8c906d9f4dce097211f54e562c9851a Mon Sep 17 00:00:00 2001
From: IceSentry <c.giguere42@gmail.com>
Date: Tue, 17 Dec 2024 12:42:27 -0500
Subject: [PATCH 03/17] wip

---
 examples/shader/custom_render_phase.rs | 375 ++++++++++++++++---------
 1 file changed, 244 insertions(+), 131 deletions(-)

diff --git a/examples/shader/custom_render_phase.rs b/examples/shader/custom_render_phase.rs
index 0b0c96b06686d..7719ad3ab209d 100644
--- a/examples/shader/custom_render_phase.rs
+++ b/examples/shader/custom_render_phase.rs
@@ -1,27 +1,43 @@
+//! This example demonstrates how to write a custom phase
+//!
+//! Render phases in bevy are used whenever you need to draw a groud of neshes in a specific way.
+//! For example, bevy's main pass has an opaque phase, a transparent phase for both 2d and 3d.
+//! Sometimes, you may want to only draw a subset of meshes before or after the builtin phase. In
+//! those situations you need to write your own phase.
+
 use std::ops::Range;
 
 use bevy::{
-    asset::UntypedAssetId,
-    core_pipeline::{
-        core_2d::Opaque2dBinKey,
-        tonemapping::{DebandDither, Tonemapping},
+    ecs::{
+        entity::EntityHashSet,
+        query::ROQueryItem,
+        system::{
+            lifetimeless::{Read, SRes},
+            SystemParamItem,
+        },
     },
-    ecs::entity::{EntityHash, EntityHashSet},
-    pbr::tonemapping_pipeline_key,
+    math::FloatOrd,
+    pbr::{DrawMesh, RenderMeshInstances, SetMeshBindGroup, SetMeshViewBindGroup},
     prelude::*,
-    sprite::{Material2dKey, Mesh2dPipelineKey, RenderMesh2dInstances},
 };
 use bevy_render::{
-    mesh::RenderMesh,
-    render_asset::RenderAssets,
+    extract_component::{ExtractComponent, ExtractComponentPlugin, UniformComponentPlugin},
+    mesh::{MeshVertexBufferLayoutRef, RenderMesh},
+    render_asset::{PrepareAssetError, RenderAsset, RenderAssetPlugin, RenderAssets},
     render_phase::{
-        BinnedPhaseItem, BinnedRenderPhaseType, CachedRenderPipelinePhaseItem, DrawFunctionId,
-        DrawFunctions, PhaseItem, PhaseItemExtraIndex, ViewBinnedRenderPhases,
+        sort_phase_system, AddRenderCommand, CachedRenderPipelinePhaseItem, DrawFunctionId,
+        DrawFunctions, PhaseItem, PhaseItemExtraIndex, RenderCommand, RenderCommandResult,
+        SetItemPipeline, SortedPhaseItem, TrackedRenderPass, ViewSortedRenderPhases,
+    },
+    render_resource::{
+        AsBindGroup, AsBindGroupError, BindGroup, BindGroupLayout, BindingResources,
+        CachedRenderPipelineId, PipelineCache, RenderPipelineDescriptor, SpecializedMeshPipeline,
+        SpecializedMeshPipelineError, SpecializedMeshPipelines,
     },
-    render_resource::{BindGroupId, CachedRenderPipelineId, PipelineCache},
-    sync_world::MainEntity,
-    view::{ExtractedView, VisibleEntities},
-    Extract, Render, RenderApp,
+    renderer::RenderDevice,
+    sync_world::{MainEntity, RenderEntity},
+    view::{check_visibility, ExtractedView, RenderVisibleEntities, VisibilitySystems},
+    Extract, Render, RenderApp, RenderSet,
 };
 
 fn main() {
@@ -31,84 +47,211 @@ fn main() {
         .run();
 }
 
-fn setup(mut commands: Commands) {
+fn setup(
+    mut commands: Commands,
+    mut meshes: ResMut<Assets<Mesh>>,
+    mut materials: ResMut<Assets<StandardMaterial>>,
+    mut custom_draw: ResMut<Assets<CustomDrawData>>,
+) {
+    // circular base
+    commands.spawn((
+        Mesh3d(meshes.add(Circle::new(4.0))),
+        MeshMaterial3d(materials.add(Color::WHITE)),
+        Transform::from_rotation(Quat::from_rotation_x(-std::f32::consts::FRAC_PI_2)),
+    ));
+    // cube
+    commands.spawn((
+        Mesh3d(meshes.add(Cuboid::new(1.0, 1.0, 1.0))),
+        MeshMaterial3d(materials.add(Color::srgb_u8(124, 144, 255))),
+        Transform::from_xyz(0.0, 0.5, 0.0),
+        CustomDrawDataHandle(custom_draw.add(CustomDrawData {
+            // Set it to red
+            color: Vec4::new(1.0, 0.0, 0.0, 1.0),
+        })),
+    ));
+    // light
+    commands.spawn((
+        PointLight {
+            shadows_enabled: true,
+            ..default()
+        },
+        Transform::from_xyz(4.0, 8.0, 4.0),
+    ));
     // camera
     commands.spawn((
         Camera3d::default(),
-        Transform::from_xyz(-2.0, 2.5, 5.0).looking_at(Vec3::ZERO, Vec3::Y),
+        Transform::from_xyz(-2.0, 4.5, 9.0).looking_at(Vec3::ZERO, Vec3::Y),
     ));
 }
 
+#[derive(Component, ExtractComponent, Clone, Copy)]
+struct CustomDrawMarker;
+
+/// A query filter that tells [`view::check_visibility`] about our custom
+/// rendered entity.
+type WithCustomDraw = With<CustomDrawMarker>;
+
 struct CustomPhasPlugin;
 impl Plugin for CustomPhasPlugin {
     fn build(&self, app: &mut App) {
+        app.init_asset::<CustomDrawData>().add_plugins((
+            RenderAssetPlugin::<PreparedCustomDrawData>::default(),
+            ExtractComponentPlugin::<CustomDrawMarker>::default(),
+        ));
+        // Make sure to tell Bevy to check our entity for visibility. Bevy won't
+        // do this by default, for efficiency reasons.
+        app.add_systems(
+            PostUpdate,
+            check_visibility::<WithCustomDraw>.in_set(VisibilitySystems::CheckVisibility),
+        );
         // We need to get the render app from the main app
         let Some(render_app) = app.get_sub_app_mut(RenderApp) else {
             return;
         };
         render_app
+            .init_resource::<SpecializedMeshPipelines<CustomDrawPipeline>>()
             .init_resource::<DrawFunctions<CustomPhase>>()
-            .init_resource::<ViewBinnedRenderPhases<CustomPhase>>()
-            .add_systems(Render, extract_camera_phases);
-        //.add_systems(
-        //    Render,
-        //    (batch_and_prepare_binned_render_phase::<CustomPhase>,),
-        //);
+            .add_render_command::<CustomPhase, DrawCustom>()
+            .init_resource::<ViewSortedRenderPhases<CustomPhase>>()
+            .add_systems(ExtractSchedule, extract_camera_phases)
+            .add_systems(
+                Render,
+                (
+                    sort_phase_system::<CustomPhase>.in_set(RenderSet::PhaseSort),
+                    queue_custom_meshes.in_set(RenderSet::QueueMeshes),
+                ),
+            );
     }
+
     fn finish(&self, app: &mut App) {
         // We need to get the render app from the main app
         let Some(render_app) = app.get_sub_app_mut(RenderApp) else {
             return;
         };
+
+        render_app.init_resource::<CustomDrawPipeline>();
     }
 }
 
-// TODO Phase
-// TODO Phase Item
-// TODO ViewNode
+#[derive(AsBindGroup, Asset, Clone, TypePath)]
+struct CustomDrawData {
+    #[uniform(0)]
+    color: Vec4,
+}
 
-pub struct CustomPhase {
-    /// The key, which determines which can be batched.
-    pub key: CustomPhaseBinKey,
-    /// An entity from which data will be fetched, including the mesh if
-    /// applicable.
-    pub representative_entity: (Entity, MainEntity),
-    /// The ranges of instances.
-    pub batch_range: Range<u32>,
-    /// An extra index, which is either a dynamic offset or an index in the
-    /// indirect parameters list.
-    pub extra_index: PhaseItemExtraIndex,
+#[derive(Resource)]
+struct CustomDrawPipeline {
+    layout: BindGroupLayout,
+}
+impl FromWorld for CustomDrawPipeline {
+    fn from_world(world: &mut World) -> Self {
+        Self {
+            layout: CustomDrawData::bind_group_layout(world.resource::<RenderDevice>()),
+        }
+    }
 }
+impl SpecializedMeshPipeline for CustomDrawPipeline {
+    type Key = u32;
+
+    fn specialize(
+        &self,
+        key: Self::Key,
+        layout: &MeshVertexBufferLayoutRef,
+    ) -> Result<RenderPipelineDescriptor, SpecializedMeshPipelineError> {
+        todo!()
+    }
+}
+
+/// Data prepared for a custom draw
+struct PreparedCustomDrawData {
+    bindings: BindingResources,
+    bind_group: BindGroup,
+}
+impl RenderAsset for PreparedCustomDrawData {
+    type SourceAsset = CustomDrawData;
+
+    type Param = (
+        SRes<RenderDevice>,
+        SRes<CustomDrawPipeline>,
+        <CustomDrawData as AsBindGroup>::Param,
+    );
+
+    fn prepare_asset(
+        material: Self::SourceAsset,
+        _: AssetId<Self::SourceAsset>,
+        (render_device, pipeline, data_param): &mut SystemParamItem<Self::Param>,
+    ) -> Result<Self, PrepareAssetError<Self::SourceAsset>> {
+        match material.as_bind_group(&pipeline.layout, render_device, data_param) {
+            Ok(prepared) => Ok(PreparedCustomDrawData {
+                bindings: prepared.bindings,
+                bind_group: prepared.bind_group,
+            }),
+            Err(AsBindGroupError::RetryNextUpdate) => {
+                Err(PrepareAssetError::RetryNextUpdate(material))
+            }
+            Err(other) => Err(PrepareAssetError::AsBindGroupError(other)),
+        }
+    }
+}
+
+type DrawCustom = (
+    SetItemPipeline,
+    SetMeshViewBindGroup<0>,
+    SetMeshBindGroup<1>,
+    SetCustomBindGroup<2>,
+    DrawMesh,
+);
 
-/// Data that must be identical in order to batch phase items together.
-#[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
-pub struct CustomPhaseBinKey {
-    /// The identifier of the render pipeline.
+#[derive(Component)]
+struct CustomDrawDataHandle(Handle<CustomDrawData>);
+
+struct SetCustomBindGroup<const I: usize>;
+impl<P: PhaseItem, const I: usize> RenderCommand<P> for SetCustomBindGroup<I> {
+    type Param = SRes<RenderAssets<PreparedCustomDrawData>>;
+    type ViewQuery = ();
+    type ItemQuery = Read<CustomDrawDataHandle>;
+
+    #[inline]
+    fn render<'w>(
+        _item: &P,
+        _view: (),
+        handle: Option<ROQueryItem<'w, Self::ItemQuery>>,
+        assets: SystemParamItem<'w, '_, Self::Param>,
+        pass: &mut TrackedRenderPass<'w>,
+    ) -> RenderCommandResult {
+        let Some(material) = handle.and_then(|handle| assets.into_inner().get(&handle.0)) else {
+            return RenderCommandResult::Failure("invalid item query");
+        };
+        pass.set_bind_group(I, &material.bind_group, &[]);
+        RenderCommandResult::Success
+    }
+}
+
+// TODO ViewNode
+
+struct CustomPhase {
+    pub sort_key: FloatOrd,
+    pub entity: (Entity, MainEntity),
     pub pipeline: CachedRenderPipelineId,
-    /// The function used to draw.
     pub draw_function: DrawFunctionId,
-    /// The asset that this phase item is associated with.
-    ///
-    /// Normally, this is the ID of the mesh, but for non-mesh items it might be
-    /// the ID of another type of asset.
-    pub asset_id: UntypedAssetId,
-    /// The ID of a bind group specific to the material.
-    pub material_bind_group_id: Option<BindGroupId>,
+    pub batch_range: Range<u32>,
+    pub extra_index: PhaseItemExtraIndex,
 }
 
 impl PhaseItem for CustomPhase {
     #[inline]
     fn entity(&self) -> Entity {
-        self.representative_entity.0
+        self.entity.0
     }
 
+    #[inline]
     fn main_entity(&self) -> MainEntity {
-        self.representative_entity.1
+        self.entity.1
     }
 
     #[inline]
     fn draw_function(&self) -> DrawFunctionId {
-        self.key.draw_function
+        self.draw_function
     }
 
     #[inline]
@@ -121,44 +264,44 @@ impl PhaseItem for CustomPhase {
         &mut self.batch_range
     }
 
+    #[inline]
     fn extra_index(&self) -> PhaseItemExtraIndex {
-        self.extra_index
+        self.extra_index.clone()
     }
 
+    #[inline]
     fn batch_range_and_extra_index_mut(&mut self) -> (&mut Range<u32>, &mut PhaseItemExtraIndex) {
         (&mut self.batch_range, &mut self.extra_index)
     }
 }
 
-impl BinnedPhaseItem for CustomPhase {
-    type BinKey = CustomPhaseBinKey;
-
-    fn new(
-        key: Self::BinKey,
-        representative_entity: (Entity, MainEntity),
-        batch_range: Range<u32>,
-        extra_index: PhaseItemExtraIndex,
-    ) -> Self {
-        CustomPhase {
-            key,
-            representative_entity,
-            batch_range,
-            extra_index,
-        }
+impl SortedPhaseItem for CustomPhase {
+    type SortKey = FloatOrd;
+
+    #[inline]
+    fn sort_key(&self) -> Self::SortKey {
+        self.sort_key
+    }
+
+    #[inline]
+    fn sort(items: &mut [Self]) {
+        // bevy normally uses radsort instead of the std slice::sort_by_key
+        // radsort is a stable radix sort that performed better than `slice::sort_by_key` or `slice::sort_unstable_by_key`.
+        // Since it is not re-exported by bevy, we just use the std sort for the purpose of the example
+        items.sort_by_key(SortedPhaseItem::sort_key);
     }
 }
 
 impl CachedRenderPipelinePhaseItem for CustomPhase {
     #[inline]
     fn cached_pipeline(&self) -> CachedRenderPipelineId {
-        self.key.pipeline
+        self.pipeline
     }
 }
 
 fn extract_camera_phases(
-    mut commands: Commands,
-    mut custom_phases: ResMut<ViewBinnedRenderPhases<CustomPhase>>,
-    cameras: Extract<Query<(Entity, &Camera), With<Camera3d>>>,
+    mut custom_phases: ResMut<ViewSortedRenderPhases<CustomPhase>>,
+    cameras: Extract<Query<(RenderEntity, &Camera), With<Camera3d>>>,
     mut live_entities: Local<EntityHashSet>,
 ) {
     live_entities.clear();
@@ -166,72 +309,45 @@ fn extract_camera_phases(
         if !camera.is_active {
             continue;
         }
-        commands.get_or_spawn(entity);
         custom_phases.insert_or_clear(entity);
         live_entities.insert(entity);
+        //println!("phase extracted");
     }
     // Clear out all dead views.
     custom_phases.retain(|camera_entity, _| live_entities.contains(camera_entity));
 }
 
 #[allow(clippy::too_many_arguments)]
-pub fn queue_material2d_meshes(
-    opaque_draw_functions: Res<DrawFunctions<CustomPhase>>,
+fn queue_custom_meshes(
+    custom_draw_functions: Res<DrawFunctions<CustomPhase>>,
+    mut pipelines: ResMut<SpecializedMeshPipelines<CustomDrawPipeline>>,
     pipeline_cache: Res<PipelineCache>,
+    custom_draw_pipeline: Res<CustomDrawPipeline>,
     render_meshes: Res<RenderAssets<RenderMesh>>,
-    mut render_mesh_instances: ResMut<RenderMesh2dInstances>,
-    mut opaque_render_phases: ResMut<ViewBinnedRenderPhases<CustomPhase>>,
-    mut views: Query<(
-        Entity,
-        &ExtractedView,
-        &VisibleEntities,
-        &Msaa,
-        Option<&Tonemapping>,
-        Option<&DebandDither>,
-    )>,
+    render_mesh_instances: Res<RenderMeshInstances>,
+    mut custom_render_phases: ResMut<ViewSortedRenderPhases<CustomPhase>>,
+    mut views: Query<(Entity, &ExtractedView, &RenderVisibleEntities, &Msaa)>,
 ) {
-    if render_material_instances.is_empty() {
-        return;
-    }
-    for (view_entity, view, visible_entities, msaa, tonemapping, dither) in &mut views {
-        let Some(opaque_phase) = opaque_render_phases.get_mut(&view_entity) else {
+    for (view_entity, view, visible_entities, _msaa) in &mut views {
+        let Some(custom_phase) = custom_render_phases.get_mut(&view_entity) else {
             continue;
         };
-        let draw_opaque_2d = opaque_draw_functions.read().id::<DrawMaterial2d<M>>();
-        let mut view_key = Mesh2dPipelineKey::from_msaa_samples(msaa.samples())
-            | Mesh2dPipelineKey::from_hdr(view.hdr);
-        if !view.hdr {
-            if let Some(tonemapping) = tonemapping {
-                view_key |= Mesh2dPipelineKey::TONEMAP_IN_SHADER;
-                view_key |= tonemapping_pipeline_key(*tonemapping);
-            }
-            if let Some(DebandDither::Enabled) = dither {
-                view_key |= Mesh2dPipelineKey::DEBAND_DITHER;
-            }
-        }
-        for visible_entity in visible_entities.iter::<WithMesh2d>() {
-            let Some(material_asset_id) = render_material_instances.get(visible_entity) else {
-                continue;
-            };
-            let Some(mesh_instance) = render_mesh_instances.get_mut(visible_entity) else {
-                continue;
-            };
-            let Some(material_2d) = render_materials.get(*material_asset_id) else {
+        let draw_custom = custom_draw_functions.read().id::<DrawCustom>();
+
+        let rangefinder = view.rangefinder3d();
+        for (render_entity, visible_entity) in visible_entities.iter::<WithCustomDraw>() {
+            println!("queue entities");
+            let Some(mesh_instance) = render_mesh_instances.render_mesh_queue_data(*visible_entity)
+            else {
                 continue;
             };
             let Some(mesh) = render_meshes.get(mesh_instance.mesh_asset_id) else {
                 continue;
             };
-            let mesh_key = view_key
-                | Mesh2dPipelineKey::from_primitive_topology(mesh.primitive_topology())
-                | material_2d.properties.mesh_pipeline_key_bits;
             let pipeline_id = pipelines.specialize(
                 &pipeline_cache,
-                &material2d_pipeline,
-                Material2dKey {
-                    mesh_key,
-                    bind_group_data: material_2d.key.clone(),
-                },
+                &custom_draw_pipeline,
+                0, // TODO key
                 &mesh.layout,
             );
             let pipeline_id = match pipeline_id {
@@ -241,20 +357,17 @@ pub fn queue_material2d_meshes(
                     continue;
                 }
             };
-            mesh_instance.material_bind_group_id = material_2d.get_bind_group_id();
-            let mesh_z = mesh_instance.transforms.world_from_local.translation.z;
-
-            let bin_key = Opaque2dBinKey {
+            let distance = rangefinder.distance_translation(&mesh_instance.translation);
+            custom_phase.add(CustomPhase {
+                // Sort the data based on the distance to the view
+                sort_key: FloatOrd(distance),
+                entity: (*render_entity, *visible_entity),
                 pipeline: pipeline_id,
-                draw_function: draw_opaque_2d,
-                asset_id: mesh_instance.mesh_asset_id.into(),
-                material_bind_group_id: material_2d.get_bind_group_id().0,
-            };
-            opaque_phase.add(
-                bin_key,
-                *visible_entity,
-                BinnedRenderPhaseType::mesh(mesh_instance.automatic_batching),
-            );
+                draw_function: draw_custom,
+                // Sorted phase items aren't batched
+                batch_range: 0..1,
+                extra_index: PhaseItemExtraIndex::None,
+            });
         }
     }
 }

From 5ef39cd3c92905df88a6ca7987cc7009caebe07d Mon Sep 17 00:00:00 2001
From: IceSentry <c.giguere42@gmail.com>
Date: Fri, 20 Dec 2024 14:01:28 -0500
Subject: [PATCH 04/17] wip

---
 Cargo.toml                             |   1 +
 assets/shaders/custom_draw_phase.wgsl  |  41 ++++
 crates/bevy_pbr/src/lib.rs             |   2 +-
 examples/shader/custom_render_phase.rs | 322 +++++++++++++++++++++++--
 4 files changed, 345 insertions(+), 21 deletions(-)
 create mode 100644 assets/shaders/custom_draw_phase.wgsl

diff --git a/Cargo.toml b/Cargo.toml
index a1d38c2b15b7f..e564f55a068eb 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -491,6 +491,7 @@ http-body-util = "0.1"
 anyhow = "1"
 macro_rules_attribute = "0.2"
 accesskit = "0.17"
+nonmax = "0.5"
 
 [target.'cfg(not(target_family = "wasm"))'.dev-dependencies]
 smol = "2"
diff --git a/assets/shaders/custom_draw_phase.wgsl b/assets/shaders/custom_draw_phase.wgsl
new file mode 100644
index 0000000000000..8d3419b656b7a
--- /dev/null
+++ b/assets/shaders/custom_draw_phase.wgsl
@@ -0,0 +1,41 @@
+//! Very simple shader used to demonstrate how to get the world position and pass data
+//! between the vertex and fragment shader. Also shows the custom vertex layout.
+
+// First we import everything we need from bevy_pbr
+// A 2d shader would be vevry similar but import from bevy_sprite instead
+#import bevy_pbr::{
+    mesh_functions,
+    view_transformations::position_world_to_clip
+}
+
+struct Vertex {
+    // This is needed if you are using batching and/or gpu preprocessing
+    // It's a built in so you don't need to define it in the vertex layout
+    @builtin(instance_index) instance_index: u32,
+    // Like we defined for the vertex layout
+    // position is at location 0
+    @location(0) position: vec3<f32>,
+};
+
+// This is the output of the vertex shader and we also use it as the input for the fragment shader
+struct VertexOutput {
+    @builtin(position) clip_position: vec4<f32>,
+    @location(0) world_position: vec4<f32>,
+};
+
+@vertex
+fn vertex(vertex: Vertex) -> VertexOutput {
+    var out: VertexOutput;
+    // This is how bevy computes the world position
+    // The vertex.instance_index is very important. Esepecially if you are using batching and gpu preprocessing
+    var world_from_local = mesh_functions::get_world_from_local(vertex.instance_index);
+    out.world_position = mesh_functions::mesh_position_local_to_world(world_from_local, vec4(vertex.position, 1.0));
+    out.clip_position = position_world_to_clip(out.world_position.xyz);
+    return out;
+}
+
+@fragment
+fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
+    // Just output a red color
+    return vec4(1.0, 0.0, 0.0, 1.0);
+}
diff --git a/crates/bevy_pbr/src/lib.rs b/crates/bevy_pbr/src/lib.rs
index f219518dfcce2..3fbe4b2c9376e 100644
--- a/crates/bevy_pbr/src/lib.rs
+++ b/crates/bevy_pbr/src/lib.rs
@@ -33,7 +33,7 @@ mod light;
 mod light_probe;
 mod lightmap;
 mod material;
-mod material_bind_groups;
+pub mod material_bind_groups;
 mod mesh_material;
 mod parallax;
 mod pbr_material;
diff --git a/examples/shader/custom_render_phase.rs b/examples/shader/custom_render_phase.rs
index 7719ad3ab209d..6fa58d1b51cc8 100644
--- a/examples/shader/custom_render_phase.rs
+++ b/examples/shader/custom_render_phase.rs
@@ -8,22 +8,36 @@
 use std::ops::Range;
 
 use bevy::{
+    core_pipeline::core_3d::graph::{Core3d, Node3d},
     ecs::{
         entity::EntityHashSet,
-        query::ROQueryItem,
+        query::{QueryItem, ROQueryItem},
         system::{
             lifetimeless::{Read, SRes},
             SystemParamItem,
         },
     },
     math::FloatOrd,
-    pbr::{DrawMesh, RenderMeshInstances, SetMeshBindGroup, SetMeshViewBindGroup},
+    pbr::{
+        material_bind_groups::MaterialBindGroupSlot, DrawMesh, MeshInputUniform, MeshPipeline,
+        MeshPipelineKey, MeshPipelineViewLayoutKey, MeshUniform, RenderMeshInstances,
+        SetMeshBindGroup, SetMeshViewBindGroup,
+    },
     prelude::*,
 };
 use bevy_render::{
+    batching::{
+        gpu_preprocessing::{batch_and_prepare_sorted_render_phase, IndirectParametersBuffer},
+        GetBatchData, GetFullBatchData, NoAutomaticBatching,
+    },
+    camera::ExtractedCamera,
+    diagnostic::RecordDiagnostics,
     extract_component::{ExtractComponent, ExtractComponentPlugin, UniformComponentPlugin},
-    mesh::{MeshVertexBufferLayoutRef, RenderMesh},
+    mesh::{allocator::MeshAllocator, MeshVertexBufferLayoutRef, RenderMesh},
     render_asset::{PrepareAssetError, RenderAsset, RenderAssetPlugin, RenderAssets},
+    render_graph::{
+        NodeRunError, RenderGraphApp, RenderGraphContext, RenderLabel, ViewNode, ViewNodeRunner,
+    },
     render_phase::{
         sort_phase_system, AddRenderCommand, CachedRenderPipelinePhaseItem, DrawFunctionId,
         DrawFunctions, PhaseItem, PhaseItemExtraIndex, RenderCommand, RenderCommandResult,
@@ -31,14 +45,23 @@ use bevy_render::{
     },
     render_resource::{
         AsBindGroup, AsBindGroupError, BindGroup, BindGroupLayout, BindingResources,
-        CachedRenderPipelineId, PipelineCache, RenderPipelineDescriptor, SpecializedMeshPipeline,
-        SpecializedMeshPipelineError, SpecializedMeshPipelines,
+        CachedRenderPipelineId, ColorTargetState, ColorWrites, CommandEncoderDescriptor,
+        CompareFunction, DepthStencilState, Face, FragmentState, FrontFace, MultisampleState,
+        PipelineCache, PolygonMode, PrimitiveState, RenderPassDescriptor, RenderPipelineDescriptor,
+        SpecializedMeshPipeline, SpecializedMeshPipelineError, SpecializedMeshPipelines,
+        TextureFormat, VertexState,
     },
-    renderer::RenderDevice,
+    renderer::{RenderContext, RenderDevice},
     sync_world::{MainEntity, RenderEntity},
-    view::{check_visibility, ExtractedView, RenderVisibleEntities, VisibilitySystems},
+    view::{
+        check_visibility, ExtractedView, NoIndirectDrawing, RenderVisibleEntities, ViewTarget,
+        VisibilitySystems,
+    },
     Extract, Render, RenderApp, RenderSet,
 };
+use nonmax::NonMaxU32;
+
+const SHADER_ASSET_PATH: &str = "shaders/custom_draw_phase.wgsl";
 
 fn main() {
     App::new()
@@ -63,11 +86,13 @@ fn setup(
     commands.spawn((
         Mesh3d(meshes.add(Cuboid::new(1.0, 1.0, 1.0))),
         MeshMaterial3d(materials.add(Color::srgb_u8(124, 144, 255))),
-        Transform::from_xyz(0.0, 0.5, 0.0),
+        Transform::from_xyz(0.0, 2.5, 0.0),
         CustomDrawDataHandle(custom_draw.add(CustomDrawData {
             // Set it to red
             color: Vec4::new(1.0, 0.0, 0.0, 1.0),
         })),
+        // TODO temp
+        NoAutomaticBatching,
     ));
     // light
     commands.spawn((
@@ -81,10 +106,13 @@ fn setup(
     commands.spawn((
         Camera3d::default(),
         Transform::from_xyz(-2.0, 4.5, 9.0).looking_at(Vec3::ZERO, Vec3::Y),
+        // disable msaa for simplicity
+        Msaa::Off,
+        NoIndirectDrawing,
     ));
 }
 
-#[derive(Component, ExtractComponent, Clone, Copy)]
+#[derive(Component, ExtractComponent, Clone, Copy, Default)]
 struct CustomDrawMarker;
 
 /// A query filter that tells [`view::check_visibility`] about our custom
@@ -102,6 +130,8 @@ impl Plugin for CustomPhasPlugin {
         // do this by default, for efficiency reasons.
         app.add_systems(
             PostUpdate,
+            // For this example it isn't stricly necessary, we could rely on the check already done
+            // for the base mesh
             check_visibility::<WithCustomDraw>.in_set(VisibilitySystems::CheckVisibility),
         );
         // We need to get the render app from the main app
@@ -118,9 +148,16 @@ impl Plugin for CustomPhasPlugin {
                 Render,
                 (
                     sort_phase_system::<CustomPhase>.in_set(RenderSet::PhaseSort),
+                    batch_and_prepare_sorted_render_phase::<CustomPhase, CustomDrawPipeline>
+                        .in_set(RenderSet::PrepareResources),
                     queue_custom_meshes.in_set(RenderSet::QueueMeshes),
                 ),
             );
+
+        render_app
+            .add_render_graph_node::<ViewNodeRunner<CustomDrawNode>>(Core3d, CustomDrawPassLabel)
+            // Tell the node to run after the main pass
+            .add_render_graph_edges(Core3d, (Node3d::MainOpaquePass, CustomDrawPassLabel));
     }
 
     fn finish(&self, app: &mut App) {
@@ -142,23 +179,87 @@ struct CustomDrawData {
 #[derive(Resource)]
 struct CustomDrawPipeline {
     layout: BindGroupLayout,
+    /// The base mesh pipeline defined by bevy
+    ///
+    /// This isn't required, but if you want to use a bevy `Mesh` it's easier when you
+    /// have access to the base `MeshPipeline` that bevy already defines
+    mesh_pipeline: MeshPipeline,
+    /// Stores the shader used for this pipeline directly on the pipeline.
+    /// This isn't required, it's only done like this for simplicity.
+    shader_handle: Handle<Shader>,
 }
 impl FromWorld for CustomDrawPipeline {
     fn from_world(world: &mut World) -> Self {
+        // Load the shader
+        let shader_handle: Handle<Shader> = world.resource::<AssetServer>().load(SHADER_ASSET_PATH);
         Self {
             layout: CustomDrawData::bind_group_layout(world.resource::<RenderDevice>()),
+            mesh_pipeline: MeshPipeline::from_world(world),
+            shader_handle,
         }
     }
 }
 impl SpecializedMeshPipeline for CustomDrawPipeline {
-    type Key = u32;
+    type Key = MeshPipelineKey;
 
     fn specialize(
         &self,
         key: Self::Key,
         layout: &MeshVertexBufferLayoutRef,
     ) -> Result<RenderPipelineDescriptor, SpecializedMeshPipelineError> {
-        todo!()
+        // Define the vertex attributes based on a standard bevy [`Mesh`]
+        let mut vertex_attributes = Vec::new();
+        if layout.0.contains(Mesh::ATTRIBUTE_POSITION) {
+            // Make sure this matches the shader location
+            vertex_attributes.push(Mesh::ATTRIBUTE_POSITION.at_shader_location(0));
+        }
+        // This will automatically generate the correct `VertexBufferLayout` based on the vertex attributes
+        let vertex_buffer_layout = layout.0.get_layout(&vertex_attributes)?;
+
+        Ok(RenderPipelineDescriptor {
+            label: Some("Specialized Mesh Pipeline".into()),
+            layout: vec![
+                // Bind group 0 is the view uniform
+                self.mesh_pipeline
+                    .get_view_layout(MeshPipelineViewLayoutKey::from(key))
+                    .clone(),
+                // Bind group 1 is the mesh uniform
+                self.mesh_pipeline.mesh_layouts.model_only.clone(),
+                // Bind group 2 is our custom data
+                // TODO
+                //self.layout.clone(),
+            ],
+            push_constant_ranges: vec![],
+            vertex: VertexState {
+                shader: self.shader_handle.clone(),
+                shader_defs: vec![],
+                entry_point: "vertex".into(),
+                // Customize how to store the meshes' vertex attributes in the vertex buffer
+                buffers: vec![vertex_buffer_layout],
+            },
+            fragment: Some(FragmentState {
+                shader: self.shader_handle.clone(),
+                shader_defs: vec![],
+                entry_point: "fragment".into(),
+                targets: vec![Some(ColorTargetState {
+                    format: TextureFormat::bevy_default(),
+                    blend: None,
+                    write_mask: ColorWrites::ALL,
+                })],
+            }),
+            primitive: PrimitiveState {
+                topology: key.primitive_topology(),
+                front_face: FrontFace::Ccw,
+                cull_mode: Some(Face::Back),
+                polygon_mode: PolygonMode::Fill,
+                ..default()
+            },
+            depth_stencil: None,
+            // It's generally recommended to specialize your pipeline for MSAA,
+            // but it's not always possible
+            multisample: MultisampleState::default(),
+            zero_initialize_workgroup_memory: false,
+        })
     }
 }
 
@@ -203,6 +304,7 @@ type DrawCustom = (
 );
 
 #[derive(Component)]
+#[require(CustomDrawMarker)]
 struct CustomDrawDataHandle(Handle<CustomDrawData>);
 
 struct SetCustomBindGroup<const I: usize>;
@@ -219,16 +321,15 @@ impl<P: PhaseItem, const I: usize> RenderCommand<P> for SetCustomBindGroup<I> {
         assets: SystemParamItem<'w, '_, Self::Param>,
         pass: &mut TrackedRenderPass<'w>,
     ) -> RenderCommandResult {
-        let Some(material) = handle.and_then(|handle| assets.into_inner().get(&handle.0)) else {
-            return RenderCommandResult::Failure("invalid item query");
-        };
-        pass.set_bind_group(I, &material.bind_group, &[]);
+        // TODO
+        //let Some(material) = handle.and_then(|handle| assets.into_inner().get(&handle.0)) else {
+        //    return RenderCommandResult::Failure("invalid item query");
+        //};
+        //pass.set_bind_group(I, &material.bind_group, &[]);
         RenderCommandResult::Success
     }
 }
 
-// TODO ViewNode
-
 struct CustomPhase {
     pub sort_key: FloatOrd,
     pub entity: (Entity, MainEntity),
@@ -299,6 +400,102 @@ impl CachedRenderPipelinePhaseItem for CustomPhase {
     }
 }
 
+impl GetBatchData for CustomDrawPipeline {
+    type Param = (
+        SRes<RenderMeshInstances>,
+        SRes<RenderAssets<RenderMesh>>,
+        SRes<MeshAllocator>,
+    );
+    type CompareData = AssetId<Mesh>;
+    type BufferData = MeshUniform;
+
+    fn get_batch_data(
+        (mesh_instances, render_assets, mesh_allocator): &SystemParamItem<Self::Param>,
+        (_entity, main_entity): (Entity, MainEntity),
+    ) -> Option<(Self::BufferData, Option<Self::CompareData>)> {
+        let RenderMeshInstances::CpuBuilding(ref mesh_instances) = **mesh_instances else {
+            error!(
+                "`get_batch_data` should never be called in GPU mesh uniform \
+                building mode"
+            );
+            return None;
+        };
+        let mesh_instance = mesh_instances.get(&main_entity)?;
+        let first_vertex_index =
+            match mesh_allocator.mesh_vertex_slice(&mesh_instance.mesh_asset_id) {
+                Some(mesh_vertex_slice) => mesh_vertex_slice.range.start,
+                None => 0,
+            };
+        Some((
+            MeshUniform::new(
+                &mesh_instance.transforms,
+                first_vertex_index,
+                // TODO don't hardcode this
+                MaterialBindGroupSlot(0),
+                None,
+                None,
+                None,
+            ),
+            None,
+        ))
+    }
+}
+impl GetFullBatchData for CustomDrawPipeline {
+    type BufferInputData = MeshInputUniform;
+
+    fn get_index_and_compare_data(
+        (_, _, _): &SystemParamItem<Self::Param>,
+        (_entity, _main_entity): (Entity, MainEntity),
+    ) -> Option<(NonMaxU32, Option<Self::CompareData>)> {
+        None
+    }
+
+    fn get_binned_batch_data(
+        (mesh_instances, _render_assets, mesh_allocator): &SystemParamItem<Self::Param>,
+        (_entity, main_entity): (Entity, MainEntity),
+    ) -> Option<Self::BufferData> {
+        let RenderMeshInstances::CpuBuilding(ref mesh_instances) = **mesh_instances else {
+            error!(
+                "`get_binned_batch_data` should never be called in GPU mesh uniform building mode"
+            );
+            return None;
+        };
+        let mesh_instance = mesh_instances.get(&main_entity)?;
+        let first_vertex_index =
+            match mesh_allocator.mesh_vertex_slice(&mesh_instance.mesh_asset_id) {
+                Some(mesh_vertex_slice) => mesh_vertex_slice.range.start,
+                None => 0,
+            };
+
+        Some(MeshUniform::new(
+            &mesh_instance.transforms,
+            first_vertex_index,
+            mesh_instance.material_bindings_index.slot,
+            None,
+            None,
+            None,
+        ))
+    }
+
+    fn get_binned_index(
+        (_, _, _): &SystemParamItem<Self::Param>,
+        (_entity, _main_entity): (Entity, MainEntity),
+    ) -> Option<NonMaxU32> {
+        // This should only be called during GPU building.
+        // For this example we don't use GPU building.
+        None
+    }
+
+    fn get_batch_indirect_parameters_index(
+        (_, _, _): &SystemParamItem<Self::Param>,
+        _indirect_parameters_buffer: &mut IndirectParametersBuffer,
+        _entity: (Entity, MainEntity),
+        _instance_index: u32,
+    ) -> Option<NonMaxU32> {
+        // We don't use gpu preprocessing for this example
+        None
+    }
+}
 fn extract_camera_phases(
     mut custom_phases: ResMut<ViewSortedRenderPhases<CustomPhase>>,
     cameras: Extract<Query<(RenderEntity, &Camera), With<Camera3d>>>,
@@ -328,15 +525,19 @@ fn queue_custom_meshes(
     mut custom_render_phases: ResMut<ViewSortedRenderPhases<CustomPhase>>,
     mut views: Query<(Entity, &ExtractedView, &RenderVisibleEntities, &Msaa)>,
 ) {
-    for (view_entity, view, visible_entities, _msaa) in &mut views {
+    for (view_entity, view, visible_entities, msaa) in &mut views {
         let Some(custom_phase) = custom_render_phases.get_mut(&view_entity) else {
             continue;
         };
         let draw_custom = custom_draw_functions.read().id::<DrawCustom>();
 
+        // Create the key based on the view.
+        // In this case we only care about MSAA and HDR
+        let view_key = MeshPipelineKey::from_msaa_samples(msaa.samples())
+            | MeshPipelineKey::from_hdr(view.hdr);
+
         let rangefinder = view.rangefinder3d();
         for (render_entity, visible_entity) in visible_entities.iter::<WithCustomDraw>() {
-            println!("queue entities");
             let Some(mesh_instance) = render_mesh_instances.render_mesh_queue_data(*visible_entity)
             else {
                 continue;
@@ -344,10 +545,17 @@ fn queue_custom_meshes(
             let Some(mesh) = render_meshes.get(mesh_instance.mesh_asset_id) else {
                 continue;
             };
+
+            // Specialize the key for the current mesh entity
+            // For this example we only specialize based on the mesh topology
+            // but you could have more complex keys and that's where you'd need to create those keys
+            let mut mesh_key = view_key;
+            mesh_key |= MeshPipelineKey::from_primitive_topology(mesh.primitive_topology());
+
             let pipeline_id = pipelines.specialize(
                 &pipeline_cache,
                 &custom_draw_pipeline,
-                0, // TODO key
+                mesh_key,
                 &mesh.layout,
             );
             let pipeline_id = match pipeline_id {
@@ -371,3 +579,77 @@ fn queue_custom_meshes(
         }
     }
 }
+
+#[derive(RenderLabel, Debug, Clone, Hash, PartialEq, Eq)]
+struct CustomDrawPassLabel;
+
+#[derive(Default)]
+struct CustomDrawNode;
+impl ViewNode for CustomDrawNode {
+    type ViewQuery = (&'static ExtractedCamera, &'static ViewTarget);
+
+    fn run<'w>(
+        &self,
+        graph: &mut RenderGraphContext,
+        render_context: &mut RenderContext<'w>,
+        (camera, target): QueryItem<'w, Self::ViewQuery>,
+        world: &'w World,
+    ) -> Result<(), NodeRunError> {
+        let Some(custom_phases) = world.get_resource::<ViewSortedRenderPhases<CustomPhase>>()
+        else {
+            return Ok(());
+        };
+        // not reguired but makes profiling easier
+        let diagnostics = render_context.diagnostic_recorder();
+
+        let color_attachments = [Some(target.get_color_attachment())];
+
+        let view_entity = graph.view_entity();
+
+        let Some(custom_phase) = custom_phases.get(&view_entity) else {
+            return Ok(());
+        };
+
+        render_context.add_command_buffer_generation_task(move |render_device| {
+            #[cfg(feature = "trace")]
+            let _ = info_span!("custom phase pass").entered();
+
+            // Command encoder setup
+            let mut command_encoder =
+                render_device.create_command_encoder(&CommandEncoderDescriptor {
+                    label: Some("custom pass encoder"),
+                });
+
+            // Render pass setup
+            let render_pass = command_encoder.begin_render_pass(&RenderPassDescriptor {
+                label: Some("custom pass"),
+                color_attachments: &color_attachments,
+                // We don't bind any depth buffer for this pass
+                depth_stencil_attachment: None,
+                timestamp_writes: None,
+                occlusion_query_set: None,
+            });
+            let mut render_pass = TrackedRenderPass::new(&render_device, render_pass);
+            let pass_span = diagnostics.pass_span(&mut render_pass, "custom_pass");
+
+            if let Some(viewport) = camera.viewport.as_ref() {
+                render_pass.set_camera_viewport(viewport);
+            }
+
+            // Opaque draws
+            if !custom_phase.items.is_empty() {
+                #[cfg(feature = "trace")]
+                let _ = info_span!("custom pass").entered();
+                if let Err(err) = custom_phase.render(&mut render_pass, world, view_entity) {
+                    error!("Error encountered while rendering the custom phase {err:?}");
+                }
+            }
+
+            pass_span.end(&mut render_pass);
+            drop(render_pass);
+            command_encoder.finish()
+        });
+
+        Ok(())
+    }
+}

From dbdba93704d7a4d3bd5710c39d811ff46709454c Mon Sep 17 00:00:00 2001
From: IceSentry <c.giguere42@gmail.com>
Date: Fri, 20 Dec 2024 14:07:24 -0500
Subject: [PATCH 05/17] yeet custom material data

---
 examples/shader/custom_render_phase.rs | 152 ++++++-------------------
 1 file changed, 36 insertions(+), 116 deletions(-)

diff --git a/examples/shader/custom_render_phase.rs b/examples/shader/custom_render_phase.rs
index 6fa58d1b51cc8..e9af55a0067ce 100644
--- a/examples/shader/custom_render_phase.rs
+++ b/examples/shader/custom_render_phase.rs
@@ -11,11 +11,8 @@ use bevy::{
     core_pipeline::core_3d::graph::{Core3d, Node3d},
     ecs::{
         entity::EntityHashSet,
-        query::{QueryItem, ROQueryItem},
-        system::{
-            lifetimeless::{Read, SRes},
-            SystemParamItem,
-        },
+        query::QueryItem,
+        system::{lifetimeless::SRes, SystemParamItem},
     },
     math::FloatOrd,
     pbr::{
@@ -24,40 +21,38 @@ use bevy::{
         SetMeshBindGroup, SetMeshViewBindGroup,
     },
     prelude::*,
-};
-use bevy_render::{
-    batching::{
-        gpu_preprocessing::{batch_and_prepare_sorted_render_phase, IndirectParametersBuffer},
-        GetBatchData, GetFullBatchData, NoAutomaticBatching,
-    },
-    camera::ExtractedCamera,
-    diagnostic::RecordDiagnostics,
-    extract_component::{ExtractComponent, ExtractComponentPlugin, UniformComponentPlugin},
-    mesh::{allocator::MeshAllocator, MeshVertexBufferLayoutRef, RenderMesh},
-    render_asset::{PrepareAssetError, RenderAsset, RenderAssetPlugin, RenderAssets},
-    render_graph::{
-        NodeRunError, RenderGraphApp, RenderGraphContext, RenderLabel, ViewNode, ViewNodeRunner,
-    },
-    render_phase::{
-        sort_phase_system, AddRenderCommand, CachedRenderPipelinePhaseItem, DrawFunctionId,
-        DrawFunctions, PhaseItem, PhaseItemExtraIndex, RenderCommand, RenderCommandResult,
-        SetItemPipeline, SortedPhaseItem, TrackedRenderPass, ViewSortedRenderPhases,
-    },
-    render_resource::{
-        AsBindGroup, AsBindGroupError, BindGroup, BindGroupLayout, BindingResources,
-        CachedRenderPipelineId, ColorTargetState, ColorWrites, CommandEncoderDescriptor,
-        CompareFunction, DepthStencilState, Face, FragmentState, FrontFace, MultisampleState,
-        PipelineCache, PolygonMode, PrimitiveState, RenderPassDescriptor, RenderPipelineDescriptor,
-        SpecializedMeshPipeline, SpecializedMeshPipelineError, SpecializedMeshPipelines,
-        TextureFormat, VertexState,
-    },
-    renderer::{RenderContext, RenderDevice},
-    sync_world::{MainEntity, RenderEntity},
-    view::{
-        check_visibility, ExtractedView, NoIndirectDrawing, RenderVisibleEntities, ViewTarget,
-        VisibilitySystems,
+    render::{
+        batching::{
+            gpu_preprocessing::{batch_and_prepare_sorted_render_phase, IndirectParametersBuffer},
+            GetBatchData, GetFullBatchData, NoAutomaticBatching,
+        },
+        camera::ExtractedCamera,
+        diagnostic::RecordDiagnostics,
+        extract_component::{ExtractComponent, ExtractComponentPlugin},
+        mesh::{allocator::MeshAllocator, MeshVertexBufferLayoutRef, RenderMesh},
+        render_asset::RenderAssets,
+        render_graph::{
+            NodeRunError, RenderGraphApp, RenderGraphContext, RenderLabel, ViewNode, ViewNodeRunner,
+        },
+        render_phase::{
+            sort_phase_system, AddRenderCommand, CachedRenderPipelinePhaseItem, DrawFunctionId,
+            DrawFunctions, PhaseItem, PhaseItemExtraIndex, SetItemPipeline, SortedPhaseItem,
+            TrackedRenderPass, ViewSortedRenderPhases,
+        },
+        render_resource::{
+            CachedRenderPipelineId, ColorTargetState, ColorWrites, CommandEncoderDescriptor, Face,
+            FragmentState, FrontFace, MultisampleState, PipelineCache, PolygonMode, PrimitiveState,
+            RenderPassDescriptor, RenderPipelineDescriptor, SpecializedMeshPipeline,
+            SpecializedMeshPipelineError, SpecializedMeshPipelines, TextureFormat, VertexState,
+        },
+        renderer::RenderContext,
+        sync_world::{MainEntity, RenderEntity},
+        view::{
+            check_visibility, ExtractedView, NoIndirectDrawing, RenderVisibleEntities, ViewTarget,
+            VisibilitySystems,
+        },
+        Extract, Render, RenderApp, RenderSet,
     },
-    Extract, Render, RenderApp, RenderSet,
 };
 use nonmax::NonMaxU32;
 
@@ -74,7 +69,6 @@ fn setup(
     mut commands: Commands,
     mut meshes: ResMut<Assets<Mesh>>,
     mut materials: ResMut<Assets<StandardMaterial>>,
-    mut custom_draw: ResMut<Assets<CustomDrawData>>,
 ) {
     // circular base
     commands.spawn((
@@ -87,10 +81,7 @@ fn setup(
         Mesh3d(meshes.add(Cuboid::new(1.0, 1.0, 1.0))),
         MeshMaterial3d(materials.add(Color::srgb_u8(124, 144, 255))),
         Transform::from_xyz(0.0, 2.5, 0.0),
-        CustomDrawDataHandle(custom_draw.add(CustomDrawData {
-            // Set it to red
-            color: Vec4::new(1.0, 0.0, 0.0, 1.0),
-        })),
+        CustomDrawMarker,
         // TODO temp
         NoAutomaticBatching,
     ));
@@ -122,10 +113,7 @@ type WithCustomDraw = With<CustomDrawMarker>;
 struct CustomPhasPlugin;
 impl Plugin for CustomPhasPlugin {
     fn build(&self, app: &mut App) {
-        app.init_asset::<CustomDrawData>().add_plugins((
-            RenderAssetPlugin::<PreparedCustomDrawData>::default(),
-            ExtractComponentPlugin::<CustomDrawMarker>::default(),
-        ));
+        app.add_plugins((ExtractComponentPlugin::<CustomDrawMarker>::default(),));
         // Make sure to tell Bevy to check our entity for visibility. Bevy won't
         // do this by default, for efficiency reasons.
         app.add_systems(
@@ -170,15 +158,8 @@ impl Plugin for CustomPhasPlugin {
     }
 }
 
-#[derive(AsBindGroup, Asset, Clone, TypePath)]
-struct CustomDrawData {
-    #[uniform(0)]
-    color: Vec4,
-}
-
 #[derive(Resource)]
 struct CustomDrawPipeline {
-    layout: BindGroupLayout,
     /// The base mesh pipeline defined by bevy
     ///
     /// This isn't required, but if you want to use a bevy `Mesh` it's easier when you
@@ -193,7 +174,6 @@ impl FromWorld for CustomDrawPipeline {
         // Load the shader
         let shader_handle: Handle<Shader> = world.resource::<AssetServer>().load(SHADER_ASSET_PATH);
         Self {
-            layout: CustomDrawData::bind_group_layout(world.resource::<RenderDevice>()),
             mesh_pipeline: MeshPipeline::from_world(world),
             shader_handle,
         }
@@ -263,73 +243,13 @@ impl SpecializedMeshPipeline for CustomDrawPipeline {
     }
 }
 
-/// Data prepared for a custom draw
-struct PreparedCustomDrawData {
-    bindings: BindingResources,
-    bind_group: BindGroup,
-}
-impl RenderAsset for PreparedCustomDrawData {
-    type SourceAsset = CustomDrawData;
-
-    type Param = (
-        SRes<RenderDevice>,
-        SRes<CustomDrawPipeline>,
-        <CustomDrawData as AsBindGroup>::Param,
-    );
-
-    fn prepare_asset(
-        material: Self::SourceAsset,
-        _: AssetId<Self::SourceAsset>,
-        (render_device, pipeline, data_param): &mut SystemParamItem<Self::Param>,
-    ) -> Result<Self, PrepareAssetError<Self::SourceAsset>> {
-        match material.as_bind_group(&pipeline.layout, render_device, data_param) {
-            Ok(prepared) => Ok(PreparedCustomDrawData {
-                bindings: prepared.bindings,
-                bind_group: prepared.bind_group,
-            }),
-            Err(AsBindGroupError::RetryNextUpdate) => {
-                Err(PrepareAssetError::RetryNextUpdate(material))
-            }
-            Err(other) => Err(PrepareAssetError::AsBindGroupError(other)),
-        }
-    }
-}
-
 type DrawCustom = (
     SetItemPipeline,
     SetMeshViewBindGroup<0>,
     SetMeshBindGroup<1>,
-    SetCustomBindGroup<2>,
     DrawMesh,
 );
 
-#[derive(Component)]
-#[require(CustomDrawMarker)]
-struct CustomDrawDataHandle(Handle<CustomDrawData>);
-
-struct SetCustomBindGroup<const I: usize>;
-impl<P: PhaseItem, const I: usize> RenderCommand<P> for SetCustomBindGroup<I> {
-    type Param = SRes<RenderAssets<PreparedCustomDrawData>>;
-    type ViewQuery = ();
-    type ItemQuery = Read<CustomDrawDataHandle>;
-
-    #[inline]
-    fn render<'w>(
-        _item: &P,
-        _view: (),
-        handle: Option<ROQueryItem<'w, Self::ItemQuery>>,
-        assets: SystemParamItem<'w, '_, Self::Param>,
-        pass: &mut TrackedRenderPass<'w>,
-    ) -> RenderCommandResult {
-        // TODO
-        //let Some(material) = handle.and_then(|handle| assets.into_inner().get(&handle.0)) else {
-        //    return RenderCommandResult::Failure("invalid item query");
-        //};
-        //pass.set_bind_group(I, &material.bind_group, &[]);
-        RenderCommandResult::Success
-    }
-}
-
 struct CustomPhase {
     pub sort_key: FloatOrd,
     pub entity: (Entity, MainEntity),
@@ -410,7 +330,7 @@ impl GetBatchData for CustomDrawPipeline {
     type BufferData = MeshUniform;
 
     fn get_batch_data(
-        (mesh_instances, render_assets, mesh_allocator): &SystemParamItem<Self::Param>,
+        (mesh_instances, _render_assets, mesh_allocator): &SystemParamItem<Self::Param>,
         (_entity, main_entity): (Entity, MainEntity),
     ) -> Option<(Self::BufferData, Option<Self::CompareData>)> {
         let RenderMeshInstances::CpuBuilding(ref mesh_instances) = **mesh_instances else {

From c37b089ce3fe3e558799dde0f9a0e52bd3575e4e Mon Sep 17 00:00:00 2001
From: IceSentry <c.giguere42@gmail.com>
Date: Fri, 20 Dec 2024 14:26:53 -0500
Subject: [PATCH 06/17] fix gpu processing

---
 examples/shader/custom_render_phase.rs | 31 +++++++++++++++++++++-----
 1 file changed, 26 insertions(+), 5 deletions(-)

diff --git a/examples/shader/custom_render_phase.rs b/examples/shader/custom_render_phase.rs
index e9af55a0067ce..91d5fbe66846e 100644
--- a/examples/shader/custom_render_phase.rs
+++ b/examples/shader/custom_render_phase.rs
@@ -5,6 +5,7 @@
 //! Sometimes, you may want to only draw a subset of meshes before or after the builtin phase. In
 //! those situations you need to write your own phase.
 
+use core::panic;
 use std::ops::Range;
 
 use bevy::{
@@ -54,6 +55,10 @@ use bevy::{
         Extract, Render, RenderApp, RenderSet,
     },
 };
+use bevy_render::{
+    batching::gpu_preprocessing::{GpuPreprocessingMode, GpuPreprocessingSupport},
+    view::NoFrustumCulling,
+};
 use nonmax::NonMaxU32;
 
 const SHADER_ASSET_PATH: &str = "shaders/custom_draw_phase.wgsl";
@@ -75,6 +80,7 @@ fn setup(
         Mesh3d(meshes.add(Circle::new(4.0))),
         MeshMaterial3d(materials.add(Color::WHITE)),
         Transform::from_rotation(Quat::from_rotation_x(-std::f32::consts::FRAC_PI_2)),
+        //NoAutomaticBatching,
     ));
     // cube
     commands.spawn((
@@ -83,7 +89,8 @@ fn setup(
         Transform::from_xyz(0.0, 2.5, 0.0),
         CustomDrawMarker,
         // TODO temp
-        NoAutomaticBatching,
+        //NoAutomaticBatching,
+        //NoFrustumCulling,
     ));
     // light
     commands.spawn((
@@ -99,7 +106,7 @@ fn setup(
         Transform::from_xyz(-2.0, 4.5, 9.0).looking_at(Vec3::ZERO, Vec3::Y),
         // disable msaa for simplicity
         Msaa::Off,
-        NoIndirectDrawing,
+        //NoIndirectDrawing,
     ));
 }
 
@@ -364,10 +371,24 @@ impl GetFullBatchData for CustomDrawPipeline {
     type BufferInputData = MeshInputUniform;
 
     fn get_index_and_compare_data(
-        (_, _, _): &SystemParamItem<Self::Param>,
-        (_entity, _main_entity): (Entity, MainEntity),
+        (mesh_instances, _, _): &SystemParamItem<Self::Param>,
+        (_entity, main_entity): (Entity, MainEntity),
     ) -> Option<(NonMaxU32, Option<Self::CompareData>)> {
-        None
+        // This should only be called during GPU building.
+        let RenderMeshInstances::GpuBuilding(ref mesh_instances) = **mesh_instances else {
+            error!(
+                "`get_index_and_compare_data` should never be called in CPU mesh uniform building \
+                mode"
+            );
+            return None;
+        };
+        let mesh_instance = mesh_instances.get(&main_entity)?;
+        Some((
+            mesh_instance.current_uniform_index,
+            mesh_instance
+                .should_batch()
+                .then_some(mesh_instance.mesh_asset_id),
+        ))
     }
 
     fn get_binned_batch_data(

From a4b70c50ecf28c84b9f7e0b8e7c089265828b9a6 Mon Sep 17 00:00:00 2001
From: IceSentry <c.giguere42@gmail.com>
Date: Fri, 20 Dec 2024 15:39:44 -0500
Subject: [PATCH 07/17] yeet check vis and rename some stuff

---
 examples/shader/custom_render_phase.rs | 57 ++++++++------------------
 1 file changed, 18 insertions(+), 39 deletions(-)

diff --git a/examples/shader/custom_render_phase.rs b/examples/shader/custom_render_phase.rs
index 91d5fbe66846e..5bb18c724a1de 100644
--- a/examples/shader/custom_render_phase.rs
+++ b/examples/shader/custom_render_phase.rs
@@ -5,7 +5,6 @@
 //! Sometimes, you may want to only draw a subset of meshes before or after the builtin phase. In
 //! those situations you need to write your own phase.
 
-use core::panic;
 use std::ops::Range;
 
 use bevy::{
@@ -25,7 +24,7 @@ use bevy::{
     render::{
         batching::{
             gpu_preprocessing::{batch_and_prepare_sorted_render_phase, IndirectParametersBuffer},
-            GetBatchData, GetFullBatchData, NoAutomaticBatching,
+            GetBatchData, GetFullBatchData,
         },
         camera::ExtractedCamera,
         diagnostic::RecordDiagnostics,
@@ -48,24 +47,17 @@ use bevy::{
         },
         renderer::RenderContext,
         sync_world::{MainEntity, RenderEntity},
-        view::{
-            check_visibility, ExtractedView, NoIndirectDrawing, RenderVisibleEntities, ViewTarget,
-            VisibilitySystems,
-        },
+        view::{ExtractedView, RenderVisibleEntities, ViewTarget},
         Extract, Render, RenderApp, RenderSet,
     },
 };
-use bevy_render::{
-    batching::gpu_preprocessing::{GpuPreprocessingMode, GpuPreprocessingSupport},
-    view::NoFrustumCulling,
-};
 use nonmax::NonMaxU32;
 
 const SHADER_ASSET_PATH: &str = "shaders/custom_draw_phase.wgsl";
 
 fn main() {
     App::new()
-        .add_plugins((DefaultPlugins, CustomPhasPlugin))
+        .add_plugins((DefaultPlugins, MeshStencilPhasePlugin))
         .add_systems(Startup, setup)
         .run();
 }
@@ -80,17 +72,17 @@ fn setup(
         Mesh3d(meshes.add(Circle::new(4.0))),
         MeshMaterial3d(materials.add(Color::WHITE)),
         Transform::from_rotation(Quat::from_rotation_x(-std::f32::consts::FRAC_PI_2)),
-        //NoAutomaticBatching,
     ));
     // cube
+    // This cube will be rendered by the main pass, but it will also be rendered by our custom
+    // pass. This should result in an unlit red cube
     commands.spawn((
         Mesh3d(meshes.add(Cuboid::new(1.0, 1.0, 1.0))),
         MeshMaterial3d(materials.add(Color::srgb_u8(124, 144, 255))),
-        Transform::from_xyz(0.0, 2.5, 0.0),
-        CustomDrawMarker,
-        // TODO temp
-        //NoAutomaticBatching,
-        //NoFrustumCulling,
+        Transform::from_xyz(0.0, 0.5, 0.0),
+        // This marker component is used to identify which mesh will be used in our custom pass
+        // The circle doesn't have it so it won't be rendered in our pass
+        DrawStencil,
     ));
     // light
     commands.spawn((
@@ -106,29 +98,16 @@ fn setup(
         Transform::from_xyz(-2.0, 4.5, 9.0).looking_at(Vec3::ZERO, Vec3::Y),
         // disable msaa for simplicity
         Msaa::Off,
-        //NoIndirectDrawing,
     ));
 }
 
 #[derive(Component, ExtractComponent, Clone, Copy, Default)]
-struct CustomDrawMarker;
-
-/// A query filter that tells [`view::check_visibility`] about our custom
-/// rendered entity.
-type WithCustomDraw = With<CustomDrawMarker>;
+struct DrawStencil;
 
-struct CustomPhasPlugin;
-impl Plugin for CustomPhasPlugin {
+struct MeshStencilPhasePlugin;
+impl Plugin for MeshStencilPhasePlugin {
     fn build(&self, app: &mut App) {
-        app.add_plugins((ExtractComponentPlugin::<CustomDrawMarker>::default(),));
-        // Make sure to tell Bevy to check our entity for visibility. Bevy won't
-        // do this by default, for efficiency reasons.
-        app.add_systems(
-            PostUpdate,
-            // For this example it isn't stricly necessary, we could rely on the check already done
-            // for the base mesh
-            check_visibility::<WithCustomDraw>.in_set(VisibilitySystems::CheckVisibility),
-        );
+        app.add_plugins((ExtractComponentPlugin::<DrawStencil>::default(),));
         // We need to get the render app from the main app
         let Some(render_app) = app.get_sub_app_mut(RenderApp) else {
             return;
@@ -212,9 +191,6 @@ impl SpecializedMeshPipeline for CustomDrawPipeline {
                     .clone(),
                 // Bind group 1 is the mesh uniform
                 self.mesh_pipeline.mesh_layouts.model_only.clone(),
-                // Bind group 2 is our custom data
-                // TODO
-                //self.layout.clone(),
             ],
             push_constant_ranges: vec![],
             vertex: VertexState {
@@ -449,7 +425,6 @@ fn extract_camera_phases(
         }
         custom_phases.insert_or_clear(entity);
         live_entities.insert(entity);
-        //println!("phase extracted");
     }
     // Clear out all dead views.
     custom_phases.retain(|camera_entity, _| live_entities.contains(camera_entity));
@@ -465,6 +440,7 @@ fn queue_custom_meshes(
     render_mesh_instances: Res<RenderMeshInstances>,
     mut custom_render_phases: ResMut<ViewSortedRenderPhases<CustomPhase>>,
     mut views: Query<(Entity, &ExtractedView, &RenderVisibleEntities, &Msaa)>,
+    has_marker: Query<(), With<DrawStencil>>,
 ) {
     for (view_entity, view, visible_entities, msaa) in &mut views {
         let Some(custom_phase) = custom_render_phases.get_mut(&view_entity) else {
@@ -478,7 +454,10 @@ fn queue_custom_meshes(
             | MeshPipelineKey::from_hdr(view.hdr);
 
         let rangefinder = view.rangefinder3d();
-        for (render_entity, visible_entity) in visible_entities.iter::<WithCustomDraw>() {
+        for (render_entity, visible_entity) in visible_entities.iter::<Mesh3d>() {
+            if has_marker.get(*render_entity).is_err() {
+                continue;
+            }
             let Some(mesh_instance) = render_mesh_instances.render_mesh_queue_data(*visible_entity)
             else {
                 continue;

From 36c13911e08c897e1851a6f71be1078126996455 Mon Sep 17 00:00:00 2001
From: IceSentry <c.giguere42@gmail.com>
Date: Fri, 20 Dec 2024 16:07:43 -0500
Subject: [PATCH 08/17] wip docs

---
 ...om_draw_phase.wgsl => custom_stencil.wgsl} |   8 +-
 examples/shader/custom_render_phase.rs        | 127 +++++++++++-------
 2 files changed, 85 insertions(+), 50 deletions(-)
 rename assets/shaders/{custom_draw_phase.wgsl => custom_stencil.wgsl} (80%)

diff --git a/assets/shaders/custom_draw_phase.wgsl b/assets/shaders/custom_stencil.wgsl
similarity index 80%
rename from assets/shaders/custom_draw_phase.wgsl
rename to assets/shaders/custom_stencil.wgsl
index 8d3419b656b7a..ce0a2e8d46e37 100644
--- a/assets/shaders/custom_draw_phase.wgsl
+++ b/assets/shaders/custom_stencil.wgsl
@@ -1,5 +1,5 @@
-//! Very simple shader used to demonstrate how to get the world position and pass data
-//! between the vertex and fragment shader. Also shows the custom vertex layout.
+//! Very simple shader showing how to use the vertex position data correctly to output the 
+//! correct stencil in the right position
 
 // First we import everything we need from bevy_pbr
 // A 2d shader would be vevry similar but import from bevy_sprite instead
@@ -27,7 +27,7 @@ struct VertexOutput {
 fn vertex(vertex: Vertex) -> VertexOutput {
     var out: VertexOutput;
     // This is how bevy computes the world position
-    // The vertex.instance_index is very important. Esepecially if you are using batching and gpu preprocessing
+    // The vertex.instance_index is very important. Especially if you are using batching and gpu preprocessing
     var world_from_local = mesh_functions::get_world_from_local(vertex.instance_index);
     out.world_position = mesh_functions::mesh_position_local_to_world(world_from_local, vec4(vertex.position, 1.0));
     out.clip_position = position_world_to_clip(out.world_position.xyz);
@@ -36,6 +36,6 @@ fn vertex(vertex: Vertex) -> VertexOutput {
 
 @fragment
 fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
-    // Just output a red color
+    // Just output a red color to represent the stencil of the mesh
     return vec4(1.0, 0.0, 0.0, 1.0);
 }
diff --git a/examples/shader/custom_render_phase.rs b/examples/shader/custom_render_phase.rs
index 5bb18c724a1de..d95975bb07cb5 100644
--- a/examples/shader/custom_render_phase.rs
+++ b/examples/shader/custom_render_phase.rs
@@ -4,6 +4,11 @@
 //! For example, bevy's main pass has an opaque phase, a transparent phase for both 2d and 3d.
 //! Sometimes, you may want to only draw a subset of meshes before or after the builtin phase. In
 //! those situations you need to write your own phase.
+//!
+//! This examples showcase how writing a custom phase to draw a stencil of a bevy mesh could look
+//! like. Some shortcuts have been used for simplicity.
+//!
+//! This example was made for 3d, but a 2d equivalent would be almost identical.
 
 use std::ops::Range;
 
@@ -53,7 +58,7 @@ use bevy::{
 };
 use nonmax::NonMaxU32;
 
-const SHADER_ASSET_PATH: &str = "shaders/custom_draw_phase.wgsl";
+const SHADER_ASSET_PATH: &str = "shaders/custom_stencil.wgsl";
 
 fn main() {
     App::new()
@@ -113,16 +118,16 @@ impl Plugin for MeshStencilPhasePlugin {
             return;
         };
         render_app
-            .init_resource::<SpecializedMeshPipelines<CustomDrawPipeline>>()
-            .init_resource::<DrawFunctions<CustomPhase>>()
-            .add_render_command::<CustomPhase, DrawCustom>()
-            .init_resource::<ViewSortedRenderPhases<CustomPhase>>()
+            .init_resource::<SpecializedMeshPipelines<StencilPipeline>>()
+            .init_resource::<DrawFunctions<StencilPhase>>()
+            .add_render_command::<StencilPhase, DrawMesh3dStencil>()
+            .init_resource::<ViewSortedRenderPhases<StencilPhase>>()
             .add_systems(ExtractSchedule, extract_camera_phases)
             .add_systems(
                 Render,
                 (
-                    sort_phase_system::<CustomPhase>.in_set(RenderSet::PhaseSort),
-                    batch_and_prepare_sorted_render_phase::<CustomPhase, CustomDrawPipeline>
+                    sort_phase_system::<StencilPhase>.in_set(RenderSet::PhaseSort),
+                    batch_and_prepare_sorted_render_phase::<StencilPhase, StencilPipeline>
                         .in_set(RenderSet::PrepareResources),
                     queue_custom_meshes.in_set(RenderSet::QueueMeshes),
                 ),
@@ -139,33 +144,34 @@ impl Plugin for MeshStencilPhasePlugin {
         let Some(render_app) = app.get_sub_app_mut(RenderApp) else {
             return;
         };
-
-        render_app.init_resource::<CustomDrawPipeline>();
+        // The pipeline needs the RenderDevice to be created and it's only available once plugins
+        // are intialized
+        render_app.init_resource::<StencilPipeline>();
     }
 }
 
 #[derive(Resource)]
-struct CustomDrawPipeline {
+struct StencilPipeline {
     /// The base mesh pipeline defined by bevy
     ///
-    /// This isn't required, but if you want to use a bevy `Mesh` it's easier when you
-    /// have access to the base `MeshPipeline` that bevy already defines
+    /// Since we want to draw a stencil of an existing bevy mesh we want to reuse the default
+    /// pipeline as much as possible
     mesh_pipeline: MeshPipeline,
     /// Stores the shader used for this pipeline directly on the pipeline.
     /// This isn't required, it's only done like this for simplicity.
     shader_handle: Handle<Shader>,
 }
-impl FromWorld for CustomDrawPipeline {
+impl FromWorld for StencilPipeline {
     fn from_world(world: &mut World) -> Self {
-        // Load the shader
-        let shader_handle: Handle<Shader> = world.resource::<AssetServer>().load(SHADER_ASSET_PATH);
         Self {
             mesh_pipeline: MeshPipeline::from_world(world),
-            shader_handle,
+            shader_handle: world.resource::<AssetServer>().load(SHADER_ASSET_PATH),
         }
     }
 }
-impl SpecializedMeshPipeline for CustomDrawPipeline {
+// For more information on how SpecializedMeshPipeline work, please look at the
+// specialized_mesh_pipeline example
+impl SpecializedMeshPipeline for StencilPipeline {
     type Key = MeshPipelineKey;
 
     fn specialize(
@@ -173,7 +179,7 @@ impl SpecializedMeshPipeline for CustomDrawPipeline {
         key: Self::Key,
         layout: &MeshVertexBufferLayoutRef,
     ) -> Result<RenderPipelineDescriptor, SpecializedMeshPipelineError> {
-        // Define the vertex attributes based on a standard bevy [`Mesh`]
+        // We will only use the position of the mesh in our shader so we only need to specify that
         let mut vertex_attributes = Vec::new();
         if layout.0.contains(Mesh::ATTRIBUTE_POSITION) {
             // Make sure this matches the shader location
@@ -184,6 +190,8 @@ impl SpecializedMeshPipeline for CustomDrawPipeline {
 
         Ok(RenderPipelineDescriptor {
             label: Some("Specialized Mesh Pipeline".into()),
+            // We want to reuse the data from bevy so we use the same bind groups as the default
+            // mesh pipeline
             layout: vec![
                 // Bind group 0 is the view uniform
                 self.mesh_pipeline
@@ -197,7 +205,6 @@ impl SpecializedMeshPipeline for CustomDrawPipeline {
                 shader: self.shader_handle.clone(),
                 shader_defs: vec![],
                 entry_point: "vertex".into(),
-                // Customize how to store the meshes' vertex attributes in the vertex buffer
                 buffers: vec![vertex_buffer_layout],
             },
             fragment: Some(FragmentState {
@@ -226,14 +233,25 @@ impl SpecializedMeshPipeline for CustomDrawPipeline {
     }
 }
 
-type DrawCustom = (
+// We will reuse render commands already defined by bevy to draw a 3d mesh
+type DrawMesh3dStencil = (
     SetItemPipeline,
+    // This will set the view bindings in group 0
     SetMeshViewBindGroup<0>,
+    // This will set the mesh bindings in group 1
     SetMeshBindGroup<1>,
+    // This will draw the mesh
     DrawMesh,
 );
 
-struct CustomPhase {
+// This is the data required when you define a custom phase in bevy. More specifically this is the
+// data required when using a ViewSortedRenderPhase. This would look differently if we wanted a
+// batched render phase. Sorted phase are a bit easier to implement, but a batched phased would
+// look similar.
+//
+// If you want to see how a batched phase implementation looks, you should look at the Opaque2d
+// phase.
+struct StencilPhase {
     pub sort_key: FloatOrd,
     pub entity: (Entity, MainEntity),
     pub pipeline: CachedRenderPipelineId,
@@ -242,7 +260,8 @@ struct CustomPhase {
     pub extra_index: PhaseItemExtraIndex,
 }
 
-impl PhaseItem for CustomPhase {
+// For more information about writing a phase item, please look at the custom_phase_item example
+impl PhaseItem for StencilPhase {
     #[inline]
     fn entity(&self) -> Entity {
         self.entity.0
@@ -279,7 +298,7 @@ impl PhaseItem for CustomPhase {
     }
 }
 
-impl SortedPhaseItem for CustomPhase {
+impl SortedPhaseItem for StencilPhase {
     type SortKey = FloatOrd;
 
     #[inline]
@@ -296,14 +315,14 @@ impl SortedPhaseItem for CustomPhase {
     }
 }
 
-impl CachedRenderPipelinePhaseItem for CustomPhase {
+impl CachedRenderPipelinePhaseItem for StencilPhase {
     #[inline]
     fn cached_pipeline(&self) -> CachedRenderPipelineId {
         self.pipeline
     }
 }
 
-impl GetBatchData for CustomDrawPipeline {
+impl GetBatchData for StencilPipeline {
     type Param = (
         SRes<RenderMeshInstances>,
         SRes<RenderAssets<RenderMesh>>,
@@ -343,7 +362,7 @@ impl GetBatchData for CustomDrawPipeline {
         ))
     }
 }
-impl GetFullBatchData for CustomDrawPipeline {
+impl GetFullBatchData for StencilPipeline {
     type BufferInputData = MeshInputUniform;
 
     fn get_index_and_compare_data(
@@ -394,12 +413,12 @@ impl GetFullBatchData for CustomDrawPipeline {
         ))
     }
 
+    // TODO
+
     fn get_binned_index(
         (_, _, _): &SystemParamItem<Self::Param>,
         (_entity, _main_entity): (Entity, MainEntity),
     ) -> Option<NonMaxU32> {
-        // This should only be called during GPU building.
-        // For this example we don't use GPU building.
         None
     }
 
@@ -409,12 +428,14 @@ impl GetFullBatchData for CustomDrawPipeline {
         _entity: (Entity, MainEntity),
         _instance_index: u32,
     ) -> Option<NonMaxU32> {
-        // We don't use gpu preprocessing for this example
         None
     }
 }
+// When defining a custom phase, we need to extract it from the main world and add it to a resource
+// that will be used by the render world. We need to give that resource all views that will use
+// that phase
 fn extract_camera_phases(
-    mut custom_phases: ResMut<ViewSortedRenderPhases<CustomPhase>>,
+    mut custom_phases: ResMut<ViewSortedRenderPhases<StencilPhase>>,
     cameras: Extract<Query<(RenderEntity, &Camera), With<Camera3d>>>,
     mut live_entities: Local<EntityHashSet>,
 ) {
@@ -430,15 +451,18 @@ fn extract_camera_phases(
     custom_phases.retain(|camera_entity, _| live_entities.contains(camera_entity));
 }
 
+// This is a very important step when writing a custom phase.
+//
+// This system determines which mesh will be added to the phase.
 #[allow(clippy::too_many_arguments)]
 fn queue_custom_meshes(
-    custom_draw_functions: Res<DrawFunctions<CustomPhase>>,
-    mut pipelines: ResMut<SpecializedMeshPipelines<CustomDrawPipeline>>,
+    custom_draw_functions: Res<DrawFunctions<StencilPhase>>,
+    mut pipelines: ResMut<SpecializedMeshPipelines<StencilPipeline>>,
     pipeline_cache: Res<PipelineCache>,
-    custom_draw_pipeline: Res<CustomDrawPipeline>,
+    custom_draw_pipeline: Res<StencilPipeline>,
     render_meshes: Res<RenderAssets<RenderMesh>>,
     render_mesh_instances: Res<RenderMeshInstances>,
-    mut custom_render_phases: ResMut<ViewSortedRenderPhases<CustomPhase>>,
+    mut custom_render_phases: ResMut<ViewSortedRenderPhases<StencilPhase>>,
     mut views: Query<(Entity, &ExtractedView, &RenderVisibleEntities, &Msaa)>,
     has_marker: Query<(), With<DrawStencil>>,
 ) {
@@ -446,7 +470,7 @@ fn queue_custom_meshes(
         let Some(custom_phase) = custom_render_phases.get_mut(&view_entity) else {
             continue;
         };
-        let draw_custom = custom_draw_functions.read().id::<DrawCustom>();
+        let draw_custom = custom_draw_functions.read().id::<DrawMesh3dStencil>();
 
         // Create the key based on the view.
         // In this case we only care about MSAA and HDR
@@ -454,7 +478,9 @@ fn queue_custom_meshes(
             | MeshPipelineKey::from_hdr(view.hdr);
 
         let rangefinder = view.rangefinder3d();
+        // Since our phase can work on any 3d mesh we can reuse the default mesh 2d filter
         for (render_entity, visible_entity) in visible_entities.iter::<Mesh3d>() {
+            // We only want meshes with the marker component to be queued to our phase.
             if has_marker.get(*render_entity).is_err() {
                 continue;
             }
@@ -486,7 +512,9 @@ fn queue_custom_meshes(
                 }
             };
             let distance = rangefinder.distance_translation(&mesh_instance.translation);
-            custom_phase.add(CustomPhase {
+            // At this point we have all the data we need to create a phase item and add it to our
+            // phase
+            custom_phase.add(StencilPhase {
                 // Sort the data based on the distance to the view
                 sort_key: FloatOrd(distance),
                 entity: (*render_entity, *visible_entity),
@@ -500,6 +528,7 @@ fn queue_custom_meshes(
     }
 }
 
+// Render label used to order our render graph node that will render our phase
 #[derive(RenderLabel, Debug, Clone, Hash, PartialEq, Eq)]
 struct CustomDrawPassLabel;
 
@@ -515,34 +544,42 @@ impl ViewNode for CustomDrawNode {
         (camera, target): QueryItem<'w, Self::ViewQuery>,
         world: &'w World,
     ) -> Result<(), NodeRunError> {
-        let Some(custom_phases) = world.get_resource::<ViewSortedRenderPhases<CustomPhase>>()
+        // First, we need to get ou phases resource
+        let Some(stencil_phases) = world.get_resource::<ViewSortedRenderPhases<StencilPhase>>()
         else {
             return Ok(());
         };
+        // Initiazlie diagnostic recording.
         // not reguired but makes profiling easier
         let diagnostics = render_context.diagnostic_recorder();
 
+        // For the purpose of the example, we will write directly to the view target. A real
+        // stencil pass would write to a custom texture and that texture would be used in later
+        // passes to render custom effects using it.
         let color_attachments = [Some(target.get_color_attachment())];
 
+        // Get the view entity from the graph
         let view_entity = graph.view_entity();
 
-        let Some(custom_phase) = custom_phases.get(&view_entity) else {
+        // Get the phase for the current view running our node
+        let Some(stencil_phase) = stencil_phases.get(&view_entity) else {
             return Ok(());
         };
 
+        // This will generate a task to generate the command buffer in parallel
         render_context.add_command_buffer_generation_task(move |render_device| {
             #[cfg(feature = "trace")]
-            let _ = info_span!("custom phase pass").entered();
+            let _ = info_span!("custom_stencil_pass").entered();
 
             // Command encoder setup
             let mut command_encoder =
                 render_device.create_command_encoder(&CommandEncoderDescriptor {
-                    label: Some("custom pass encoder"),
+                    label: Some("custom stencil pass encoder"),
                 });
 
             // Render pass setup
             let render_pass = command_encoder.begin_render_pass(&RenderPassDescriptor {
-                label: Some("custom pass"),
+                label: Some("stencil pass"),
                 color_attachments: &color_attachments,
                 // We don't bind any depth buffer for this pass
                 depth_stencil_attachment: None,
@@ -556,11 +593,9 @@ impl ViewNode for CustomDrawNode {
                 render_pass.set_camera_viewport(viewport);
             }
 
-            // Opaque draws
-            if !custom_phase.items.is_empty() {
-                #[cfg(feature = "trace")]
-                let _ = info_span!("custom pass").entered();
-                if let Err(err) = custom_phase.render(&mut render_pass, world, view_entity) {
+            // Render the phase
+            if !stencil_phase.items.is_empty() {
+                if let Err(err) = stencil_phase.render(&mut render_pass, world, view_entity) {
                     error!("Error encountered while rendering the custom phase {err:?}");
                 }
             }

From 0150d7964224742eba681c4437b9dea5c1ffc61e Mon Sep 17 00:00:00 2001
From: Christopher Biscardi <chris@christopherbiscardi.com>
Date: Thu, 16 Jan 2025 09:43:02 -0800
Subject: [PATCH 09/17] docs updates and typo fixes

---
 assets/shaders/custom_stencil.wgsl     |  6 +++---
 examples/shader/custom_render_phase.rs | 16 +++++++++-------
 2 files changed, 12 insertions(+), 10 deletions(-)

diff --git a/assets/shaders/custom_stencil.wgsl b/assets/shaders/custom_stencil.wgsl
index ce0a2e8d46e37..6f2fa2da4f977 100644
--- a/assets/shaders/custom_stencil.wgsl
+++ b/assets/shaders/custom_stencil.wgsl
@@ -1,5 +1,5 @@
-//! Very simple shader showing how to use the vertex position data correctly to output the 
-//! correct stencil in the right position
+//! A shader showing how to use the vertex position data to output the 
+//! stencil in the right position
 
 // First we import everything we need from bevy_pbr
 // A 2d shader would be vevry similar but import from bevy_sprite instead
@@ -36,6 +36,6 @@ fn vertex(vertex: Vertex) -> VertexOutput {
 
 @fragment
 fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
-    // Just output a red color to represent the stencil of the mesh
+    // Output a red color to represent the stencil of the mesh
     return vec4(1.0, 0.0, 0.0, 1.0);
 }
diff --git a/examples/shader/custom_render_phase.rs b/examples/shader/custom_render_phase.rs
index d95975bb07cb5..fd1fb1c57b02e 100644
--- a/examples/shader/custom_render_phase.rs
+++ b/examples/shader/custom_render_phase.rs
@@ -1,11 +1,11 @@
 //! This example demonstrates how to write a custom phase
 //!
-//! Render phases in bevy are used whenever you need to draw a groud of neshes in a specific way.
+//! Render phases in bevy are used whenever you need to draw a group of meshes in a specific way.
 //! For example, bevy's main pass has an opaque phase, a transparent phase for both 2d and 3d.
 //! Sometimes, you may want to only draw a subset of meshes before or after the builtin phase. In
 //! those situations you need to write your own phase.
 //!
-//! This examples showcase how writing a custom phase to draw a stencil of a bevy mesh could look
+//! This example showcases how writing a custom phase to draw a stencil of a bevy mesh could look
 //! like. Some shortcuts have been used for simplicity.
 //!
 //! This example was made for 3d, but a 2d equivalent would be almost identical.
@@ -246,7 +246,7 @@ type DrawMesh3dStencil = (
 
 // This is the data required when you define a custom phase in bevy. More specifically this is the
 // data required when using a ViewSortedRenderPhase. This would look differently if we wanted a
-// batched render phase. Sorted phase are a bit easier to implement, but a batched phased would
+// batched render phase. Sorted phases are a bit easier to implement, but a batched phased would
 // look similar.
 //
 // If you want to see how a batched phase implementation looks, you should look at the Opaque2d
@@ -453,7 +453,7 @@ fn extract_camera_phases(
 
 // This is a very important step when writing a custom phase.
 //
-// This system determines which mesh will be added to the phase.
+// This system determines which meshes will be added to the phase.
 #[allow(clippy::too_many_arguments)]
 fn queue_custom_meshes(
     custom_draw_functions: Res<DrawFunctions<StencilPhase>>,
@@ -478,7 +478,7 @@ fn queue_custom_meshes(
             | MeshPipelineKey::from_hdr(view.hdr);
 
         let rangefinder = view.rangefinder3d();
-        // Since our phase can work on any 3d mesh we can reuse the default mesh 2d filter
+        // Since our phase can work on any 3d mesh we can reuse the default mesh 3d filter
         for (render_entity, visible_entity) in visible_entities.iter::<Mesh3d>() {
             // We only want meshes with the marker component to be queued to our phase.
             if has_marker.get(*render_entity).is_err() {
@@ -549,13 +549,15 @@ impl ViewNode for CustomDrawNode {
         else {
             return Ok(());
         };
-        // Initiazlie diagnostic recording.
-        // not reguired but makes profiling easier
+        // Initialize diagnostic recording.
+        // not required but makes profiling easier
         let diagnostics = render_context.diagnostic_recorder();
 
         // For the purpose of the example, we will write directly to the view target. A real
         // stencil pass would write to a custom texture and that texture would be used in later
         // passes to render custom effects using it.
+        // Check out the prepass (ex: DepthPrepass) implementations in Bevy for additional
+        // context when using custom textures.
         let color_attachments = [Some(target.get_color_attachment())];
 
         // Get the view entity from the graph

From b4b2cdfad4033210ffa786a69629cfc243fdd19d Mon Sep 17 00:00:00 2001
From: Christopher Biscardi <chris@christopherbiscardi.com>
Date: Thu, 16 Jan 2025 09:44:10 -0800
Subject: [PATCH 10/17] add custom render phase to examples readme

---
 examples/README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/examples/README.md b/examples/README.md
index 5f51e2c38e660..e1519994696f0 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -421,6 +421,7 @@ Example | Description
 [Animated](../examples/shader/animate_shader.rs) | A shader that uses dynamic data like the time since startup
 [Array Texture](../examples/shader/array_texture.rs) | A shader that shows how to reuse the core bevy PBR shading functionality in a custom material that obtains the base color from an array texture.
 [Compute - Game of Life](../examples/shader/compute_shader_game_of_life.rs) | A compute shader that simulates Conway's Game of Life
+[Custom Render Phase](../examples/shader/custom_render_phase.rs) | Shows how to make a complete render phase
 [Custom Vertex Attribute](../examples/shader/custom_vertex_attribute.rs) | A shader that reads a mesh's custom vertex attribute
 [Custom phase item](../examples/shader/custom_phase_item.rs) | Demonstrates how to enqueue custom draw commands in a render phase
 [Extended Material](../examples/shader/extended_material.rs) | A custom shader that builds on the standard material

From 505df2f8a2a4f7b08770b7c071edf6a11c2cdf40 Mon Sep 17 00:00:00 2001
From: IceSentry <c.giguere42@gmail.com>
Date: Thu, 6 Feb 2025 20:29:48 -0500
Subject: [PATCH 11/17] wip docs

---
 examples/shader/custom_render_phase.rs | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/examples/shader/custom_render_phase.rs b/examples/shader/custom_render_phase.rs
index fd1fb1c57b02e..b6f70dc25a000 100644
--- a/examples/shader/custom_render_phase.rs
+++ b/examples/shader/custom_render_phase.rs
@@ -569,6 +569,7 @@ impl ViewNode for CustomDrawNode {
         };
 
         // This will generate a task to generate the command buffer in parallel
+        // This is not required but is generally recommended
         render_context.add_command_buffer_generation_task(move |render_device| {
             #[cfg(feature = "trace")]
             let _ = info_span!("custom_stencil_pass").entered();
@@ -582,7 +583,10 @@ impl ViewNode for CustomDrawNode {
             // Render pass setup
             let render_pass = command_encoder.begin_render_pass(&RenderPassDescriptor {
                 label: Some("stencil pass"),
-                color_attachments: &color_attachments,
+                // For the purpose of the example, we will write directly to the view target. A real
+                // stencil pass would write to a custom texture and that texture would be used in later
+                // passes to render custom effects using it.
+                color_attachments: &[Some(target.get_color_attachment())],
                 // We don't bind any depth buffer for this pass
                 depth_stencil_attachment: None,
                 timestamp_writes: None,
@@ -597,8 +601,9 @@ impl ViewNode for CustomDrawNode {
 
             // Render the phase
             if !stencil_phase.items.is_empty() {
+                // This will execute each draw functions of each phase items queued in this phase
                 if let Err(err) = stencil_phase.render(&mut render_pass, world, view_entity) {
-                    error!("Error encountered while rendering the custom phase {err:?}");
+                    error!("Error encountered while rendering the stencil phase {err:?}");
                 }
             }
 

From a3beefb9819b7765931f6f3d6a7ca09256f2a3a0 Mon Sep 17 00:00:00 2001
From: IceSentry <c.giguere42@gmail.com>
Date: Fri, 7 Feb 2025 15:50:50 -0500
Subject: [PATCH 12/17] update to main

---
 examples/shader/custom_render_phase.rs | 112 ++++++++++++++++---------
 1 file changed, 73 insertions(+), 39 deletions(-)

diff --git a/examples/shader/custom_render_phase.rs b/examples/shader/custom_render_phase.rs
index b6f70dc25a000..cfffc2bafdced 100644
--- a/examples/shader/custom_render_phase.rs
+++ b/examples/shader/custom_render_phase.rs
@@ -15,7 +15,6 @@ use std::ops::Range;
 use bevy::{
     core_pipeline::core_3d::graph::{Core3d, Node3d},
     ecs::{
-        entity::EntityHashSet,
         query::QueryItem,
         system::{lifetimeless::SRes, SystemParamItem},
     },
@@ -25,11 +24,12 @@ use bevy::{
         MeshPipelineKey, MeshPipelineViewLayoutKey, MeshUniform, RenderMeshInstances,
         SetMeshBindGroup, SetMeshViewBindGroup,
     },
+    platform_support::collections::HashSet,
     prelude::*,
     render::{
         batching::{
-            gpu_preprocessing::{batch_and_prepare_sorted_render_phase, IndirectParametersBuffer},
-            GetBatchData, GetFullBatchData,
+            gpu_preprocessing::batch_and_prepare_sorted_render_phase, GetBatchData,
+            GetFullBatchData,
         },
         camera::ExtractedCamera,
         diagnostic::RecordDiagnostics,
@@ -51,11 +51,14 @@ use bevy::{
             SpecializedMeshPipelineError, SpecializedMeshPipelines, TextureFormat, VertexState,
         },
         renderer::RenderContext,
-        sync_world::{MainEntity, RenderEntity},
+        sync_world::MainEntity,
         view::{ExtractedView, RenderVisibleEntities, ViewTarget},
         Extract, Render, RenderApp, RenderSet,
     },
 };
+use bevy_render::{
+    batching::gpu_preprocessing::IndirectParametersMetadata, view::RetainedViewEntity,
+};
 use nonmax::NonMaxU32;
 
 const SHADER_ASSET_PATH: &str = "shaders/custom_stencil.wgsl";
@@ -169,6 +172,7 @@ impl FromWorld for StencilPipeline {
         }
     }
 }
+
 // For more information on how SpecializedMeshPipeline work, please look at the
 // specialized_mesh_pipeline example
 impl SpecializedMeshPipeline for StencilPipeline {
@@ -258,6 +262,9 @@ struct StencilPhase {
     pub draw_function: DrawFunctionId,
     pub batch_range: Range<u32>,
     pub extra_index: PhaseItemExtraIndex,
+    /// Whether the mesh in question is indexed (uses an index buffer in
+    /// addition to its vertex buffer).
+    pub indexed: bool,
 }
 
 // For more information about writing a phase item, please look at the custom_phase_item example
@@ -313,6 +320,11 @@ impl SortedPhaseItem for StencilPhase {
         // Since it is not re-exported by bevy, we just use the std sort for the purpose of the example
         items.sort_by_key(SortedPhaseItem::sort_key);
     }
+
+    #[inline]
+    fn indexed(&self) -> bool {
+        self.indexed
+    }
 }
 
 impl CachedRenderPipelinePhaseItem for StencilPhase {
@@ -367,7 +379,7 @@ impl GetFullBatchData for StencilPipeline {
 
     fn get_index_and_compare_data(
         (mesh_instances, _, _): &SystemParamItem<Self::Param>,
-        (_entity, main_entity): (Entity, MainEntity),
+        main_entity: MainEntity,
     ) -> Option<(NonMaxU32, Option<Self::CompareData>)> {
         // This should only be called during GPU building.
         let RenderMeshInstances::GpuBuilding(ref mesh_instances) = **mesh_instances else {
@@ -388,7 +400,7 @@ impl GetFullBatchData for StencilPipeline {
 
     fn get_binned_batch_data(
         (mesh_instances, _render_assets, mesh_allocator): &SystemParamItem<Self::Param>,
-        (_entity, main_entity): (Entity, MainEntity),
+        main_entity: MainEntity,
     ) -> Option<Self::BufferData> {
         let RenderMeshInstances::CpuBuilding(ref mesh_instances) = **mesh_instances else {
             error!(
@@ -413,48 +425,72 @@ impl GetFullBatchData for StencilPipeline {
         ))
     }
 
-    // TODO
+    fn write_batch_indirect_parameters_metadata(
+        mesh_index: u32,
+        indexed: bool,
+        base_output_index: u32,
+        batch_set_index: Option<NonMaxU32>,
+        indirect_parameters_buffers: &mut bevy_render::batching::gpu_preprocessing::IndirectParametersBuffers,
+        indirect_parameters_offset: u32,
+    ) {
+        // Note that `IndirectParameters` covers both of these structures, even
+        // though they actually have distinct layouts. See the comment above that
+        // type for more information.
+        let indirect_parameters = IndirectParametersMetadata {
+            mesh_index,
+            base_output_index,
+            batch_set_index: match batch_set_index {
+                None => !0,
+                Some(batch_set_index) => u32::from(batch_set_index),
+            },
+            early_instance_count: 0,
+            late_instance_count: 0,
+        };
 
-    fn get_binned_index(
-        (_, _, _): &SystemParamItem<Self::Param>,
-        (_entity, _main_entity): (Entity, MainEntity),
-    ) -> Option<NonMaxU32> {
-        None
+        if indexed {
+            indirect_parameters_buffers
+                .set_indexed(indirect_parameters_offset, indirect_parameters);
+        } else {
+            indirect_parameters_buffers
+                .set_non_indexed(indirect_parameters_offset, indirect_parameters);
+        }
     }
 
-    fn get_batch_indirect_parameters_index(
-        (_, _, _): &SystemParamItem<Self::Param>,
-        _indirect_parameters_buffer: &mut IndirectParametersBuffer,
-        _entity: (Entity, MainEntity),
-        _instance_index: u32,
+    fn get_binned_index(
+        _param: &SystemParamItem<Self::Param>,
+        _query_item: MainEntity,
     ) -> Option<NonMaxU32> {
         None
     }
 }
-// When defining a custom phase, we need to extract it from the main world and add it to a resource
+
+// When defining a phase, we need to extract it from the main world and add it to a resource
 // that will be used by the render world. We need to give that resource all views that will use
 // that phase
 fn extract_camera_phases(
-    mut custom_phases: ResMut<ViewSortedRenderPhases<StencilPhase>>,
-    cameras: Extract<Query<(RenderEntity, &Camera), With<Camera3d>>>,
-    mut live_entities: Local<EntityHashSet>,
+    mut stencil_phases: ResMut<ViewSortedRenderPhases<StencilPhase>>,
+    cameras: Extract<Query<(Entity, &Camera), With<Camera3d>>>,
+    mut live_entities: Local<HashSet<RetainedViewEntity>>,
 ) {
     live_entities.clear();
-    for (entity, camera) in &cameras {
+    for (main_entity, camera) in &cameras {
         if !camera.is_active {
             continue;
         }
-        custom_phases.insert_or_clear(entity);
-        live_entities.insert(entity);
+        // This is the main camera, so we use the first subview index (0)
+        let retained_view_entity = RetainedViewEntity::new(main_entity.into(), None, 0);
+
+        stencil_phases.insert_or_clear(retained_view_entity);
+        live_entities.insert(retained_view_entity);
     }
+
     // Clear out all dead views.
-    custom_phases.retain(|camera_entity, _| live_entities.contains(camera_entity));
+    stencil_phases.retain(|camera_entity, _| live_entities.contains(camera_entity));
 }
 
 // This is a very important step when writing a custom phase.
 //
 // This system determines which meshes will be added to the phase.
-#[allow(clippy::too_many_arguments)]
 fn queue_custom_meshes(
     custom_draw_functions: Res<DrawFunctions<StencilPhase>>,
     mut pipelines: ResMut<SpecializedMeshPipelines<StencilPipeline>>,
@@ -463,11 +499,11 @@ fn queue_custom_meshes(
     render_meshes: Res<RenderAssets<RenderMesh>>,
     render_mesh_instances: Res<RenderMeshInstances>,
     mut custom_render_phases: ResMut<ViewSortedRenderPhases<StencilPhase>>,
-    mut views: Query<(Entity, &ExtractedView, &RenderVisibleEntities, &Msaa)>,
+    mut views: Query<(&ExtractedView, &RenderVisibleEntities, &Msaa)>,
     has_marker: Query<(), With<DrawStencil>>,
 ) {
-    for (view_entity, view, visible_entities, msaa) in &mut views {
-        let Some(custom_phase) = custom_render_phases.get_mut(&view_entity) else {
+    for (view, visible_entities, msaa) in &mut views {
+        let Some(custom_phase) = custom_render_phases.get_mut(&view.retained_view_entity) else {
             continue;
         };
         let draw_custom = custom_draw_functions.read().id::<DrawMesh3dStencil>();
@@ -523,6 +559,7 @@ fn queue_custom_meshes(
                 // Sorted phase items aren't batched
                 batch_range: 0..1,
                 extra_index: PhaseItemExtraIndex::None,
+                indexed: mesh.indexed(),
             });
         }
     }
@@ -535,13 +572,17 @@ struct CustomDrawPassLabel;
 #[derive(Default)]
 struct CustomDrawNode;
 impl ViewNode for CustomDrawNode {
-    type ViewQuery = (&'static ExtractedCamera, &'static ViewTarget);
+    type ViewQuery = (
+        &'static ExtractedCamera,
+        &'static ExtractedView,
+        &'static ViewTarget,
+    );
 
     fn run<'w>(
         &self,
         graph: &mut RenderGraphContext,
         render_context: &mut RenderContext<'w>,
-        (camera, target): QueryItem<'w, Self::ViewQuery>,
+        (camera, view, target): QueryItem<'w, Self::ViewQuery>,
         world: &'w World,
     ) -> Result<(), NodeRunError> {
         // First, we need to get ou phases resource
@@ -553,18 +594,11 @@ impl ViewNode for CustomDrawNode {
         // not required but makes profiling easier
         let diagnostics = render_context.diagnostic_recorder();
 
-        // For the purpose of the example, we will write directly to the view target. A real
-        // stencil pass would write to a custom texture and that texture would be used in later
-        // passes to render custom effects using it.
-        // Check out the prepass (ex: DepthPrepass) implementations in Bevy for additional
-        // context when using custom textures.
-        let color_attachments = [Some(target.get_color_attachment())];
-
         // Get the view entity from the graph
         let view_entity = graph.view_entity();
 
         // Get the phase for the current view running our node
-        let Some(stencil_phase) = stencil_phases.get(&view_entity) else {
+        let Some(stencil_phase) = stencil_phases.get(&view.retained_view_entity) else {
             return Ok(());
         };
 

From 66a5294c2cafa8f6e1cec4efdc5545456dcdb326 Mon Sep 17 00:00:00 2001
From: IceSentry <c.giguere42@gmail.com>
Date: Fri, 7 Feb 2025 16:02:02 -0500
Subject: [PATCH 13/17] fix typo

---
 examples/shader/custom_render_phase.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/shader/custom_render_phase.rs b/examples/shader/custom_render_phase.rs
index cfffc2bafdced..9eed83d32fdd8 100644
--- a/examples/shader/custom_render_phase.rs
+++ b/examples/shader/custom_render_phase.rs
@@ -148,7 +148,7 @@ impl Plugin for MeshStencilPhasePlugin {
             return;
         };
         // The pipeline needs the RenderDevice to be created and it's only available once plugins
-        // are intialized
+        // are initialized
         render_app.init_resource::<StencilPipeline>();
     }
 }

From 36d6330c94356f05585fbfa499fd25d865f3cdb8 Mon Sep 17 00:00:00 2001
From: IceSentry <c.giguere42@gmail.com>
Date: Fri, 7 Feb 2025 16:03:42 -0500
Subject: [PATCH 14/17] fix internal import

---
 examples/shader/custom_render_phase.rs | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/examples/shader/custom_render_phase.rs b/examples/shader/custom_render_phase.rs
index 9eed83d32fdd8..f6dbf96de35f4 100644
--- a/examples/shader/custom_render_phase.rs
+++ b/examples/shader/custom_render_phase.rs
@@ -28,8 +28,10 @@ use bevy::{
     prelude::*,
     render::{
         batching::{
-            gpu_preprocessing::batch_and_prepare_sorted_render_phase, GetBatchData,
-            GetFullBatchData,
+            gpu_preprocessing::{
+                batch_and_prepare_sorted_render_phase, IndirectParametersMetadata,
+            },
+            GetBatchData, GetFullBatchData,
         },
         camera::ExtractedCamera,
         diagnostic::RecordDiagnostics,
@@ -52,13 +54,10 @@ use bevy::{
         },
         renderer::RenderContext,
         sync_world::MainEntity,
-        view::{ExtractedView, RenderVisibleEntities, ViewTarget},
+        view::{ExtractedView, RenderVisibleEntities, RetainedViewEntity, ViewTarget},
         Extract, Render, RenderApp, RenderSet,
     },
 };
-use bevy_render::{
-    batching::gpu_preprocessing::IndirectParametersMetadata, view::RetainedViewEntity,
-};
 use nonmax::NonMaxU32;
 
 const SHADER_ASSET_PATH: &str = "shaders/custom_stencil.wgsl";

From 930277c624f981e8c5f0c9d365beb7b5f6b3700e Mon Sep 17 00:00:00 2001
From: IceSentry <c.giguere42@gmail.com>
Date: Fri, 7 Feb 2025 16:33:26 -0500
Subject: [PATCH 15/17] remove unnecessary pub

---
 crates/bevy_pbr/src/lib.rs             |  2 +-
 examples/shader/custom_render_phase.rs | 33 +++++++++++++++-----------
 2 files changed, 20 insertions(+), 15 deletions(-)

diff --git a/crates/bevy_pbr/src/lib.rs b/crates/bevy_pbr/src/lib.rs
index c2c513de93b75..88403900aeedb 100644
--- a/crates/bevy_pbr/src/lib.rs
+++ b/crates/bevy_pbr/src/lib.rs
@@ -35,7 +35,7 @@ mod light;
 mod light_probe;
 mod lightmap;
 mod material;
-pub mod material_bind_groups;
+mod material_bind_groups;
 mod mesh_material;
 mod parallax;
 mod pbr_material;
diff --git a/examples/shader/custom_render_phase.rs b/examples/shader/custom_render_phase.rs
index f6dbf96de35f4..1107a2665461e 100644
--- a/examples/shader/custom_render_phase.rs
+++ b/examples/shader/custom_render_phase.rs
@@ -20,9 +20,8 @@ use bevy::{
     },
     math::FloatOrd,
     pbr::{
-        material_bind_groups::MaterialBindGroupSlot, DrawMesh, MeshInputUniform, MeshPipeline,
-        MeshPipelineKey, MeshPipelineViewLayoutKey, MeshUniform, RenderMeshInstances,
-        SetMeshBindGroup, SetMeshViewBindGroup,
+        DrawMesh, MeshInputUniform, MeshPipeline, MeshPipelineKey, MeshPipelineViewLayoutKey,
+        MeshUniform, RenderMeshInstances, SetMeshBindGroup, SetMeshViewBindGroup,
     },
     platform_support::collections::HashSet,
     prelude::*,
@@ -359,18 +358,24 @@ impl GetBatchData for StencilPipeline {
                 Some(mesh_vertex_slice) => mesh_vertex_slice.range.start,
                 None => 0,
             };
-        Some((
-            MeshUniform::new(
-                &mesh_instance.transforms,
+        let mesh_uniform = {
+            let mesh_transforms = &mesh_instance.transforms;
+            let (local_from_world_transpose_a, local_from_world_transpose_b) =
+                mesh_transforms.world_from_local.inverse_transpose_3x3();
+            MeshUniform {
+                world_from_local: mesh_transforms.world_from_local.to_transpose(),
+                previous_world_from_local: mesh_transforms.previous_world_from_local.to_transpose(),
+                lightmap_uv_rect: UVec2::ZERO,
+                local_from_world_transpose_a,
+                local_from_world_transpose_b,
+                flags: mesh_transforms.flags,
                 first_vertex_index,
-                // TODO don't hardcode this
-                MaterialBindGroupSlot(0),
-                None,
-                None,
-                None,
-            ),
-            None,
-        ))
+                current_skin_index: u32::MAX,
+                previous_skin_index: u32::MAX,
+                material_and_lightmap_bind_group_slot: 0,
+            }
+        };
+        Some((mesh_uniform, None))
     }
 }
 impl GetFullBatchData for StencilPipeline {

From 8d24684c7bd44d5df619909173bc337c84fc596a Mon Sep 17 00:00:00 2001
From: IceSentry <c.giguere42@gmail.com>
Date: Fri, 7 Feb 2025 16:45:08 -0500
Subject: [PATCH 16/17] simplify node

---
 examples/shader/custom_render_phase.rs | 77 +++++++++-----------------
 1 file changed, 26 insertions(+), 51 deletions(-)

diff --git a/examples/shader/custom_render_phase.rs b/examples/shader/custom_render_phase.rs
index 1107a2665461e..dc230ed3fd2c1 100644
--- a/examples/shader/custom_render_phase.rs
+++ b/examples/shader/custom_render_phase.rs
@@ -33,7 +33,6 @@ use bevy::{
             GetBatchData, GetFullBatchData,
         },
         camera::ExtractedCamera,
-        diagnostic::RecordDiagnostics,
         extract_component::{ExtractComponent, ExtractComponentPlugin},
         mesh::{allocator::MeshAllocator, MeshVertexBufferLayoutRef, RenderMesh},
         render_asset::RenderAssets,
@@ -43,13 +42,13 @@ use bevy::{
         render_phase::{
             sort_phase_system, AddRenderCommand, CachedRenderPipelinePhaseItem, DrawFunctionId,
             DrawFunctions, PhaseItem, PhaseItemExtraIndex, SetItemPipeline, SortedPhaseItem,
-            TrackedRenderPass, ViewSortedRenderPhases,
+            ViewSortedRenderPhases,
         },
         render_resource::{
-            CachedRenderPipelineId, ColorTargetState, ColorWrites, CommandEncoderDescriptor, Face,
-            FragmentState, FrontFace, MultisampleState, PipelineCache, PolygonMode, PrimitiveState,
-            RenderPassDescriptor, RenderPipelineDescriptor, SpecializedMeshPipeline,
-            SpecializedMeshPipelineError, SpecializedMeshPipelines, TextureFormat, VertexState,
+            CachedRenderPipelineId, ColorTargetState, ColorWrites, Face, FragmentState, FrontFace,
+            MultisampleState, PipelineCache, PolygonMode, PrimitiveState, RenderPassDescriptor,
+            RenderPipelineDescriptor, SpecializedMeshPipeline, SpecializedMeshPipelineError,
+            SpecializedMeshPipelines, TextureFormat, VertexState,
         },
         renderer::RenderContext,
         sync_world::MainEntity,
@@ -589,14 +588,11 @@ impl ViewNode for CustomDrawNode {
         (camera, view, target): QueryItem<'w, Self::ViewQuery>,
         world: &'w World,
     ) -> Result<(), NodeRunError> {
-        // First, we need to get ou phases resource
+        // First, we need to get our phases resource
         let Some(stencil_phases) = world.get_resource::<ViewSortedRenderPhases<StencilPhase>>()
         else {
             return Ok(());
         };
-        // Initialize diagnostic recording.
-        // not required but makes profiling easier
-        let diagnostics = render_context.diagnostic_recorder();
 
         // Get the view entity from the graph
         let view_entity = graph.view_entity();
@@ -606,49 +602,28 @@ impl ViewNode for CustomDrawNode {
             return Ok(());
         };
 
-        // This will generate a task to generate the command buffer in parallel
-        // This is not required but is generally recommended
-        render_context.add_command_buffer_generation_task(move |render_device| {
-            #[cfg(feature = "trace")]
-            let _ = info_span!("custom_stencil_pass").entered();
-
-            // Command encoder setup
-            let mut command_encoder =
-                render_device.create_command_encoder(&CommandEncoderDescriptor {
-                    label: Some("custom stencil pass encoder"),
-                });
-
-            // Render pass setup
-            let render_pass = command_encoder.begin_render_pass(&RenderPassDescriptor {
-                label: Some("stencil pass"),
-                // For the purpose of the example, we will write directly to the view target. A real
-                // stencil pass would write to a custom texture and that texture would be used in later
-                // passes to render custom effects using it.
-                color_attachments: &[Some(target.get_color_attachment())],
-                // We don't bind any depth buffer for this pass
-                depth_stencil_attachment: None,
-                timestamp_writes: None,
-                occlusion_query_set: None,
-            });
-            let mut render_pass = TrackedRenderPass::new(&render_device, render_pass);
-            let pass_span = diagnostics.pass_span(&mut render_pass, "custom_pass");
-
-            if let Some(viewport) = camera.viewport.as_ref() {
-                render_pass.set_camera_viewport(viewport);
-            }
+        // Render pass setup
+        let mut render_pass = render_context.begin_tracked_render_pass(RenderPassDescriptor {
+            label: Some("stencil pass"),
+            // For the purpose of the example, we will write directly to the view target. A real
+            // stencil pass would write to a custom texture and that texture would be used in later
+            // passes to render custom effects using it.
+            color_attachments: &[Some(target.get_color_attachment())],
+            // We don't bind any depth buffer for this pass
+            depth_stencil_attachment: None,
+            timestamp_writes: None,
+            occlusion_query_set: None,
+        });
 
-            // Render the phase
-            if !stencil_phase.items.is_empty() {
-                // This will execute each draw functions of each phase items queued in this phase
-                if let Err(err) = stencil_phase.render(&mut render_pass, world, view_entity) {
-                    error!("Error encountered while rendering the stencil phase {err:?}");
-                }
-            }
+        if let Some(viewport) = camera.viewport.as_ref() {
+            render_pass.set_camera_viewport(viewport);
+        }
 
-            pass_span.end(&mut render_pass);
-            drop(render_pass);
-            command_encoder.finish()
-        });
+        // Render the phase
+        // This will execute each draw functions of each phase items queued in this phase
+        if let Err(err) = stencil_phase.render(&mut render_pass, world, view_entity) {
+            error!("Error encountered while rendering the stencil phase {err:?}");
+        }
 
         Ok(())
     }

From a499468f7d291e0a6f645bb08dff011bfa7c3be9 Mon Sep 17 00:00:00 2001
From: IceSentry <c.giguere42@gmail.com>
Date: Sat, 8 Feb 2025 14:04:52 -0500
Subject: [PATCH 17/17] minor clean ups

---
 examples/shader/custom_render_phase.rs | 35 +++++++++++++-------------
 1 file changed, 17 insertions(+), 18 deletions(-)

diff --git a/examples/shader/custom_render_phase.rs b/examples/shader/custom_render_phase.rs
index dc230ed3fd2c1..4fbf105fe9d56 100644
--- a/examples/shader/custom_render_phase.rs
+++ b/examples/shader/custom_render_phase.rs
@@ -119,17 +119,17 @@ impl Plugin for MeshStencilPhasePlugin {
         };
         render_app
             .init_resource::<SpecializedMeshPipelines<StencilPipeline>>()
-            .init_resource::<DrawFunctions<StencilPhase>>()
-            .add_render_command::<StencilPhase, DrawMesh3dStencil>()
-            .init_resource::<ViewSortedRenderPhases<StencilPhase>>()
+            .init_resource::<DrawFunctions<Stencil3d>>()
+            .add_render_command::<Stencil3d, DrawMesh3dStencil>()
+            .init_resource::<ViewSortedRenderPhases<Stencil3d>>()
             .add_systems(ExtractSchedule, extract_camera_phases)
             .add_systems(
                 Render,
                 (
-                    sort_phase_system::<StencilPhase>.in_set(RenderSet::PhaseSort),
-                    batch_and_prepare_sorted_render_phase::<StencilPhase, StencilPipeline>
-                        .in_set(RenderSet::PrepareResources),
                     queue_custom_meshes.in_set(RenderSet::QueueMeshes),
+                    sort_phase_system::<Stencil3d>.in_set(RenderSet::PhaseSort),
+                    batch_and_prepare_sorted_render_phase::<Stencil3d, StencilPipeline>
+                        .in_set(RenderSet::PrepareResources),
                 ),
             );
 
@@ -245,14 +245,14 @@ type DrawMesh3dStencil = (
     DrawMesh,
 );
 
-// This is the data required when you define a custom phase in bevy. More specifically this is the
+// This is the data required per entity drawn in a custom phase in bevy. More specifically this is the
 // data required when using a ViewSortedRenderPhase. This would look differently if we wanted a
-// batched render phase. Sorted phases are a bit easier to implement, but a batched phased would
+// batched render phase. Sorted phases are a bit easier to implement, but a batched phase would
 // look similar.
 //
 // If you want to see how a batched phase implementation looks, you should look at the Opaque2d
 // phase.
-struct StencilPhase {
+struct Stencil3d {
     pub sort_key: FloatOrd,
     pub entity: (Entity, MainEntity),
     pub pipeline: CachedRenderPipelineId,
@@ -265,7 +265,7 @@ struct StencilPhase {
 }
 
 // For more information about writing a phase item, please look at the custom_phase_item example
-impl PhaseItem for StencilPhase {
+impl PhaseItem for Stencil3d {
     #[inline]
     fn entity(&self) -> Entity {
         self.entity.0
@@ -302,7 +302,7 @@ impl PhaseItem for StencilPhase {
     }
 }
 
-impl SortedPhaseItem for StencilPhase {
+impl SortedPhaseItem for Stencil3d {
     type SortKey = FloatOrd;
 
     #[inline]
@@ -324,7 +324,7 @@ impl SortedPhaseItem for StencilPhase {
     }
 }
 
-impl CachedRenderPipelinePhaseItem for StencilPhase {
+impl CachedRenderPipelinePhaseItem for Stencil3d {
     #[inline]
     fn cached_pipeline(&self) -> CachedRenderPipelineId {
         self.pipeline
@@ -471,7 +471,7 @@ impl GetFullBatchData for StencilPipeline {
 // that will be used by the render world. We need to give that resource all views that will use
 // that phase
 fn extract_camera_phases(
-    mut stencil_phases: ResMut<ViewSortedRenderPhases<StencilPhase>>,
+    mut stencil_phases: ResMut<ViewSortedRenderPhases<Stencil3d>>,
     cameras: Extract<Query<(Entity, &Camera), With<Camera3d>>>,
     mut live_entities: Local<HashSet<RetainedViewEntity>>,
 ) {
@@ -495,13 +495,13 @@ fn extract_camera_phases(
 //
 // This system determines which meshes will be added to the phase.
 fn queue_custom_meshes(
-    custom_draw_functions: Res<DrawFunctions<StencilPhase>>,
+    custom_draw_functions: Res<DrawFunctions<Stencil3d>>,
     mut pipelines: ResMut<SpecializedMeshPipelines<StencilPipeline>>,
     pipeline_cache: Res<PipelineCache>,
     custom_draw_pipeline: Res<StencilPipeline>,
     render_meshes: Res<RenderAssets<RenderMesh>>,
     render_mesh_instances: Res<RenderMeshInstances>,
-    mut custom_render_phases: ResMut<ViewSortedRenderPhases<StencilPhase>>,
+    mut custom_render_phases: ResMut<ViewSortedRenderPhases<Stencil3d>>,
     mut views: Query<(&ExtractedView, &RenderVisibleEntities, &Msaa)>,
     has_marker: Query<(), With<DrawStencil>>,
 ) {
@@ -553,7 +553,7 @@ fn queue_custom_meshes(
             let distance = rangefinder.distance_translation(&mesh_instance.translation);
             // At this point we have all the data we need to create a phase item and add it to our
             // phase
-            custom_phase.add(StencilPhase {
+            custom_phase.add(Stencil3d {
                 // Sort the data based on the distance to the view
                 sort_key: FloatOrd(distance),
                 entity: (*render_entity, *visible_entity),
@@ -589,8 +589,7 @@ impl ViewNode for CustomDrawNode {
         world: &'w World,
     ) -> Result<(), NodeRunError> {
         // First, we need to get our phases resource
-        let Some(stencil_phases) = world.get_resource::<ViewSortedRenderPhases<StencilPhase>>()
-        else {
+        let Some(stencil_phases) = world.get_resource::<ViewSortedRenderPhases<Stencil3d>>() else {
             return Ok(());
         };