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

automatic_instancing/
automatic_instancing.rs
