automatic_instancing/
automatic_instancing.rs

1//! Shows that multiple instances of a cube are automatically instanced in one draw call
2//! Try running this example in a graphics profiler and all the cubes should be only a single draw call.
3//! Also demonstrates how to use `MeshTag` to use external data in a custom material.
4
5use bevy::{
6    prelude::*,
7    reflect::TypePath,
8    render::{
9        mesh::MeshTag,
10        render_resource::{AsBindGroup, ShaderRef},
11    },
12};
13
14const SHADER_ASSET_PATH: &str = "shaders/automatic_instancing.wgsl";
15
16fn main() {
17    App::new()
18        .add_plugins((DefaultPlugins, MaterialPlugin::<CustomMaterial>::default()))
19        .add_systems(Startup, setup)
20        .add_systems(Update, update)
21        .run();
22}
23
24/// Sets up an instanced grid of cubes, where each cube is colored based on an image that is
25/// sampled in the vertex shader. The cubes are then animated in a spiral pattern.
26///
27/// This example demonstrates one use of automatic instancing and how to use `MeshTag` to use
28/// external data in a custom material. For example, here we use the "index" of each cube to
29/// determine the texel coordinate to sample from the image in the shader.
30fn setup(
31    mut commands: Commands,
32    assets: Res<AssetServer>,
33    mut meshes: ResMut<Assets<Mesh>>,
34    mut materials: ResMut<Assets<CustomMaterial>>,
35) {
36    // We will use this image as our external data for our material to sample from in the vertex shader
37    let image = assets.load("branding/icon.png");
38
39    // Our single mesh handle that will be instanced
40    let mesh_handle = meshes.add(Cuboid::from_size(Vec3::splat(0.01)));
41
42    // Create the custom material with a reference to our texture
43    // Automatic instancing works with any Material, including the `StandardMaterial`.
44    // This custom material is used to demonstrate the optional `MeshTag` feature.
45    let material_handle = materials.add(CustomMaterial {
46        image: image.clone(),
47    });
48
49    // We're hardcoding the image dimensions for simplicity
50    let image_dims = UVec2::new(256, 256);
51    let total_pixels = image_dims.x * image_dims.y;
52
53    for index in 0..total_pixels {
54        // Get x,y from index - x goes left to right, y goes top to bottom
55        let x = index % image_dims.x;
56        let y = index / image_dims.x;
57
58        // Convert to centered world coordinates
59        let world_x = (x as f32 - image_dims.x as f32 / 2.0) / 50.0;
60        let world_y = -((y as f32 - image_dims.y as f32 / 2.0) / 50.0); // Still need negative for world space
61
62        commands.spawn((
63            // For automatic instancing to take effect you need to
64            // use the same mesh handle and material handle for each instance
65            Mesh3d(mesh_handle.clone()),
66            MeshMaterial3d(material_handle.clone()),
67            // This is an optional component that can be used to help tie external data to a mesh instance
68            MeshTag(index),
69            Transform::from_xyz(world_x, world_y, 0.0),
70        ));
71    }
72
73    // Camera
74    commands.spawn((
75        Camera3d::default(),
76        Transform::from_xyz(0.0, 0.0, 5.0).looking_at(Vec3::ZERO, Vec3::Y),
77    ));
78}
79
80// Animate the transform
81fn update(time: Res<Time>, mut transforms: Query<(&mut Transform, &MeshTag)>) {
82    for (mut transform, index) in transforms.iter_mut() {
83        // Animate the z position based on time using the index to create a spiral
84        transform.translation.z = ops::sin(time.elapsed_secs() + index.0 as f32 * 0.01);
85    }
86}
87
88// This struct defines the data that will be passed to your shader
89#[derive(Asset, TypePath, AsBindGroup, Debug, Clone)]
90struct CustomMaterial {
91    #[texture(0)]
92    #[sampler(1)]
93    image: Handle<Image>,
94}
95
96impl Material for CustomMaterial {
97    fn vertex_shader() -> ShaderRef {
98        SHADER_ASSET_PATH.into()
99    }
100
101    fn fragment_shader() -> ShaderRef {
102        SHADER_ASSET_PATH.into()
103    }
104}
automatic_instancing/automatic_instancing.rs

automatic_instancing/
automatic_instancing.rs
