Struct wgpu::Queue

source ·
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

source

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.

source

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.

source

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 of data, 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.

source

pub fn submit<I: IntoIterator<Item = CommandBuffer>>( &self, command_buffers: I ) -> SubmissionIndex

Submits a series of finished command buffers for execution.

source

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.

source

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.

source§

impl Queue

source

pub fn global_id(&self) -> Id<Self>

Returns a globally-unique identifier for this Queue.

Calling this method multiple times on the same object will always return the same value. The returned value is guaranteed to be different for all resources created from the same Instance.

Trait Implementations§

source§

impl Debug for Queue

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

impl Drop for Queue

source§

fn drop(&mut self)

Executes the destructor for this type. Read more

Auto Trait Implementations§

§

impl !RefUnwindSafe for Queue

§

impl Send for Queue

§

impl Sync for Queue

§

impl Unpin for Queue

§

impl !UnwindSafe for Queue

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<T> Downcast<T> for T

§

fn downcast(&self) -> &T

source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<T> Upcast<T> for T

§

fn upcast(&self) -> Option<&T>

§

impl<T> WasmNotSend for T
where T: Send,

§

impl<T> WasmNotSendSync for T

§

impl<T> WasmNotSync for T
where T: Sync,