Clarify purpose of shader_instancing example (#15456)

# Objective

- The shader_instancing example can be misleading since it doesn't
explain that bevy has built in automatic instancing.

## Solution

- Explain that bevy has built in instancing and that this example is for
advanced users.
- Add a new automatic_instancing example that shows how to use the built
in automatic instancing
- Rename the shader_instancing example to custom_shader_instancing to
highlight that this is a more advanced implementation

---------

Co-authored-by: JMS55 <47158642+JMS55@users.noreply.github.com>

Cargo.toml

@@ -2467,13 +2467,24 @@ category = "Shaders"
 wasm = true
 
 [[example]]
-name = "shader_instancing"
-path = "examples/shader/shader_instancing.rs"
+name = "custom_shader_instancing"
+path = "examples/shader/custom_shader_instancing.rs"
 doc-scrape-examples = true
 
-[package.metadata.example.shader_instancing]
+[package.metadata.example.custom_shader_instancing]
 name = "Instancing"
-description = "A shader that renders a mesh multiple times in one draw call"
+description = "A shader that renders a mesh multiple times in one draw call using low level rendering api"
+category = "Shaders"
+wasm = true
+
+[[example]]
+name = "automatic_instancing"
+path = "examples/shader/automatic_instancing.rs"
+doc-scrape-examples = true
+
+[package.metadata.example.automatic_instancing]
+name = "Instancing"
+description = "Shows that multiple instances of a cube are automatically instanced in one draw call"
 category = "Shaders"
 wasm = true
 

examples/README.md

@@ -412,7 +412,8 @@ Example | Description
 [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
 [GPU readback](../examples/shader/gpu_readback.rs) | A very simple compute shader that writes to a buffer that is read by the cpu
-[Instancing](../examples/shader/shader_instancing.rs) | A shader that renders a mesh multiple times in one draw call
+[Instancing](../examples/shader/custom_shader_instancing.rs) | A shader that renders a mesh multiple times in one draw call using low level rendering api
+[Instancing](../examples/shader/automatic_instancing.rs) | Shows that multiple instances of a cube are automatically instanced in one draw call
 [Material](../examples/shader/shader_material.rs) | A shader and a material that uses it
 [Material](../examples/shader/shader_material_2d.rs) | A shader and a material that uses it on a 2d mesh
 [Material - GLSL](../examples/shader/shader_material_glsl.rs) | A shader that uses the GLSL shading language

examples/shader/automatic_instancing.rs

@@ -0,0 +1,53 @@
+//! Shows that multiple instances of a cube are automatically instanced in one draw call
+//! Try running this example in a graphics profiler and all the cubes should be only a single draw call.
+
+use bevy::prelude::*;
+
+fn main() {
+    App::new()
+        .add_plugins(DefaultPlugins)
+        .add_systems(Startup, setup)
+        .run();
+}
+
+/// set up a simple 3D scene
+fn setup(
+    mut commands: Commands,
+    mut meshes: ResMut<Assets<Mesh>>,
+    mut materials: ResMut<Assets<StandardMaterial>>,
+) {
+    // camera
+    commands.spawn(Camera3dBundle {
+        transform: Transform::from_xyz(0.0, 8.0, 20.0).looking_at(Vec3::ZERO, Vec3::Y),
+        ..default()
+    });
+    // light
+    commands.spawn(PointLightBundle {
+        point_light: PointLight {
+            shadows_enabled: true,
+            ..default()
+        },
+        transform: Transform::from_xyz(0.0, 16.0, 8.0),
+        ..default()
+    });
+
+    let mesh = meshes.add(Cuboid::from_size(Vec3::splat(0.5)));
+    // This example uses the StandardMaterial but it can work with most custom material too
+    let material = materials.add(Color::srgb_u8(124, 144, 255));
+
+    // spawn 1000 cubes
+    for x in -5..5 {
+        for y in -5..5 {
+            for z in -5..5 {
+                commands.spawn(PbrBundle {
+                    // For automatic instancing to take effect you need to
+                    // use the same mesh handle and material handle for each instance
+                    mesh: mesh.clone(),
+                    material: material.clone(),
+                    transform: Transform::from_xyz(x as f32, y as f32, z as f32),
+                    ..default()
+                });
+            }
+        }
+    }
+}

examples/shader/custom_shader_instancing.rs

@@ -1,4 +1,11 @@
 //! A shader that renders a mesh multiple times in one draw call.
+//!
+//! Bevy will automatically batch and instance your meshes assuming you use the same
+//! `Handle<Material>` and `Handle<Mesh>` for all of your instances.
+//!
+//! This example is intended for advanced users and shows how to make a custom instancing
+//! implementation using bevy's low level rendering api.
+//! It's generally recommended to try the built-in instancing before going with this approach.
 
 use bevy::{
     core_pipeline::core_3d::Transparent3d,