wgpu/api/
queue.rs

1use alloc::boxed::Box;
2use core::ops::{Deref, DerefMut};
3
4use crate::{api::DeferredCommandBufferActions, *};
5
6/// Handle to a command queue on a device.
7///
8/// A `Queue` executes recorded [`CommandBuffer`] objects and provides convenience methods
9/// for writing to [buffers](Queue::write_buffer) and [textures](Queue::write_texture).
10/// It can be created along with a [`Device`] by calling [`Adapter::request_device`].
11///
12/// Corresponds to [WebGPU `GPUQueue`](https://gpuweb.github.io/gpuweb/#gpu-queue).
13#[derive(Debug, Clone)]
14pub struct Queue {
15    pub(crate) inner: dispatch::DispatchQueue,
16}
17#[cfg(send_sync)]
18static_assertions::assert_impl_all!(Queue: Send, Sync);
19
20crate::cmp::impl_eq_ord_hash_proxy!(Queue => .inner);
21
22impl Queue {
23    #[cfg(custom)]
24    /// Returns custom implementation of Queue (if custom backend and is internally T)
25    pub fn as_custom<T: custom::QueueInterface>(&self) -> Option<&T> {
26        self.inner.as_custom()
27    }
28
29    #[cfg(custom)]
30    /// Creates Queue from custom implementation
31    pub fn from_custom<T: custom::QueueInterface>(queue: T) -> Self {
32        Self {
33            inner: dispatch::DispatchQueue::custom(queue),
34        }
35    }
36}
37
38/// Identifier for a particular call to [`Queue::submit`]. Can be used
39/// as part of an argument to [`Device::poll`] to block for a particular
40/// submission to finish.
41///
42/// This type is unique to the Rust API of `wgpu`.
43/// There is no analogue in the WebGPU specification.
44#[derive(Debug, Clone)]
45pub struct SubmissionIndex {
46    pub(crate) index: u64,
47}
48#[cfg(send_sync)]
49static_assertions::assert_impl_all!(SubmissionIndex: Send, Sync);
50
51/// Passed to [`Device::poll`] to control how and if it should block.
52pub type PollType = wgt::PollType<SubmissionIndex>;
53#[cfg(send_sync)]
54static_assertions::assert_impl_all!(PollType: Send, Sync);
55
56/// A write-only view into a staging buffer.
57///
58/// Reading into this buffer won't yield the contents of the buffer from the
59/// GPU and is likely to be slow. Because of this, although [`AsMut`] is
60/// implemented for this type, [`AsRef`] is not.
61pub struct QueueWriteBufferView {
62    queue: Queue,
63    buffer: Buffer,
64    offset: BufferAddress,
65    inner: dispatch::DispatchQueueWriteBuffer,
66}
67#[cfg(send_sync)]
68static_assertions::assert_impl_all!(QueueWriteBufferView: Send, Sync);
69
70impl QueueWriteBufferView {
71    #[cfg(custom)]
72    /// Returns custom implementation of QueueWriteBufferView (if custom backend and is internally T)
73    pub fn as_custom<T: custom::QueueWriteBufferInterface>(&self) -> Option<&T> {
74        self.inner.as_custom()
75    }
76}
77
78impl Deref for QueueWriteBufferView {
79    type Target = [u8];
80
81    fn deref(&self) -> &Self::Target {
82        log::warn!("Reading from a QueueWriteBufferView won't yield the contents of the buffer and may be slow.");
83        self.inner.slice()
84    }
85}
86
87impl DerefMut for QueueWriteBufferView {
88    fn deref_mut(&mut self) -> &mut Self::Target {
89        self.inner.slice_mut()
90    }
91}
92
93impl AsMut<[u8]> for QueueWriteBufferView {
94    fn as_mut(&mut self) -> &mut [u8] {
95        self.inner.slice_mut()
96    }
97}
98
99impl Drop for QueueWriteBufferView {
100    fn drop(&mut self) {
101        self.queue
102            .inner
103            .write_staging_buffer(&self.buffer.inner, self.offset, &self.inner);
104    }
105}
106
107impl Queue {
108    /// Copies the bytes of `data` into `buffer` starting at `offset`.
109    ///
110    /// The data must be written fully in-bounds, that is, `offset + data.len() <= buffer.len()`.
111    ///
112    /// # Performance considerations
113    ///
114    /// * Calls to `write_buffer()` do *not* submit the transfer to the GPU
115    ///   immediately. They begin GPU execution only on the next call to
116    ///   [`Queue::submit()`], just before the explicitly submitted commands.
117    ///   To get a set of scheduled transfers started immediately,
118    ///   it's fine to call `submit` with no command buffers at all:
119    ///
120    ///   ```no_run
121    ///   # let queue: wgpu::Queue = todo!();
122    ///   # let buffer: wgpu::Buffer = todo!();
123    ///   # let data = [0u8];
124    ///   queue.write_buffer(&buffer, 0, &data);
125    ///   queue.submit([]);
126    ///   ```
127    ///
128    ///   However, `data` will be immediately copied into staging memory, so the
129    ///   caller may discard it any time after this call completes.
130    ///
131    /// * Consider using [`Queue::write_buffer_with()`] instead.
132    ///   That method allows you to prepare your data directly within the staging
133    ///   memory, rather than first placing it in a separate `[u8]` to be copied.
134    ///   That is, `queue.write_buffer(b, offset, data)` is approximately equivalent
135    ///   to `queue.write_buffer_with(b, offset, data.len()).copy_from_slice(data)`,
136    ///   so use `write_buffer_with()` if you can do something smarter than that
137    ///   [`copy_from_slice()`](slice::copy_from_slice). However, for small values
138    ///   (e.g. a typical uniform buffer whose contents come from a `struct`),
139    ///   there will likely be no difference, since the compiler will be able to
140    ///   optimize out unnecessary copies regardless.
141    ///
142    /// * Currently on native platforms, for both of these methods, the staging
143    ///   memory will be a new allocation. This will then be released after the
144    ///   next submission finishes. To entirely avoid short-lived allocations, you might
145    ///   be able to use [`StagingBelt`](crate::util::StagingBelt),
146    ///   or buffers you explicitly create, map, and unmap yourself.
147    pub fn write_buffer(&self, buffer: &Buffer, offset: BufferAddress, data: &[u8]) {
148        self.inner.write_buffer(&buffer.inner, offset, data);
149    }
150
151    /// Prepares to write data to a buffer via a mapped staging buffer.
152    ///
153    /// This operation allocates a temporary buffer and then returns a
154    /// [`QueueWriteBufferView`], which
155    ///
156    /// * dereferences to a `[u8]` of length `size`, and
157    /// * when dropped, schedules a copy of its contents into `buffer` at `offset`.
158    ///
159    /// Therefore, this obtains the same result as [`Queue::write_buffer()`], but may
160    /// allow you to skip one allocation and one copy of your data, if you are able to
161    /// assemble your data directly into the returned [`QueueWriteBufferView`] instead of
162    /// into a separate allocation like a [`Vec`](alloc::vec::Vec) first.
163    ///
164    /// The data must be written fully in-bounds, that is, `offset + size <= buffer.len()`.
165    ///
166    /// # Performance considerations
167    ///
168    /// * For small data not separately heap-allocated, there is no advantage of this
169    ///   over [`Queue::write_buffer()`].
170    ///
171    /// * Reading from the returned view may be slow, and will not yield the current
172    ///   contents of `buffer`. You should treat it as “write-only”.
173    ///
174    /// * Dropping the [`QueueWriteBufferView`] does *not* submit the
175    ///   transfer to the GPU immediately. The transfer begins only on the next
176    ///   call to [`Queue::submit()`] after the view is dropped, just before the
177    ///   explicitly submitted commands. To get a set of scheduled transfers started
178    ///   immediately, it's fine to call `queue.submit([])` with no command buffers at all.
179    ///
180    /// * Currently on native platforms, the staging memory will be a new allocation, which will
181    ///   then be released after the next submission finishes. To entirely avoid short-lived
182    ///   allocations, you might be able to use [`StagingBelt`](crate::util::StagingBelt),
183    ///   or buffers you explicitly create, map, and unmap yourself.
184    #[must_use]
185    pub fn write_buffer_with(
186        &self,
187        buffer: &Buffer,
188        offset: BufferAddress,
189        size: BufferSize,
190    ) -> Option<QueueWriteBufferView> {
191        profiling::scope!("Queue::write_buffer_with");
192        self.inner
193            .validate_write_buffer(&buffer.inner, offset, size)?;
194        let staging_buffer = self.inner.create_staging_buffer(size)?;
195        Some(QueueWriteBufferView {
196            queue: self.clone(),
197            buffer: buffer.clone(),
198            offset,
199            inner: staging_buffer,
200        })
201    }
202
203    /// Copies the bytes of `data` into into a texture.
204    ///
205    /// * `data` contains the texels to be written, which must be in
206    ///   [the same format as the texture](TextureFormat).
207    /// * `data_layout` describes the memory layout of `data`, which does not necessarily
208    ///   have to have tightly packed rows.
209    /// * `texture` specifies the texture to write into, and the location within the
210    ///   texture (coordinate offset, mip level) that will be overwritten.
211    /// * `size` is the size, in texels, of the region to be written.
212    ///
213    /// This method fails if `size` overruns the size of `texture`, or if `data` is too short.
214    ///
215    /// # Performance considerations
216    ///
217    /// This operation has the same performance considerations as [`Queue::write_buffer()`];
218    /// see its documentation for details.
219    ///
220    /// However, since there is no “mapped texture” like a mapped buffer,
221    /// alternate techniques for writing to textures will generally consist of first copying
222    /// the data to a buffer, then using [`CommandEncoder::copy_buffer_to_texture()`], or in
223    /// some cases a compute shader, to copy texels from that buffer to the texture.
224    pub fn write_texture(
225        &self,
226        texture: TexelCopyTextureInfo<'_>,
227        data: &[u8],
228        data_layout: TexelCopyBufferLayout,
229        size: Extent3d,
230    ) {
231        self.inner.write_texture(texture, data, data_layout, size);
232    }
233
234    /// Schedule a copy of data from `image` into `texture`.
235    #[cfg(web)]
236    pub fn copy_external_image_to_texture(
237        &self,
238        source: &wgt::CopyExternalImageSourceInfo,
239        dest: wgt::CopyExternalImageDestInfo<&api::Texture>,
240        size: Extent3d,
241    ) {
242        self.inner
243            .copy_external_image_to_texture(source, dest, size);
244    }
245
246    /// Submits a series of finished command buffers for execution.
247    pub fn submit<I: IntoIterator<Item = CommandBuffer>>(
248        &self,
249        command_buffers: I,
250    ) -> SubmissionIndex {
251        // As submit drains the iterator (even on error), collect deferred actions
252        // from each CommandBuffer along the way.
253        let mut actions = DeferredCommandBufferActions::default();
254
255        let mut command_buffers = command_buffers.into_iter().map(|comb| {
256            actions.append(&mut comb.actions.lock());
257            comb.buffer
258        });
259        let index = self.inner.submit(&mut command_buffers);
260
261        // Execute all deferred actions after submit.
262        actions.execute(&self.inner);
263
264        SubmissionIndex { index }
265    }
266
267    /// Gets the amount of nanoseconds each tick of a timestamp query represents.
268    ///
269    /// Returns zero if timestamp queries are unsupported.
270    ///
271    /// Timestamp values are represented in nanosecond values on WebGPU, see `<https://gpuweb.github.io/gpuweb/#timestamp>`
272    /// Therefore, this is always 1.0 on the web, but on wgpu-core a manual conversion is required.
273    pub fn get_timestamp_period(&self) -> f32 {
274        self.inner.get_timestamp_period()
275    }
276
277    /// Registers a callback that is invoked when the previous [`Queue::submit`] finishes executing
278    /// on the GPU. When this callback runs, all mapped-buffer callbacks registered for the same
279    /// submission are guaranteed to have been called.
280    ///
281    /// For the callback to run, either [`queue.submit(..)`][q::s], [`instance.poll_all(..)`][i::p_a],
282    /// or [`device.poll(..)`][d::p] must be called elsewhere in the runtime, possibly integrated into
283    /// an event loop or run on a separate thread.
284    ///
285    /// The callback runs on the thread that first calls one of the above functions after the GPU work
286    /// completes. There are no restrictions on the code you can run in the callback; however, on native
287    /// the polling call will not return until the callback finishes, so keep callbacks short (set flags,
288    /// send messages, etc.).
289    ///
290    /// [q::s]: Queue::submit
291    /// [i::p_a]: Instance::poll_all
292    /// [d::p]: Device::poll
293    pub fn on_submitted_work_done(&self, callback: impl FnOnce() + Send + 'static) {
294        self.inner.on_submitted_work_done(Box::new(callback));
295    }
296
297    /// Get the [`wgpu_hal`] device from this `Queue`.
298    ///
299    /// Find the Api struct corresponding to the active backend in [`wgpu_hal::api`],
300    /// and pass that struct to the to the `A` type parameter.
301    ///
302    /// Returns a guard that dereferences to the type of the hal backend
303    /// which implements [`A::Queue`].
304    ///
305    /// # Types
306    ///
307    /// The returned type depends on the backend:
308    ///
309    #[doc = crate::hal_type_vulkan!("Queue")]
310    #[doc = crate::hal_type_metal!("Queue")]
311    #[doc = crate::hal_type_dx12!("Queue")]
312    #[doc = crate::hal_type_gles!("Queue")]
313    ///
314    /// # Errors
315    ///
316    /// This method will return None if:
317    /// - The queue is not from the backend specified by `A`.
318    /// - The queue is from the `webgpu` or `custom` backend.
319    ///
320    /// # Safety
321    ///
322    /// - The returned resource must not be destroyed unless the guard
323    ///   is the last reference to it and it is not in use by the GPU.
324    ///   The guard and handle may be dropped at any time however.
325    /// - All the safety requirements of wgpu-hal must be upheld.
326    ///
327    /// [`A::Queue`]: hal::Api::Queue
328    #[cfg(wgpu_core)]
329    pub unsafe fn as_hal<A: hal::Api>(
330        &self,
331    ) -> Option<impl Deref<Target = A::Queue> + WasmNotSendSync> {
332        let queue = self.inner.as_core_opt()?;
333        unsafe { queue.context.queue_as_hal::<A>(queue) }
334    }
335
336    /// Compact a BLAS, it must have had [`Blas::prepare_compaction_async`] called on it and had the
337    /// callback provided called.
338    ///
339    /// The returned BLAS is more restricted than a normal BLAS because it may not be rebuilt or
340    /// compacted.
341    pub fn compact_blas(&self, blas: &Blas) -> Blas {
342        let (handle, dispatch) = self.inner.compact_blas(&blas.inner);
343        Blas {
344            handle,
345            inner: dispatch,
346        }
347    }
348}