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}