Struct MeshAllocator 

pub struct MeshAllocator { /* private fields */ }

Manages the assignment of mesh data to GPU buffers.

The Bevy renderer tries to pack vertex and index data for multiple meshes together so that multiple meshes can be drawn back-to-back without any rebinding. This resource manages these buffers.

The MeshAllocatorSettings allows you to tune the behavior of the allocator for better performance with your use case. Most applications won’t need to change the settings from their default values.

Implementations

impl MeshAllocator

pub fn mesh_vertex_slice( &self, mesh_id: &AssetId<Mesh>, ) -> Option<SlabAllocationBufferSlice<'_, MeshSlabItem>>

Returns the buffer and range within that buffer of the vertex data for the mesh with the given ID.

If the mesh wasn’t allocated, returns None.

Examples found in repository

examples/shader_advanced/custom_render_phase.rs (line 379)

    fn get_batch_data(
        (mesh_instances, _render_assets, mesh_allocator): &SystemParamItem<Self::Param>,
        (_entity, main_entity): (Entity, MainEntity),
    ) -> Option<(
        Self::BufferData,
        Option<(Self::BatchSetCompareData, Self::BatchCompareData)>,
    )> {
        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,
            };
        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,
                current_skin_index: u32::MAX,
                material_and_lightmap_bind_group_slot: 0,
                tag: 0,
                morph_descriptor_index: u32::MAX,
            }
        };
        Some((mesh_uniform, None))
    }
}

impl GetFullBatchData for StencilPipeline {
    type BufferInputData = MeshInputUniform;

    fn get_index_and_compare_data(
        (mesh_instances, _, _): &SystemParamItem<Self::Param>,
        main_entity: MainEntity,
    ) -> Option<(
        NonMaxU32,
        Option<(Self::BatchSetCompareData, Self::BatchCompareData)>,
    )> {
        // 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((
            NonMaxU32::new(mesh_instance.gpu_specific.current_uniform_index())?,
            mesh_instance
                .should_batch()
                .then_some((mesh_instance.mesh_asset_id(), ())),
        ))
    }

    fn get_binned_batch_data(
        (mesh_instances, _render_assets, mesh_allocator): &SystemParamItem<Self::Param>,
        main_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,
            None,
        ))
    }

examples/shader_advanced/custom_shader_instancing.rs (line 322)

    fn render<'w>(
        item: &P,
        _view: (),
        instance_buffer: Option<&'w InstanceBuffer>,
        (meshes, render_mesh_instances, mesh_allocator): SystemParamItem<'w, '_, Self::Param>,
        pass: &mut TrackedRenderPass<'w>,
    ) -> RenderCommandResult {
        // A borrow check workaround.
        let mesh_allocator = mesh_allocator.into_inner();

        let Some(mesh_instance) = render_mesh_instances.render_mesh_queue_data(item.main_entity())
        else {
            return RenderCommandResult::Skip;
        };
        let Some(gpu_mesh) = meshes.into_inner().get(mesh_instance.mesh_asset_id()) else {
            return RenderCommandResult::Skip;
        };
        let Some(instance_buffer) = instance_buffer else {
            return RenderCommandResult::Skip;
        };
        let Some(vertex_buffer_slice) =
            mesh_allocator.mesh_vertex_slice(&mesh_instance.mesh_asset_id())
        else {
            return RenderCommandResult::Skip;
        };

        pass.set_vertex_buffer(0, vertex_buffer_slice.buffer.slice(..));
        pass.set_vertex_buffer(1, instance_buffer.buffer.slice(..));

        match &gpu_mesh.buffer_info {
            RenderMeshBufferInfo::Indexed {
                index_format,
                count,
            } => {
                let Some(index_buffer_slice) =
                    mesh_allocator.mesh_index_slice(&mesh_instance.mesh_asset_id())
                else {
                    return RenderCommandResult::Skip;
                };

                pass.set_index_buffer(index_buffer_slice.buffer.slice(..), *index_format);
                pass.draw_indexed(
                    index_buffer_slice.range.start..(index_buffer_slice.range.start + count),
                    vertex_buffer_slice.range.start as i32,
                    0..instance_buffer.length as u32,
                );
            }
            RenderMeshBufferInfo::NonIndexed => {
                pass.draw(vertex_buffer_slice.range, 0..instance_buffer.length as u32);
            }
        }
        RenderCommandResult::Success
    }

examples/shader_advanced/compute_mesh.rs (line 272)

fn compute_mesh(
    mut render_context: RenderContext,
    chunks: Res<ChunksToProcess>,
    mesh_allocator: Res<MeshAllocator>,
    pipeline_cache: Res<PipelineCache>,
    pipeline: Res<ComputePipeline>,
    render_queue: Res<RenderQueue>,
) {
    let Some(init_pipeline) = pipeline_cache.get_compute_pipeline(pipeline.pipeline) else {
        return;
    };

    for mesh_id in &chunks.0 {
        info!(?mesh_id, "processing mesh");

        // the mesh_allocator holds slabs of meshes, so the buffers we get here
        // can contain more data than just the mesh we're asking for.
        // That's why there is a range field.
        // You should *not* touch data in these buffers that is outside of the range.
        let vertex_buffer_slice = mesh_allocator.mesh_vertex_slice(mesh_id).unwrap();
        let index_buffer_slice = mesh_allocator.mesh_index_slice(mesh_id).unwrap();

        let first = DataRanges {
            // there are 8 vertex data values (pos, normal, uv) per vertex
            // and the vertex_buffer_slice.range.start is in "vertex elements"
            // which includes all of that data, so each index is worth 8 indices
            // to our shader code.
            vertex_start: vertex_buffer_slice.range.start * 8,
            vertex_end: vertex_buffer_slice.range.end * 8,
            // but each vertex index is a single value, so the index of the
            // vertex indices is exactly what the value is
            index_start: index_buffer_slice.range.start,
            index_end: index_buffer_slice.range.end,
        };

        let mut uniforms = UniformBuffer::from(first);
        uniforms.write_buffer(render_context.render_device(), &render_queue);

        // pass in the full mesh_allocator slabs as well as the first index
        // offsets for the vertex and index buffers
        let bind_group = render_context.render_device().create_bind_group(
            None,
            &pipeline_cache.get_bind_group_layout(&pipeline.layout),
            &BindGroupEntries::sequential((
                &uniforms,
                vertex_buffer_slice.buffer.as_entire_buffer_binding(),
                index_buffer_slice.buffer.as_entire_buffer_binding(),
            )),
        );

        let mut pass =
            render_context
                .command_encoder()
                .begin_compute_pass(&ComputePassDescriptor {
                    label: Some("Mesh generation compute pass"),
                    ..default()
                });
        pass.push_debug_group("compute_mesh");

        pass.set_bind_group(0, &bind_group, &[]);
        pass.set_pipeline(init_pipeline);
        // we only dispatch 1,1,1 workgroup here, but a real compute shader
        // would take advantage of more and larger size workgroups
        pass.dispatch_workgroups(1, 1, 1);

        pass.pop_debug_group();
    }
}

pub fn mesh_index_slice( &self, mesh_id: &AssetId<Mesh>, ) -> Option<SlabAllocationBufferSlice<'_, MeshSlabItem>>

Returns the buffer and range within that buffer of the index data for the mesh with the given ID.

If the mesh has no index data or wasn’t allocated, returns None.

Examples found in repository

examples/shader_advanced/custom_shader_instancing.rs (line 336)

    fn render<'w>(
        item: &P,
        _view: (),
        instance_buffer: Option<&'w InstanceBuffer>,
        (meshes, render_mesh_instances, mesh_allocator): SystemParamItem<'w, '_, Self::Param>,
        pass: &mut TrackedRenderPass<'w>,
    ) -> RenderCommandResult {
        // A borrow check workaround.
        let mesh_allocator = mesh_allocator.into_inner();

        let Some(mesh_instance) = render_mesh_instances.render_mesh_queue_data(item.main_entity())
        else {
            return RenderCommandResult::Skip;
        };
        let Some(gpu_mesh) = meshes.into_inner().get(mesh_instance.mesh_asset_id()) else {
            return RenderCommandResult::Skip;
        };
        let Some(instance_buffer) = instance_buffer else {
            return RenderCommandResult::Skip;
        };
        let Some(vertex_buffer_slice) =
            mesh_allocator.mesh_vertex_slice(&mesh_instance.mesh_asset_id())
        else {
            return RenderCommandResult::Skip;
        };

        pass.set_vertex_buffer(0, vertex_buffer_slice.buffer.slice(..));
        pass.set_vertex_buffer(1, instance_buffer.buffer.slice(..));

        match &gpu_mesh.buffer_info {
            RenderMeshBufferInfo::Indexed {
                index_format,
                count,
            } => {
                let Some(index_buffer_slice) =
                    mesh_allocator.mesh_index_slice(&mesh_instance.mesh_asset_id())
                else {
                    return RenderCommandResult::Skip;
                };

                pass.set_index_buffer(index_buffer_slice.buffer.slice(..), *index_format);
                pass.draw_indexed(
                    index_buffer_slice.range.start..(index_buffer_slice.range.start + count),
                    vertex_buffer_slice.range.start as i32,
                    0..instance_buffer.length as u32,
                );
            }
            RenderMeshBufferInfo::NonIndexed => {
                pass.draw(vertex_buffer_slice.range, 0..instance_buffer.length as u32);
            }
        }
        RenderCommandResult::Success
    }

examples/shader_advanced/compute_mesh.rs (line 273)

fn compute_mesh(
    mut render_context: RenderContext,
    chunks: Res<ChunksToProcess>,
    mesh_allocator: Res<MeshAllocator>,
    pipeline_cache: Res<PipelineCache>,
    pipeline: Res<ComputePipeline>,
    render_queue: Res<RenderQueue>,
) {
    let Some(init_pipeline) = pipeline_cache.get_compute_pipeline(pipeline.pipeline) else {
        return;
    };

    for mesh_id in &chunks.0 {
        info!(?mesh_id, "processing mesh");

        // the mesh_allocator holds slabs of meshes, so the buffers we get here
        // can contain more data than just the mesh we're asking for.
        // That's why there is a range field.
        // You should *not* touch data in these buffers that is outside of the range.
        let vertex_buffer_slice = mesh_allocator.mesh_vertex_slice(mesh_id).unwrap();
        let index_buffer_slice = mesh_allocator.mesh_index_slice(mesh_id).unwrap();

        let first = DataRanges {
            // there are 8 vertex data values (pos, normal, uv) per vertex
            // and the vertex_buffer_slice.range.start is in "vertex elements"
            // which includes all of that data, so each index is worth 8 indices
            // to our shader code.
            vertex_start: vertex_buffer_slice.range.start * 8,
            vertex_end: vertex_buffer_slice.range.end * 8,
            // but each vertex index is a single value, so the index of the
            // vertex indices is exactly what the value is
            index_start: index_buffer_slice.range.start,
            index_end: index_buffer_slice.range.end,
        };

        let mut uniforms = UniformBuffer::from(first);
        uniforms.write_buffer(render_context.render_device(), &render_queue);

        // pass in the full mesh_allocator slabs as well as the first index
        // offsets for the vertex and index buffers
        let bind_group = render_context.render_device().create_bind_group(
            None,
            &pipeline_cache.get_bind_group_layout(&pipeline.layout),
            &BindGroupEntries::sequential((
                &uniforms,
                vertex_buffer_slice.buffer.as_entire_buffer_binding(),
                index_buffer_slice.buffer.as_entire_buffer_binding(),
            )),
        );

        let mut pass =
            render_context
                .command_encoder()
                .begin_compute_pass(&ComputePassDescriptor {
                    label: Some("Mesh generation compute pass"),
                    ..default()
                });
        pass.push_debug_group("compute_mesh");

        pass.set_bind_group(0, &bind_group, &[]);
        pass.set_pipeline(init_pipeline);
        // we only dispatch 1,1,1 workgroup here, but a real compute shader
        // would take advantage of more and larger size workgroups
        pass.dispatch_workgroups(1, 1, 1);

        pass.pop_debug_group();
    }
}

pub fn mesh_morph_target_slice( &self, mesh_id: &AssetId<Mesh>, ) -> Option<SlabAllocationBufferSlice<'_, MeshSlabItem>>

Available on crate feature morph only.

Returns the buffer and range within that buffer of the morph target data for the mesh with the given ID.

If the mesh has no morph target data or wasn’t allocated, returns None.

pub fn mesh_slabs(&self, mesh_id: &AssetId<Mesh>) -> Option<MeshSlabs>

Returns the IDs of the vertex buffer and index buffer respectively for the mesh with the given ID.

If the mesh wasn’t allocated, or has no index data in the case of the index buffer, the corresponding element in the returned tuple will be None.

Examples found in repository

examples/shader_advanced/specialized_mesh_pipeline.rs (line 355)

fn queue_custom_mesh_pipeline(
    pipeline_cache: Res<PipelineCache>,
    custom_mesh_pipeline: Res<CustomMeshPipeline>,
    (mut opaque_render_phases, opaque_draw_functions): (
        ResMut<ViewBinnedRenderPhases<Opaque3d>>,
        Res<DrawFunctions<Opaque3d>>,
    ),
    mut specialized_mesh_pipelines: ResMut<SpecializedMeshPipelines<CustomMeshPipeline>>,
    views: Query<(&RenderVisibleEntities, &ExtractedView)>,
    view_key_cache: Res<ViewKeyCache>,
    (render_meshes, render_mesh_instances): (
        Res<RenderAssets<RenderMesh>>,
        Res<RenderMeshInstances>,
    ),
    mut change_tick: Local<Tick>,
    mesh_allocator: Res<MeshAllocator>,
    gpu_preprocessing_support: Res<GpuPreprocessingSupport>,
    dirty_specializations: Res<DirtySpecializations>,
    mut pending_custom_mesh_queues: ResMut<PendingCustomMeshQueues>,
) {
    // Get the id for our custom draw function
    let draw_function = opaque_draw_functions
        .read()
        .id::<DrawSpecializedPipelineCommands>();

    // Render phases are per-view, so we need to iterate over all views so that
    // the entity appears in them. (In this example, we have only one view, but
    // it's good practice to loop over all views anyway.)
    for (view_visible_entities, view) in views.iter() {
        let Some(opaque_phase) = opaque_render_phases.get_mut(&view.retained_view_entity) else {
            continue;
        };

        let Some(&view_key) = view_key_cache.get(&view.retained_view_entity) else {
            continue;
        };

        let Some(render_visible_mesh_entities) =
            view_visible_entities.get::<CustomRenderedEntity>()
        else {
            continue;
        };

        // Initialize the pending queues.
        let view_pending_custom_mesh_queues =
            pending_custom_mesh_queues.prepare_for_new_frame(view.retained_view_entity);

        // First, remove meshes that need to be respecialized, and those that were removed, from the bins.
        for &main_entity in dirty_specializations
            .iter_to_dequeue(view.retained_view_entity, render_visible_mesh_entities)
        {
            opaque_phase.remove(main_entity);
        }

        // Find all the custom rendered entities that are visible from this
        // view.
        for (render_entity, visible_entity) in dirty_specializations.iter_to_queue(
            view.retained_view_entity,
            render_visible_mesh_entities,
            &view_pending_custom_mesh_queues.prev_frame,
        ) {
            // Get the mesh instance
            let Some(mesh_instance) = render_mesh_instances.render_mesh_queue_data(*visible_entity)
            else {
                // We couldn't fetch the mesh, probably because it hasn't been
                // loaded yet. Add the entity to the list of pending custom
                // meshes and bail.
                view_pending_custom_mesh_queues
                    .current_frame
                    .insert((*render_entity, *visible_entity));
                continue;
            };

            // Get the mesh data
            let Some(mesh) = render_meshes.get(mesh_instance.mesh_asset_id()) else {
                continue;
            };

            let Some(mesh_slabs) = mesh_allocator.mesh_slabs(&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_and_strip_index(
                mesh.primitive_topology(),
                mesh.index_format(),
            );

            // Finally, we can specialize the pipeline based on the key
            let pipeline_id = specialized_mesh_pipelines
                .specialize(
                    &pipeline_cache,
                    &custom_mesh_pipeline,
                    mesh_key,
                    &mesh.layout,
                )
                // This should never happen with this example, but if your pipeline
                // specialization can fail you need to handle the error here
                .expect("Failed to specialize mesh pipeline");

            // Bump the change tick so that Bevy is forced to rebuild the bin.
            let next_change_tick = change_tick.get() + 1;
            change_tick.set(next_change_tick);

            // Add the mesh with our specialized pipeline
            opaque_phase.add(
                Opaque3dBatchSetKey {
                    draw_function,
                    pipeline: pipeline_id,
                    material_bind_group_index: None,
                    slabs: mesh_slabs,
                    lightmap_slab: None,
                },
                // For this example we can use the mesh asset id as the bin key,
                // but you can use any asset_id as a key
                Opaque3dBinKey {
                    asset_id: mesh_instance.mesh_asset_id().into(),
                },
                (*render_entity, *visible_entity),
                mesh_instance.current_uniform_index,
                // This example supports batching and multi draw indirect,
                // but if your pipeline doesn't support it you can use
                // `BinnedRenderPhaseType::UnbatchableMesh`
                BinnedRenderPhaseType::mesh(
                    mesh_instance.should_batch(),
                    &gpu_preprocessing_support,
                ),
            );
        }
    }
}

pub fn index_allocation_count(&self) -> usize

Returns the number of index allocations that this mesh allocator manages.

pub fn morph_target_slabs(&self) -> impl Iterator<Item = SlabId<MeshSlabItem>>

Available on crate feature morph only.

Returns an iterator over all slabs that contain morph targets.

Methods from Deref<Target = SlabAllocator<MeshSlabItem>>

pub fn stage_allocation(&mut self) -> AllocationStage<'_, I>

Creates an AllocationStage, enabling batched allocation of objects in this slab.

Allocation of objects in the slab requires calling this function, calling AllocationStage::allocate on the resulting AllocationStage, and finally calling AllocationStage::commit. Grouping allocations into a batch, preferably at most one per frame, is the most efficient way to perform many allocations at once.

pub fn stage_deallocation(&mut self) -> DeallocationStage<'_, I>

Creates a DeallocationStage, enabling batched deallocation.

Deallocation of objects in the slab requires calling this function, calling DeallocationStage::free on the resulting DeallocationStage, and finally calling DeallocationStage::commit. Grouping deallocations into a batch, preferably at most one per frame, is the most efficient way to perform many deallocations at once.

pub fn buffer_for_slab(&self, slab_id: SlabId<I>) -> Option<&Buffer>

Returns the GPU buffer corresponding to the slab with the given ID if that slab has been uploaded to the GPU.

pub fn slab_allocation_slice( &self, key: &<I as SlabItem>::Key, slab_id: SlabId<I>, ) -> Option<SlabAllocationBufferSlice<'_, I>>

Given a slab and the key of data located with it, returns the buffer and range of that data within the slab.

pub fn slab_count(&self) -> usize

Get the number of allocated slabs

pub fn slabs_size(&self) -> u64

Get the total size of all allocated slabs

pub fn copy_element_data( &mut self, key: &<I as SlabItem>::Key, len: usize, fill_data: impl Fn(WriteOnly<'_, [u8]>), render_device: &RenderDevice, render_queue: &RenderQueue, )

Copies data into an allocated slab.

len specifies the size of the data to be copied in bytes. The given fill_data callback is expected to write the data into the given slice; this callback approach avoids a copy.

Trait Implementations

impl Component for MeshAllocator

where MeshAllocator: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::SparseSet

A constant indicating the storage type used for this component.

type Mutability = Mutable

A marker type to assist Bevy with determining if this component is mutable, or immutable. Mutable components will have Component<Mutability = Mutable>, while immutable components will instead have Component<Mutability = Immutable>.

fn register_required_components( _requiree: ComponentId, required_components: &mut RequiredComponentsRegistrator<'_, '_>, )

Registers required components.

fn clone_behavior() -> ComponentCloneBehavior

Called when registering this component, allowing to override clone function (or disable cloning altogether) for this component.

fn relationship_accessor() -> Option<ComponentRelationshipAccessor<MeshAllocator>>

Returns ComponentRelationshipAccessor required for working with relationships in dynamic contexts.

fn on_add() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_add ComponentHook for this Component if one is defined.

fn on_insert() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_insert ComponentHook for this Component if one is defined.

fn on_discard() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_discard ComponentHook for this Component if one is defined.

fn on_remove() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_remove ComponentHook for this Component if one is defined.

fn on_despawn() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_despawn ComponentHook for this Component if one is defined.

fn map_entities<E>(_this: &mut Self, _mapper: &mut E)

where E: EntityMapper,

Maps the entities on this component using the given EntityMapper. This is used to remap entities in contexts like scenes and entity cloning. When deriving Component, this is populated by annotating fields containing entities with #[entities]

impl Deref for MeshAllocator

type Target = SlabAllocator<MeshSlabItem>

The resulting type after dereferencing.

fn deref(&self) -> &<MeshAllocator as Deref>::Target

Dereferences the value.

impl DerefMut for MeshAllocator

fn deref_mut(&mut self) -> &mut <MeshAllocator as Deref>::Target

Mutably dereferences the value.

impl FromWorld for MeshAllocator

fn from_world(world: &mut World) -> MeshAllocator

Creates Self using data from the given World.

impl Resource for MeshAllocator

where MeshAllocator: Send + Sync + 'static,