Trait wgpu_hal::CommandEncoder

pub trait CommandEncoder: WasmNotSendSync + Debug {
    type A: Api;

    // Required methods
    unsafe fn begin_encoding(
        &mut self,
        label: Label<'_>,
    ) -> Result<(), DeviceError>;
    unsafe fn discard_encoding(&mut self);
    unsafe fn end_encoding(
        &mut self,
    ) -> Result<<Self::A as Api>::CommandBuffer, DeviceError>;
    unsafe fn reset_all<I>(&mut self, command_buffers: I)
       where I: Iterator<Item = <Self::A as Api>::CommandBuffer>;
    unsafe fn transition_buffers<'a, T>(&mut self, barriers: T)
       where T: Iterator<Item = BufferBarrier<'a, <Self::A as Api>::Buffer>>;
    unsafe fn transition_textures<'a, T>(&mut self, barriers: T)
       where T: Iterator<Item = TextureBarrier<'a, <Self::A as Api>::Texture>>;
    unsafe fn clear_buffer(
        &mut self,
        buffer: &<Self::A as Api>::Buffer,
        range: MemoryRange,
    );
    unsafe fn copy_buffer_to_buffer<T>(
        &mut self,
        src: &<Self::A as Api>::Buffer,
        dst: &<Self::A as Api>::Buffer,
        regions: T,
    )
       where T: Iterator<Item = BufferCopy>;
    unsafe fn copy_texture_to_texture<T>(
        &mut self,
        src: &<Self::A as Api>::Texture,
        src_usage: TextureUses,
        dst: &<Self::A as Api>::Texture,
        regions: T,
    )
       where T: Iterator<Item = TextureCopy>;
    unsafe fn copy_buffer_to_texture<T>(
        &mut self,
        src: &<Self::A as Api>::Buffer,
        dst: &<Self::A as Api>::Texture,
        regions: T,
    )
       where T: Iterator<Item = BufferTextureCopy>;
    unsafe fn copy_texture_to_buffer<T>(
        &mut self,
        src: &<Self::A as Api>::Texture,
        src_usage: TextureUses,
        dst: &<Self::A as Api>::Buffer,
        regions: T,
    )
       where T: Iterator<Item = BufferTextureCopy>;
    unsafe fn set_bind_group(
        &mut self,
        layout: &<Self::A as Api>::PipelineLayout,
        index: u32,
        group: &<Self::A as Api>::BindGroup,
        dynamic_offsets: &[DynamicOffset],
    );
    unsafe fn set_push_constants(
        &mut self,
        layout: &<Self::A as Api>::PipelineLayout,
        stages: ShaderStages,
        offset_bytes: u32,
        data: &[u32],
    );
    unsafe fn insert_debug_marker(&mut self, label: &str);
    unsafe fn begin_debug_marker(&mut self, group_label: &str);
    unsafe fn end_debug_marker(&mut self);
    unsafe fn begin_query(
        &mut self,
        set: &<Self::A as Api>::QuerySet,
        index: u32,
    );
    unsafe fn end_query(&mut self, set: &<Self::A as Api>::QuerySet, index: u32);
    unsafe fn write_timestamp(
        &mut self,
        set: &<Self::A as Api>::QuerySet,
        index: u32,
    );
    unsafe fn reset_queries(
        &mut self,
        set: &<Self::A as Api>::QuerySet,
        range: Range<u32>,
    );
    unsafe fn copy_query_results(
        &mut self,
        set: &<Self::A as Api>::QuerySet,
        range: Range<u32>,
        buffer: &<Self::A as Api>::Buffer,
        offset: BufferAddress,
        stride: BufferSize,
    );
    unsafe fn begin_render_pass(
        &mut self,
        desc: &RenderPassDescriptor<'_, <Self::A as Api>::QuerySet, <Self::A as Api>::TextureView>,
    );
    unsafe fn end_render_pass(&mut self);
    unsafe fn set_render_pipeline(
        &mut self,
        pipeline: &<Self::A as Api>::RenderPipeline,
    );
    unsafe fn set_index_buffer<'a>(
        &mut self,
        binding: BufferBinding<'a, <Self::A as Api>::Buffer>,
        format: IndexFormat,
    );
    unsafe fn set_vertex_buffer<'a>(
        &mut self,
        index: u32,
        binding: BufferBinding<'a, <Self::A as Api>::Buffer>,
    );
    unsafe fn set_viewport(&mut self, rect: &Rect<f32>, depth_range: Range<f32>);
    unsafe fn set_scissor_rect(&mut self, rect: &Rect<u32>);
    unsafe fn set_stencil_reference(&mut self, value: u32);
    unsafe fn set_blend_constants(&mut self, color: &[f32; 4]);
    unsafe fn draw(
        &mut self,
        first_vertex: u32,
        vertex_count: u32,
        first_instance: u32,
        instance_count: u32,
    );
    unsafe fn draw_indexed(
        &mut self,
        first_index: u32,
        index_count: u32,
        base_vertex: i32,
        first_instance: u32,
        instance_count: u32,
    );
    unsafe fn draw_indirect(
        &mut self,
        buffer: &<Self::A as Api>::Buffer,
        offset: BufferAddress,
        draw_count: u32,
    );
    unsafe fn draw_indexed_indirect(
        &mut self,
        buffer: &<Self::A as Api>::Buffer,
        offset: BufferAddress,
        draw_count: u32,
    );
    unsafe fn draw_indirect_count(
        &mut self,
        buffer: &<Self::A as Api>::Buffer,
        offset: BufferAddress,
        count_buffer: &<Self::A as Api>::Buffer,
        count_offset: BufferAddress,
        max_count: u32,
    );
    unsafe fn draw_indexed_indirect_count(
        &mut self,
        buffer: &<Self::A as Api>::Buffer,
        offset: BufferAddress,
        count_buffer: &<Self::A as Api>::Buffer,
        count_offset: BufferAddress,
        max_count: u32,
    );
    unsafe fn begin_compute_pass(
        &mut self,
        desc: &ComputePassDescriptor<'_, <Self::A as Api>::QuerySet>,
    );
    unsafe fn end_compute_pass(&mut self);
    unsafe fn set_compute_pipeline(
        &mut self,
        pipeline: &<Self::A as Api>::ComputePipeline,
    );
    unsafe fn dispatch(&mut self, count: [u32; 3]);
    unsafe fn dispatch_indirect(
        &mut self,
        buffer: &<Self::A as Api>::Buffer,
        offset: BufferAddress,
    );
    unsafe fn build_acceleration_structures<'a, T>(
        &mut self,
        descriptor_count: u32,
        descriptors: T,
    )
       where Self::A: 'a,
             T: IntoIterator<Item = BuildAccelerationStructureDescriptor<'a, <Self::A as Api>::Buffer, <Self::A as Api>::AccelerationStructure>>;
    unsafe fn place_acceleration_structure_barrier(
        &mut self,
        barrier: AccelerationStructureBarrier,
    );
}

Encoder and allocation pool for CommandBuffers.

A CommandEncoder not only constructs CommandBuffers but also acts as the allocation pool that owns the buffers’ underlying storage. Thus, CommandBuffers must not outlive the CommandEncoder that created them.

The life cycle of a CommandBuffer is as follows:

• Call Device::create_command_encoder to create a new CommandEncoder, in the “closed” state.

• Call begin_encoding on a closed CommandEncoder to begin recording commands. This puts the CommandEncoder in the “recording” state.

• Call methods like copy_buffer_to_buffer, begin_render_pass, etc. on a “recording” CommandEncoder to add commands to the list. (If an error occurs, you must call discard_encoding; see below.)

• Call end_encoding on a recording CommandEncoder to close the encoder and construct a fresh CommandBuffer consisting of the list of commands recorded up to that point.

• Call discard_encoding on a recording CommandEncoder to drop the commands recorded thus far and close the encoder. This is the only safe thing to do on a CommandEncoder if an error has occurred while recording commands.

• Call reset_all on a closed CommandEncoder, passing all the live CommandBuffers built from it. All the CommandBuffers are destroyed, and their resources are freed.

Safety

• The CommandEncoder must be in the states described above to make the given calls.

• A CommandBuffer that has been submitted for execution on the GPU must live until its execution is complete.

• A CommandBuffer must not outlive the CommandEncoder that built it.

• A CommandEncoder must not outlive its Device.

It is the user’s responsibility to meet this requirements. This allows CommandEncoder implementations to keep their state tracking to a minimum.

Required Associated Types

type A: Api

Required Methods

unsafe fn begin_encoding(&mut self, label: Label<'_>) -> Result<(), DeviceError>

Begin encoding a new command buffer.

This puts this CommandEncoder in the “recording” state.

Safety

This CommandEncoder must be in the “closed” state.

unsafe fn discard_encoding(&mut self)

Discard the command list under construction.

If an error has occurred while recording commands, this is the only safe thing to do with the encoder.

This puts this CommandEncoder in the “closed” state.

Safety

This CommandEncoder must be in the “recording” state.

Callers must not assume that implementations of this function are idempotent, and thus should not call it multiple times in a row.

unsafe fn end_encoding( &mut self, ) -> Result<<Self::A as Api>::CommandBuffer, DeviceError>

Return a fresh CommandBuffer holding the recorded commands.

The returned CommandBuffer holds all the commands recorded on this CommandEncoder since the last call to begin_encoding.

This puts this CommandEncoder in the “closed” state.

Safety

This CommandEncoder must be in the “recording” state.

The returned CommandBuffer must not outlive this CommandEncoder. Implementations are allowed to build CommandBuffers that depend on storage owned by this CommandEncoder.

unsafe fn reset_all<I>(&mut self, command_buffers: I)

where I: Iterator<Item = <Self::A as Api>::CommandBuffer>,

Reclaim all resources belonging to this CommandEncoder.

Safety

This CommandEncoder must be in the “closed” state.

The command_buffers iterator must produce all the live CommandBuffers built using this CommandEncoder — that is, every extant CommandBuffer returned from end_encoding.

unsafe fn transition_buffers<'a, T>(&mut self, barriers: T)

where T: Iterator<Item = BufferBarrier<'a, <Self::A as Api>::Buffer>>,

unsafe fn transition_textures<'a, T>(&mut self, barriers: T)

where T: Iterator<Item = TextureBarrier<'a, <Self::A as Api>::Texture>>,

unsafe fn clear_buffer( &mut self, buffer: &<Self::A as Api>::Buffer, range: MemoryRange, )

unsafe fn copy_buffer_to_buffer<T>( &mut self, src: &<Self::A as Api>::Buffer, dst: &<Self::A as Api>::Buffer, regions: T, )

where T: Iterator<Item = BufferCopy>,

unsafe fn copy_texture_to_texture<T>( &mut self, src: &<Self::A as Api>::Texture, src_usage: TextureUses, dst: &<Self::A as Api>::Texture, regions: T, )

where T: Iterator<Item = TextureCopy>,

Copy from one texture to another. Works with a single array layer. Note: dst current usage has to be TextureUses::COPY_DST. Note: the copy extent is in physical size (rounded to the block size)

unsafe fn copy_buffer_to_texture<T>( &mut self, src: &<Self::A as Api>::Buffer, dst: &<Self::A as Api>::Texture, regions: T, )

where T: Iterator<Item = BufferTextureCopy>,

Copy from buffer to texture. Works with a single array layer. Note: dst current usage has to be TextureUses::COPY_DST. Note: the copy extent is in physical size (rounded to the block size)

unsafe fn copy_texture_to_buffer<T>( &mut self, src: &<Self::A as Api>::Texture, src_usage: TextureUses, dst: &<Self::A as Api>::Buffer, regions: T, )

where T: Iterator<Item = BufferTextureCopy>,

Copy from texture to buffer. Works with a single array layer. Note: the copy extent is in physical size (rounded to the block size)

unsafe fn set_bind_group( &mut self, layout: &<Self::A as Api>::PipelineLayout, index: u32, group: &<Self::A as Api>::BindGroup, dynamic_offsets: &[DynamicOffset], )

Sets the bind group at index to group.

If this is not the first call to set_bind_group within the current render or compute pass:

• If layout contains n bind group layouts, then any previously set bind groups at indices n or higher are cleared.

• If the first m bind group layouts of layout are equal to those of the previously passed layout, but no more, then any previously set bind groups at indices m or higher are cleared.

It follows from the above that passing the same layout as before doesn’t clear any bind groups.

Safety

• This CommandEncoder must be within a render or compute pass.

• index must be the valid index of some bind group layout in layout. Call this the “relevant bind group layout”.

• The layout of group must be equal to the relevant bind group layout.

• The length of dynamic_offsets must match the number of buffer bindings with dynamic offsets in the relevant bind group layout.

• If those buffer bindings are ordered by increasing binding number and paired with elements from dynamic_offsets, then each offset must be a valid offset for the binding’s corresponding buffer in group.

unsafe fn set_push_constants( &mut self, layout: &<Self::A as Api>::PipelineLayout, stages: ShaderStages, offset_bytes: u32, data: &[u32], )

Sets a range in push constant data.

IMPORTANT: while the data is passed as words, the offset is in bytes!

Safety

• offset_bytes must be a multiple of 4.
• The range of push constants written must be valid for the pipeline layout at draw time.

unsafe fn insert_debug_marker(&mut self, label: &str)

unsafe fn begin_debug_marker(&mut self, group_label: &str)

unsafe fn end_debug_marker(&mut self)

unsafe fn begin_query(&mut self, set: &<Self::A as Api>::QuerySet, index: u32)

Safety:

• If set is an occlusion query set, it must be the same one as used in the RenderPassDescriptor::occlusion_query_set parameter.

unsafe fn end_query(&mut self, set: &<Self::A as Api>::QuerySet, index: u32)

Safety:

• If set is an occlusion query set, it must be the same one as used in the RenderPassDescriptor::occlusion_query_set parameter.

unsafe fn write_timestamp( &mut self, set: &<Self::A as Api>::QuerySet, index: u32, )

unsafe fn reset_queries( &mut self, set: &<Self::A as Api>::QuerySet, range: Range<u32>, )

unsafe fn copy_query_results( &mut self, set: &<Self::A as Api>::QuerySet, range: Range<u32>, buffer: &<Self::A as Api>::Buffer, offset: BufferAddress, stride: BufferSize, )

unsafe fn begin_render_pass( &mut self, desc: &RenderPassDescriptor<'_, <Self::A as Api>::QuerySet, <Self::A as Api>::TextureView>, )

Begin a new render pass, clearing all active bindings.

This clears any bindings established by the following calls:

• set_bind_group
• set_push_constants
• begin_query
• set_render_pipeline
• set_index_buffer
• set_vertex_buffer

Safety

• All prior calls to begin_render_pass on this CommandEncoder must have been followed by a call to end_render_pass.

• All prior calls to begin_compute_pass on this CommandEncoder must have been followed by a call to end_compute_pass.

unsafe fn end_render_pass(&mut self)

End the current render pass.

Safety

• There must have been a prior call to begin_render_pass on this CommandEncoder that has not been followed by a call to end_render_pass.

unsafe fn set_render_pipeline( &mut self, pipeline: &<Self::A as Api>::RenderPipeline, )

unsafe fn set_index_buffer<'a>( &mut self, binding: BufferBinding<'a, <Self::A as Api>::Buffer>, format: IndexFormat, )

unsafe fn set_vertex_buffer<'a>( &mut self, index: u32, binding: BufferBinding<'a, <Self::A as Api>::Buffer>, )

unsafe fn set_viewport(&mut self, rect: &Rect<f32>, depth_range: Range<f32>)

unsafe fn set_scissor_rect(&mut self, rect: &Rect<u32>)

unsafe fn set_stencil_reference(&mut self, value: u32)

unsafe fn set_blend_constants(&mut self, color: &[f32; 4])

unsafe fn draw( &mut self, first_vertex: u32, vertex_count: u32, first_instance: u32, instance_count: u32, )

unsafe fn draw_indexed( &mut self, first_index: u32, index_count: u32, base_vertex: i32, first_instance: u32, instance_count: u32, )

unsafe fn draw_indirect( &mut self, buffer: &<Self::A as Api>::Buffer, offset: BufferAddress, draw_count: u32, )

unsafe fn draw_indexed_indirect( &mut self, buffer: &<Self::A as Api>::Buffer, offset: BufferAddress, draw_count: u32, )

unsafe fn draw_indirect_count( &mut self, buffer: &<Self::A as Api>::Buffer, offset: BufferAddress, count_buffer: &<Self::A as Api>::Buffer, count_offset: BufferAddress, max_count: u32, )

unsafe fn draw_indexed_indirect_count( &mut self, buffer: &<Self::A as Api>::Buffer, offset: BufferAddress, count_buffer: &<Self::A as Api>::Buffer, count_offset: BufferAddress, max_count: u32, )

unsafe fn begin_compute_pass( &mut self, desc: &ComputePassDescriptor<'_, <Self::A as Api>::QuerySet>, )

Begin a new compute pass, clearing all active bindings.

This clears any bindings established by the following calls:

• set_bind_group
• set_push_constants
• begin_query
• set_compute_pipeline

Safety

• All prior calls to begin_render_pass on this CommandEncoder must have been followed by a call to end_render_pass.

• All prior calls to begin_compute_pass on this CommandEncoder must have been followed by a call to end_compute_pass.

unsafe fn end_compute_pass(&mut self)

End the current compute pass.

Safety

• There must have been a prior call to begin_compute_pass on this CommandEncoder that has not been followed by a call to end_compute_pass.

unsafe fn set_compute_pipeline( &mut self, pipeline: &<Self::A as Api>::ComputePipeline, )

unsafe fn dispatch(&mut self, count: [u32; 3])

unsafe fn dispatch_indirect( &mut self, buffer: &<Self::A as Api>::Buffer, offset: BufferAddress, )

unsafe fn build_acceleration_structures<'a, T>( &mut self, descriptor_count: u32, descriptors: T, )

where Self::A: 'a, T: IntoIterator<Item = BuildAccelerationStructureDescriptor<'a, <Self::A as Api>::Buffer, <Self::A as Api>::AccelerationStructure>>,

To get the required sizes for the buffer allocations use get_acceleration_structure_build_sizes per descriptor All buffers must be synchronized externally All buffer regions, which are written to may only be passed once per function call, with the exception of updates in the same descriptor. Consequences of this limitation:

• scratch buffers need to be unique
• a tlas can’t be build in the same call with a blas it contains

unsafe fn place_acceleration_structure_barrier( &mut self, barrier: AccelerationStructureBarrier, )

Object Safety

This trait is not object safe.

Implementors

impl CommandEncoder for Encoder

type A = Api

impl CommandEncoder for wgpu_hal::gles::CommandEncoder

type A = Api

impl CommandEncoder for wgpu_hal::vulkan::CommandEncoder

type A = Api