Trait wgpu_hal::CommandEncoder
source · pub trait CommandEncoder: WasmNotSendSync + Debug {
type A: Api;
Show 43 methods
// 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
);
}
Expand description
Encoder and allocation pool for CommandBuffer
s.
A CommandEncoder
not only constructs CommandBuffer
s but also
acts as the allocation pool that owns the buffers’ underlying
storage. Thus, CommandBuffer
s 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 newCommandEncoder
, in the “closed” state. -
Call
begin_encoding
on a closedCommandEncoder
to begin recording commands. This puts theCommandEncoder
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 calldiscard_encoding
; see below.) -
Call
end_encoding
on a recordingCommandEncoder
to close the encoder and construct a freshCommandBuffer
consisting of the list of commands recorded up to that point. -
Call
discard_encoding
on a recordingCommandEncoder
to drop the commands recorded thus far and close the encoder. This is the only safe thing to do on aCommandEncoder
if an error has occurred while recording commands. -
Call
reset_all
on a closedCommandEncoder
, passing all the liveCommandBuffers
built from it. All theCommandBuffer
s 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 theCommandEncoder
that built it. -
A
CommandEncoder
must not outlive itsDevice
.
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§
Required Methods§
sourceunsafe fn begin_encoding(&mut self, label: Label<'_>) -> Result<(), DeviceError>
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.
sourceunsafe fn discard_encoding(&mut self)
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.
sourceunsafe fn end_encoding(
&mut self
) -> Result<<Self::A as Api>::CommandBuffer, DeviceError>
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
CommandBuffer
s that depend on storage owned by this
CommandEncoder
.
sourceunsafe fn reset_all<I>(&mut self, command_buffers: I)
unsafe fn reset_all<I>(&mut self, command_buffers: I)
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
CommandBuffer
s built using this CommandEncoder
— that
is, every extant CommandBuffer
returned from end_encoding
.
unsafe fn transition_buffers<'a, T>(&mut self, barriers: T)
unsafe fn transition_textures<'a, T>(&mut self, barriers: T)
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>,
sourceunsafe 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_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)
sourceunsafe 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_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)
sourceunsafe 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 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)
sourceunsafe 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_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
containsn
bind group layouts, then any previously set bind groups at indicesn
or higher are cleared. -
If the first
m
bind group layouts oflayout
are equal to those of the previously passed layout, but no more, then any previously set bind groups at indicesm
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 inlayout
. 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 fromdynamic_offsets
, then each offset must be a valid offset for the binding’s corresponding buffer ingroup
.
sourceunsafe fn set_push_constants(
&mut self,
layout: &<Self::A as Api>::PipelineLayout,
stages: ShaderStages,
offset_bytes: u32,
data: &[u32]
)
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)
sourceunsafe fn begin_query(&mut self, set: &<Self::A as Api>::QuerySet, index: u32)
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 theRenderPassDescriptor::occlusion_query_set
parameter.
sourceunsafe fn end_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)
Safety:
- If
set
is an occlusion query set, it must be the same one as used in theRenderPassDescriptor::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 )
sourceunsafe fn begin_render_pass(
&mut self,
desc: &RenderPassDescriptor<'_, <Self::A as Api>::QuerySet, <Self::A as Api>::TextureView>
)
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 thisCommandEncoder
must have been followed by a call toend_render_pass
. -
All prior calls to
begin_compute_pass
on thisCommandEncoder
must have been followed by a call toend_compute_pass
.
sourceunsafe fn end_render_pass(&mut self)
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 thisCommandEncoder
that has not been followed by a call toend_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 )
sourceunsafe fn begin_compute_pass(
&mut self,
desc: &ComputePassDescriptor<'_, <Self::A as Api>::QuerySet>
)
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:
Safety
-
All prior calls to
begin_render_pass
on thisCommandEncoder
must have been followed by a call toend_render_pass
. -
All prior calls to
begin_compute_pass
on thisCommandEncoder
must have been followed by a call toend_compute_pass
.
sourceunsafe fn end_compute_pass(&mut self)
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 thisCommandEncoder
that has not been followed by a call toend_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 )
sourceunsafe 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 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§
Implementors§
source§impl CommandEncoder for wgpu_hal::gles::CommandEncoder
Available on gles
only.
impl CommandEncoder for wgpu_hal::gles::CommandEncoder
gles
only.source§impl CommandEncoder for wgpu_hal::vulkan::CommandEncoder
Available on vulkan
only.
impl CommandEncoder for wgpu_hal::vulkan::CommandEncoder
vulkan
only.