pub struct Queue { /* private fields */ }
Expand description
Handle to a command queue on a device.
A Queue
executes recorded CommandBuffer
objects and provides convenience methods
for writing to buffers and textures.
It can be created along with a Device
by calling Adapter::request_device
.
Corresponds to WebGPU GPUQueue
.
Implementations§
Source§impl Queue
impl Queue
Sourcepub fn write_buffer(&self, buffer: &Buffer, offset: BufferAddress, data: &[u8])
pub fn write_buffer(&self, buffer: &Buffer, offset: BufferAddress, data: &[u8])
Schedule a data write into buffer
starting at offset
.
This method fails if data
overruns the size of buffer
starting at offset
.
This does not submit the transfer to the GPU immediately. Calls to
write_buffer
begin execution only on the next call to
Queue::submit
. To get a set of scheduled transfers started
immediately, it’s fine to call submit
with no command buffers at all:
queue.submit([]);
However, data
will be immediately copied into staging memory, so the
caller may discard it any time after this call completes.
If possible, consider using Queue::write_buffer_with
instead. That
method avoids an intermediate copy and is often able to transfer data
more efficiently than this one.
Sourcepub fn write_buffer_with<'a>(
&'a self,
buffer: &'a Buffer,
offset: BufferAddress,
size: BufferSize,
) -> Option<QueueWriteBufferView<'a>>
pub fn write_buffer_with<'a>( &'a self, buffer: &'a Buffer, offset: BufferAddress, size: BufferSize, ) -> Option<QueueWriteBufferView<'a>>
Write to a buffer via a directly mapped staging buffer.
Return a QueueWriteBufferView
which, when dropped, schedules a copy
of its contents into buffer
at offset
. The returned view
dereferences to a size
-byte long &mut [u8]
, in which you should
store the data you would like written to buffer
.
This method may perform transfers faster than Queue::write_buffer
,
because the returned QueueWriteBufferView
is actually the staging
buffer for the write, mapped into the caller’s address space. Writing
your data directly into this staging buffer avoids the temporary
CPU-side buffer needed by write_buffer
.
Reading from the returned view is slow, and will not yield the current
contents of buffer
.
Note that dropping the QueueWriteBufferView
does not submit the
transfer to the GPU immediately. The transfer begins only on the next
call to Queue::submit
after the view is dropped. To get a set of
scheduled transfers started immediately, it’s fine to call submit
with
no command buffers at all:
queue.submit([]);
This method fails if size
is greater than the size of buffer
starting at offset
.
Sourcepub fn write_texture(
&self,
texture: ImageCopyTexture<'_>,
data: &[u8],
data_layout: ImageDataLayout,
size: Extent3d,
)
pub fn write_texture( &self, texture: ImageCopyTexture<'_>, data: &[u8], data_layout: ImageDataLayout, size: Extent3d, )
Schedule a write of some data into a texture.
data
contains the texels to be written, which must be in the same format as the texture.data_layout
describes the memory layout ofdata
, which does not necessarily have to have tightly packed rows.texture
specifies the texture to write into, and the location within the texture (coordinate offset, mip level) that will be overwritten.size
is the size, in texels, of the region to be written.
This method fails if size
overruns the size of texture
, or if data
is too short.
This does not submit the transfer to the GPU immediately. Calls to
write_texture
begin execution only on the next call to
Queue::submit
. To get a set of scheduled transfers started
immediately, it’s fine to call submit
with no command buffers at all:
queue.submit([]);
However, data
will be immediately copied into staging memory, so the
caller may discard it any time after this call completes.
Sourcepub fn submit<I: IntoIterator<Item = CommandBuffer>>(
&self,
command_buffers: I,
) -> SubmissionIndex
pub fn submit<I: IntoIterator<Item = CommandBuffer>>( &self, command_buffers: I, ) -> SubmissionIndex
Submits a series of finished command buffers for execution.
Sourcepub fn get_timestamp_period(&self) -> f32
pub fn get_timestamp_period(&self) -> f32
Gets the amount of nanoseconds each tick of a timestamp query represents.
Returns zero if timestamp queries are unsupported.
Timestamp values are represented in nanosecond values on WebGPU, see <https://gpuweb.github.io/gpuweb/#timestamp>
Therefore, this is always 1.0 on the web, but on wgpu-core a manual conversion is required.
Sourcepub fn on_submitted_work_done(&self, callback: impl FnOnce() + Send + 'static)
pub fn on_submitted_work_done(&self, callback: impl FnOnce() + Send + 'static)
Registers a callback when the previous call to submit finishes running on the gpu. This callback being called implies that all mapped buffer callbacks which were registered before this call will have been called.
For the callback to complete, either queue.submit(..)
, instance.poll_all(..)
, or device.poll(..)
must be called elsewhere in the runtime, possibly integrated into an event loop or run on a separate thread.
The callback will be called on the thread that first calls the above functions after the gpu work has completed. There are no restrictions on the code you can run in the callback, however on native the call to the function will not complete until the callback returns, so prefer keeping callbacks short and used to set flags, send messages, etc.