Add a custom render phase example (#16916)

# Objective

- It's currently very hard for beginners and advanced users to get a
full understanding of a complete render phase.

## Solution

- Implement a full custom render phase
- The render phase in the example is intended to show a custom stencil
phase that renders the stencil in red directly on the screen

---

## Showcase

<img width="1277" alt="image"
src="https://github.com/user-attachments/assets/e9dc0105-4fb6-463f-ad53-0529b575fd28"
/>

## Notes

More docs to explain what is going on is still needed but the example
works and can already help some people.

We might want to consider using a batched phase and cold specialization
in the future, but the example is already complex enough as it is.

---------

Co-authored-by: Christopher Biscardi <[email protected]>

Author: IceSentry

Cargo.toml

@@ -518,6 +518,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"
@@ -2728,6 +2729,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"

assets/shaders/custom_stencil.wgsl

@@ -0,0 +1,41 @@
+//! 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
+#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. 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);
+    return out;
+}
+
+@fragment
+fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
+    // Output a red color to represent the stencil of the mesh
+    return vec4(1.0, 0.0, 0.0, 1.0);
+}

examples/README.md

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