isomesh_gpu/buffers.rs
1//! Getting a field onto the GPU, and results back off it.
2
3use isomesh::Sdf;
4
5use crate::{Error, GridParams, Result};
6
7/// A grid of `f32` field samples in GPU memory, with the grid that describes it.
8///
9/// The two travel together because they are useless apart: a buffer of floats
10/// with no grid cannot be indexed, and a grid with no buffer cannot be sampled.
11/// A shader binds this as `array<f32>` alongside
12/// [`GridParams::to_std140`] as its uniform.
13#[derive(Debug)]
14pub struct FieldBuffer {
15 buffer: wgpu::Buffer,
16 params: GridParams,
17}
18
19impl FieldBuffer {
20 /// Allocate the samples for `params` without writing them.
21 ///
22 /// Usable as a compute *output* — a shader that evaluates the field on the
23 /// GPU writes here — as well as an input. Usage is `STORAGE | COPY_DST |
24 /// COPY_SRC` for exactly that reason: the same buffer is a destination when
25 /// the CPU fills it and a source when [`read_buffer`] takes it back.
26 #[must_use]
27 pub fn new(device: &wgpu::Device, params: GridParams) -> Self {
28 let buffer = device.create_buffer(&wgpu::BufferDescriptor {
29 label: Some("isomesh field samples"),
30 size: params.field_buffer_size(),
31 usage: wgpu::BufferUsages::STORAGE
32 | wgpu::BufferUsages::COPY_DST
33 | wgpu::BufferUsages::COPY_SRC,
34 mapped_at_creation: false,
35 });
36 Self { buffer, params }
37 }
38
39 /// Allocate and write `samples`, in `x`-fastest order.
40 ///
41 /// # The obvious optimisation here is a pessimisation, measured
42 ///
43 /// This builds a `Vec<u8>` and hands it to `write_buffer`, which looks like
44 /// one copy too many. Three variants were measured at 129³ (M-153) and this
45 /// one wins:
46 ///
47 /// | | upload |
48 /// |---|---:|
49 /// | this: `Vec<u8>` + `write_buffer` | **8.40 ms** |
50 /// | `mapped_at_creation` + `write_iter`, no intermediate | 13.47 ms |
51 /// | `mapped_at_creation` + bulk `copy_from_slice` | 8.62 ms |
52 ///
53 /// Per-element writes into a mapping cost **1.6×**, because mapped memory
54 /// may be write-combining — which is exactly why `BufferViewMut` refuses to
55 /// deref to `[u8]`. A bulk memcpy into a mapping ties, so `write_buffer` was
56 /// already doing the efficient thing and there is nothing to reclaim here.
57 ///
58 /// # Errors
59 ///
60 /// [`Error::SampleCountMismatch`] if the slice is not exactly
61 /// [`GridParams::sample_count`] long. A short slice is rejected rather than
62 /// zero-filled and a long one rather than truncated: both repairs produce a
63 /// buffer that looks meshable and describes a different surface.
64 pub fn uploaded(
65 device: &wgpu::Device,
66 queue: &wgpu::Queue,
67 params: GridParams,
68 samples: &[f32],
69 ) -> Result<Self> {
70 let expected = params.sample_count();
71 let got = samples.len() as u64;
72 if got != expected {
73 return Err(Error::SampleCountMismatch { expected, got });
74 }
75 let mut bytes = Vec::with_capacity(samples.len() * 4);
76 for sample in samples {
77 bytes.extend_from_slice(&sample.to_le_bytes());
78 }
79 Ok(Self::from_bytes(device, queue, params, &bytes))
80 }
81
82 /// Allocate and write bytes that are already in the shader's layout.
83 ///
84 /// The one place a `FieldBuffer` is filled, so the descriptor exists once.
85 fn from_bytes(
86 device: &wgpu::Device,
87 queue: &wgpu::Queue,
88 params: GridParams,
89 bytes: &[u8],
90 ) -> Self {
91 let field = Self::new(device, params);
92 queue.write_buffer(&field.buffer, 0, bytes);
93 field
94 }
95
96 /// Sample an `isomesh` field on the CPU and upload the result.
97 ///
98 /// The bridge between the two crates, and the thing that makes a GPU
99 /// extraction comparable to a CPU one: both read the same numbers, so a
100 /// difference in the output is the *algorithm*, which is what GPU-005's
101 /// bit-identity acceptance is about.
102 ///
103 /// # Errors
104 ///
105 /// Propagates [`uploaded`](Self::uploaded)'s, which cannot actually fire
106 /// here — the slice is built from `params` — and is returned rather than
107 /// asserted so this stays one code path with the caller-supplied case.
108 pub fn sampled<F>(
109 device: &wgpu::Device,
110 queue: &wgpu::Queue,
111 params: GridParams,
112 field: &F,
113 ) -> Result<Self>
114 where
115 F: Sdf<Scalar = f32>,
116 {
117 let [sx, sy, sz] = params.samples();
118 // Bytes directly, rather than a `Vec<f32>` that is converted afterwards.
119 // That conversion was a second full pass over 8.4 MB at 129³, 1.14 ms of
120 // a 4.65 ms upload (M-152). Evaluation already touches every sample, so
121 // writing it in the shader's layout here costs nothing extra.
122 let mut bytes = Vec::with_capacity(params.sample_count() as usize * 4);
123 // x fastest, matching GridParams' documented index order.
124 for z in 0..sz {
125 for y in 0..sy {
126 for x in 0..sx {
127 let sample = field.sample(params.sample_position([x, y, z]));
128 bytes.extend_from_slice(&sample.to_le_bytes());
129 }
130 }
131 }
132 Ok(Self::from_bytes(device, queue, params, &bytes))
133 }
134
135 /// The underlying buffer, for binding into a pipeline.
136 #[must_use]
137 pub const fn buffer(&self) -> &wgpu::Buffer {
138 &self.buffer
139 }
140
141 /// The grid these samples describe.
142 #[must_use]
143 pub const fn params(&self) -> GridParams {
144 self.params
145 }
146}
147
148/// Copy `bytes` from `source` back to the CPU as `f32`s.
149///
150/// Blocks until the copy completes. That is the honest signature for what this
151/// does — a caller wanting it off the frame thread runs it off the frame
152/// thread — and it is why nothing here is `async`: read-back needs the device
153/// polled, not an executor, and hiding the wait behind a future would suggest
154/// otherwise.
155///
156/// `source` needs `COPY_SRC`; a staging buffer is created and dropped per call,
157/// which is right for the validation and comparison this is for and wrong for a
158/// per-frame path. When a per-frame path exists it gets a persistent staging
159/// ring, not a flag on this function.
160///
161/// # Errors
162///
163/// [`Error::UnalignedReadback`] if `bytes` is not a multiple of 4,
164/// [`Error::MapFailed`] if the map is refused, [`Error::DeviceLost`] if the
165/// submission never completes.
166pub fn read_buffer(
167 device: &wgpu::Device,
168 queue: &wgpu::Queue,
169 source: &wgpu::Buffer,
170 bytes: u64,
171) -> Result<Vec<f32>> {
172 let raw = read_bytes(device, queue, source, bytes)?;
173 Ok(raw
174 .as_chunks::<4>()
175 .0
176 .iter()
177 .map(|w| f32::from_le_bytes([w[0], w[1], w[2], w[3]]))
178 .collect())
179}
180
181/// The same, as `u32`.
182///
183/// A separate function rather than a generic or a flag: there are exactly two
184/// element types crossing this boundary and naming them is shorter than
185/// abstracting over them.
186///
187/// # Errors
188///
189/// As [`read_buffer`].
190pub fn read_buffer_u32(
191 device: &wgpu::Device,
192 queue: &wgpu::Queue,
193 source: &wgpu::Buffer,
194 bytes: u64,
195) -> Result<Vec<u32>> {
196 let raw = read_bytes(device, queue, source, bytes)?;
197 Ok(raw
198 .as_chunks::<4>()
199 .0
200 .iter()
201 .map(|w| u32::from_le_bytes([w[0], w[1], w[2], w[3]]))
202 .collect())
203}
204
205/// Copy `bytes` from `source` back to the CPU, untyped.
206///
207/// One request through [`read_bytes_many`], which is where the staging/map/poll
208/// dance actually lives.
209///
210/// # Errors
211///
212/// As [`read_buffer`].
213pub fn read_bytes(
214 device: &wgpu::Device,
215 queue: &wgpu::Queue,
216 source: &wgpu::Buffer,
217 bytes: u64,
218) -> Result<Vec<u8>> {
219 let mut out = read_bytes_many(device, queue, &[(source, bytes)])?;
220 match out.pop() {
221 Some(only) => Ok(only),
222 // `read_bytes_many` returns one result per request and it was given one.
223 None => Err(Error::DeviceLost),
224 }
225}
226
227/// Copy several buffers back to the CPU in **one submission and one device
228/// wait**.
229///
230/// The one place that touches a staging buffer, so the map/poll/unmap dance
231/// exists once.
232///
233/// # Why the plural version is the primitive
234///
235/// `device.poll(Wait { submission_index: None })` **drains the entire queue**,
236/// not just the copy that preceded it — so the cost of a read-back is a full
237/// device synchronisation whether it moves four bytes or forty megabytes, and
238/// two read-backs in a row cost two of them for no reason. M-167 measured
239/// synchronisation at 82.6% of this crate's GPU time, which makes the second
240/// drain the expensive part of the operation rather than an detail of it.
241///
242/// Batching is only legal when nothing between the reads consumes a result. A
243/// read-back whose value sizes the next dispatch **cannot** join the batch, and
244/// `extract_buffers` has exactly one of those — the triangle total that sizes
245/// the geometry buffers.
246///
247/// # Errors
248///
249/// [`Error::UnalignedReadback`] if any `bytes` is not a multiple of 4,
250/// [`Error::MapFailed`] if a map is refused, [`Error::DeviceLost`] if the
251/// submission never completes.
252pub fn read_bytes_many(
253 device: &wgpu::Device,
254 queue: &wgpu::Queue,
255 requests: &[(&wgpu::Buffer, u64)],
256) -> Result<Vec<Vec<u8>>> {
257 for (_, bytes) in requests {
258 if !bytes.is_multiple_of(4) {
259 return Err(Error::UnalignedReadback {
260 bytes: *bytes,
261 stride: 4,
262 });
263 }
264 }
265 if requests.is_empty() {
266 return Ok(Vec::new());
267 }
268
269 // **One staging buffer, not one per request.** Peak staging memory is the
270 // same either way -- every copy in a batch has to be resident until the
271 // single wait completes -- but this is one allocation and one map instead of
272 // `n` of each, and the device allocator is the thing being avoided.
273 let total: u64 = requests.iter().map(|(_, bytes)| *bytes).sum();
274 let staging = device.create_buffer(&wgpu::BufferDescriptor {
275 label: Some("isomesh readback"),
276 size: total,
277 usage: wgpu::BufferUsages::MAP_READ | wgpu::BufferUsages::COPY_DST,
278 mapped_at_creation: false,
279 });
280
281 let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
282 label: Some("isomesh readback copy"),
283 });
284 let mut at = 0u64;
285 for (source, bytes) in requests {
286 // Every size is a multiple of 4, checked above, so each offset satisfies
287 // `COPY_BUFFER_ALIGNMENT` by construction rather than by rounding.
288 encoder.copy_buffer_to_buffer(source, 0, &staging, at, *bytes);
289 at += *bytes;
290 }
291 queue.submit(Some(encoder.finish()));
292
293 let (sender, receiver) = std::sync::mpsc::channel();
294 staging
295 .slice(..)
296 .map_async(wgpu::MapMode::Read, move |result| {
297 // A closed channel means the caller is gone, which cannot happen
298 // while this function is on the stack. Dropping the result is the
299 // only thing left to do with it and there is nobody to report to.
300 let _ = sender.send(result);
301 });
302 // `Wait` with no submission index waits for everything queued, and with no
303 // timeout waits indefinitely -- a read-back that gives up early would
304 // return a partially written buffer, which is worse than blocking.
305 device
306 .poll(wgpu::PollType::Wait {
307 submission_index: None,
308 timeout: None,
309 })
310 .map_err(|_| Error::DeviceLost)?;
311
312 match receiver.recv() {
313 Ok(Ok(())) => {}
314 Ok(Err(_)) => return Err(Error::MapFailed),
315 Err(_) => return Err(Error::DeviceLost),
316 }
317
318 let view = staging
319 .slice(..)
320 .get_mapped_range()
321 .map_err(|_| Error::MapFailed)?;
322 let mut out = Vec::with_capacity(requests.len());
323 let mut at = 0usize;
324 for (_, bytes) in requests {
325 let len = usize::try_from(*bytes).map_err(|_| Error::DeviceLost)?;
326 let end = at.checked_add(len).ok_or(Error::DeviceLost)?;
327 let slice = view.get(at..end).ok_or(Error::DeviceLost)?;
328 out.push(slice.to_vec());
329 at = end;
330 }
331 drop(view);
332 staging.unmap();
333 Ok(out)
334}
335
336/// A read-back in flight, with no wait in it.
337///
338/// [`read_bytes_many`] waits on an mpsc channel, which is correct on a native
339/// thread and fatal on the browser's: under WebGPU `Device::poll` is a
340/// documented no-op and `map_async` completes only when control returns to the
341/// event loop, so a thread that blocks on `recv()` is the thread that would have
342/// run the event loop and the tab deadlocks. This is the same staging copy with
343/// the wait taken out -- submit, then ask again next frame.
344///
345/// One frame of latency at best, more under load, and that is the honest shape
346/// of a GPU read-back. [`read_bytes_many`] stays as it is: a native test wants
347/// the answer on the next line, and this is its deferred sibling rather than a
348/// replacement.
349#[derive(Debug)]
350pub struct Readback {
351 /// `None` for an empty request list. A zero-size `wgpu::Buffer` is invalid,
352 /// so the empty case is represented by having no buffer at all rather than
353 /// by a buffer that validation would reject.
354 staging: Option<wgpu::Buffer>,
355 /// 0 pending, 1 mapped, 2 refused. Written once by the `map_async` callback,
356 /// which wgpu may run on any thread, and read by [`Readback::ready`] and
357 /// [`Readback::take`] -- hence the atomic rather than a `Cell`.
358 state: std::sync::Arc<std::sync::atomic::AtomicU8>,
359 /// Byte length per request, in request order, so [`Readback::take`] can
360 /// split the single mapped range back into the buffers that were asked for.
361 spans: Vec<usize>,
362}
363
364/// Copy `requests` into one staging buffer and start mapping it.
365///
366/// The staging allocation, the alignment guard and the copy loop are
367/// [`read_bytes_many`]'s; what is missing is its `poll(Wait)` and its
368/// `recv()`. The caller asks [`Readback::ready`] once a frame and calls
369/// [`Readback::take`] when it says yes.
370///
371/// # Errors
372///
373/// [`Error::UnalignedReadback`] if any `bytes` is not a multiple of 4. Nothing
374/// else can fail here: a map that is refused is reported by
375/// [`Readback::take`], because that is where the caller is asking for the bytes.
376pub fn read_bytes_many_deferred(
377 device: &wgpu::Device,
378 queue: &wgpu::Queue,
379 requests: &[(&wgpu::Buffer, u64)],
380) -> Result<Readback> {
381 for (_, bytes) in requests {
382 if !bytes.is_multiple_of(4) {
383 return Err(Error::UnalignedReadback {
384 bytes: *bytes,
385 stride: 4,
386 });
387 }
388 }
389
390 let state = std::sync::Arc::new(std::sync::atomic::AtomicU8::new(0));
391 if requests.is_empty() {
392 // Nothing to map, so nothing to wait for: mark it done here and the
393 // caller's `ready` loop terminates on its first look, matching
394 // `read_bytes_many`'s empty-input `Ok(Vec::new())`.
395 state.store(1, std::sync::atomic::Ordering::Release);
396 return Ok(Readback {
397 staging: None,
398 state,
399 spans: Vec::new(),
400 });
401 }
402
403 let mut spans = Vec::with_capacity(requests.len());
404 for (_, bytes) in requests {
405 spans.push(usize::try_from(*bytes).map_err(|_| Error::DeviceLost)?);
406 }
407
408 // One staging buffer for the batch, for the reason `read_bytes_many` gives:
409 // peak residency is the same either way and this is one device allocation
410 // and one map instead of `n` of each.
411 let total: u64 = requests.iter().map(|(_, bytes)| *bytes).sum();
412 let staging = device.create_buffer(&wgpu::BufferDescriptor {
413 label: Some("isomesh deferred readback"),
414 size: total,
415 usage: wgpu::BufferUsages::MAP_READ | wgpu::BufferUsages::COPY_DST,
416 mapped_at_creation: false,
417 });
418
419 let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
420 label: Some("isomesh deferred readback copy"),
421 });
422 let mut at = 0u64;
423 for (source, bytes) in requests {
424 // Every size is a multiple of 4, checked above, so each offset satisfies
425 // `COPY_BUFFER_ALIGNMENT` by construction rather than by rounding.
426 encoder.copy_buffer_to_buffer(source, 0, &staging, at, *bytes);
427 at += *bytes;
428 }
429 queue.submit(Some(encoder.finish()));
430
431 let signal = std::sync::Arc::clone(&state);
432 staging
433 .slice(..)
434 .map_async(wgpu::MapMode::Read, move |result| {
435 // `Release` so that a thread which loads 1 or 2 with `Acquire` also
436 // sees the mapped memory the driver wrote before calling this.
437 let code = if result.is_ok() { 1 } else { 2 };
438 signal.store(code, std::sync::atomic::Ordering::Release);
439 });
440
441 Ok(Readback {
442 staging: Some(staging),
443 state,
444 spans,
445 })
446}
447
448impl Readback {
449 /// Whether the mapping has completed. Call once a frame.
450 ///
451 /// Polls with [`wgpu::PollType::Poll`], which is one call site for both
452 /// targets and no `cfg`: on a native backend it is the pump that lets the
453 /// `map_async` callback fire, and under WebGPU it is a documented no-op
454 /// returning `PollStatus::QueueEmpty` because the browser polls for us and
455 /// the callback arrives from the event loop.
456 ///
457 /// The poll result is dropped deliberately. A device that failed to poll
458 /// shows up here as a read-back that never becomes ready, and
459 /// [`Readback::take`] is the one place that reports an error, because it is
460 /// the one place a caller is asking for bytes.
461 #[must_use]
462 pub fn ready(&self, device: &wgpu::Device) -> bool {
463 let _ = device.poll(wgpu::PollType::Poll);
464 self.state.load(std::sync::atomic::Ordering::Acquire) != 0
465 }
466
467 /// The bytes, one `Vec` per request, in request order. Unmaps the staging
468 /// buffer.
469 ///
470 /// # Errors
471 ///
472 /// [`Error::MapFailed`] if the map was refused, [`Error::DeviceLost`] if the
473 /// mapping has not completed -- calling this before [`Readback::ready`]
474 /// returns `true` is the caller's bug, and returning half a buffer would
475 /// hide it.
476 pub fn take(self) -> Result<Vec<Vec<u8>>> {
477 match self.state.load(std::sync::atomic::Ordering::Acquire) {
478 1 => {}
479 2 => return Err(Error::MapFailed),
480 _ => return Err(Error::DeviceLost),
481 }
482 let Some(staging) = self.staging else {
483 // The empty request list, which never had a buffer to map.
484 return Ok(Vec::new());
485 };
486
487 let view = staging
488 .slice(..)
489 .get_mapped_range()
490 .map_err(|_| Error::MapFailed)?;
491 let mut out = Vec::with_capacity(self.spans.len());
492 let mut at = 0usize;
493 for len in &self.spans {
494 let end = at.checked_add(*len).ok_or(Error::DeviceLost)?;
495 let slice = view.get(at..end).ok_or(Error::DeviceLost)?;
496 out.push(slice.to_vec());
497 at = end;
498 }
499 drop(view);
500 staging.unmap();
501 Ok(out)
502 }
503}
504
505/// Several [`Readback`]s in flight at once, keyed by what they are read-backs
506/// *of*, collected in submission order.
507///
508/// # Why this exists, and why it is not a fallback
509///
510/// This crate ships two extraction contracts and this is the third. They differ
511/// in what they guarantee, not in how hard they try:
512///
513/// - [`crate::MarchingCubesGpu::extract_buffers`] — geometry **now**, on the
514/// calling line, at the cost of a wait.
515/// - [`crate::MarchingCubesGpu::extract_indirect`] — geometry **never leaves the
516/// device**; totals become indirect draw arguments and there is no wait at all.
517/// - this — geometry **a frame or two later**, with the wait amortised across
518/// the frames a scheduler was going to run anyway.
519///
520/// A caller picks by requirement: a test wants the first, a renderer that only
521/// draws wants the second, and a collider consumer under a frame budget wants
522/// this. None substitutes for another when it fails.
523///
524/// # Why keyed, rather than a fixed-depth ring
525///
526/// `P-71`'s first arm was a depth-2 ring over one stream of read-backs, and a
527/// ring cannot represent what
528/// [`isomesh::DirtySet::mesh_within_budget`](https://docs.rs/isomesh) does:
529/// it meshes **many chunks in one frame**, a count that changes with the budget
530/// and with how much of the world is dirty. A slot per read-back with the
531/// chunk's own id attached is what lets a frame submit five and collect three,
532/// and it is what makes the collected bytes attributable — geometry that comes
533/// back without saying which chunk it belongs to is geometry a caller cannot
534/// install.
535///
536/// `K` is the caller's key type; `isomesh::ChunkId` is the intended one and
537/// nothing here depends on it.
538#[derive(Debug)]
539pub struct DeferredGeometry<K> {
540 /// One slot per in-flight read-back, `None` when free. `Option` rather than
541 /// a compacting `Vec` because [`Readback::take`] consumes, so a collected
542 /// slot is drained with [`Option::take`] and reused in place.
543 slots: Vec<Option<(K, Readback)>>,
544}
545
546/// **`DeferredGeometry` must stay `Send + Sync`,** and this is the gate.
547///
548/// `bevy_isomesh` holds a `MarchingCubesGpu` as a Bevy `Resource`, which
549/// requires both, so a `Cell` or `RefCell` in anything reachable from it
550/// compiles cleanly *here* and breaks that crate's examples at type-check time.
551/// That already happened once, to `StageTimestamps` — see the comment on its
552/// `next: AtomicU32` field. A plain `Vec<Option<(K, Readback)>>` is sufficient
553/// because [`Readback`] is `Send + Sync` already (an `Arc<AtomicU8>` and `wgpu`
554/// types), and this assertion turns a future interior-mutability field into a
555/// compile error in this crate rather than a failure in another workspace.
556const _: fn() = || {
557 fn assert<T: Send + Sync>() {}
558 assert::<DeferredGeometry<u32>>();
559};
560
561impl<K> DeferredGeometry<K> {
562 /// A queue holding at most `capacity` read-backs in flight.
563 ///
564 /// `capacity` is the collision-latency knob: at 1 a submitted chunk must be
565 /// collected before the next can be submitted, at `n` a burst of `n` chunks
566 /// can be in flight and the last of them is `n` collections away.
567 ///
568 /// # Errors
569 ///
570 /// [`Error::DeferredQueueFull`] with `capacity: 0`. A zero-capacity queue is
571 /// full the moment it exists — every [`DeferredGeometry::submit`] would
572 /// refuse — so it is refused at construction where the caller can see it,
573 /// rather than becoming a scheduler that silently meshes nothing.
574 pub fn new(capacity: usize) -> Result<Self> {
575 if capacity == 0 {
576 return Err(Error::DeferredQueueFull { capacity });
577 }
578 let mut slots = Vec::with_capacity(capacity);
579 slots.resize_with(capacity, || None);
580 Ok(Self { slots })
581 }
582
583 /// Whether another [`DeferredGeometry::submit`] would be accepted.
584 #[must_use]
585 pub fn has_room(&self) -> bool {
586 self.slots.iter().any(Option::is_none)
587 }
588
589 /// Record a read-back that has already been submitted, under `key`.
590 ///
591 /// # Errors
592 ///
593 /// [`Error::DeferredQueueFull`] when `!has_room()`. The read-back is
594 /// returned to the caller as part of nothing — it is dropped, which unmaps
595 /// and frees its staging buffer — so a caller that ignores this error has
596 /// lost that chunk's geometry. Ask [`DeferredGeometry::has_room`] before
597 /// paying for the extraction.
598 pub fn submit(&mut self, key: K, readback: Readback) -> Result<()> {
599 let capacity = self.slots.len();
600 let Some(slot) = self.slots.iter_mut().find(|slot| slot.is_none()) else {
601 return Err(Error::DeferredQueueFull { capacity });
602 };
603 *slot = Some((key, readback));
604 Ok(())
605 }
606
607 /// Every read-back that has completed, in submission order. Call once a
608 /// frame.
609 ///
610 /// A slot that is not ready stays in flight and is offered again next call,
611 /// which is what makes this safe to call unconditionally: the return is the
612 /// frame's harvest and an empty `Vec` means "nothing yet", never "nothing
613 /// ever". Each entry's inner `Vec<Vec<u8>>` is that read-back's requests in
614 /// the order they were asked for, exactly as [`Readback::take`] returns
615 /// them.
616 ///
617 /// Submission order is preserved because slots are filled at the lowest free
618 /// index and scanned in index order, and a slot is only freed by a
619 /// collection — so a chunk submitted before another is never collected after
620 /// it *within one frame*. Across frames the order is the order they became
621 /// ready, which is the driver's.
622 ///
623 /// # Errors
624 ///
625 /// Whatever [`Readback::take`] returns: [`Error::MapFailed`] if a map was
626 /// refused. The failing read-back has already been removed from the queue,
627 /// so a retry is the caller re-extracting that chunk rather than asking
628 /// again — there is nothing left here to ask.
629 pub fn drain_ready(&mut self, device: &wgpu::Device) -> Result<Vec<(K, Vec<Vec<u8>>)>> {
630 let mut out = Vec::new();
631 for slot in &mut self.slots {
632 let ready = slot
633 .as_ref()
634 .is_some_and(|(_, readback)| readback.ready(device));
635 if !ready {
636 continue;
637 }
638 // `take` on both: `Readback::take` consumes, and the slot has to be
639 // freed whether the take succeeds or not -- a slot holding a refused
640 // map would be retried forever and never become ready.
641 let (key, readback) = slot.take().expect("checked above");
642 out.push((key, readback.take()?));
643 }
644 Ok(out)
645 }
646
647 /// Read-backs submitted and not yet collected.
648 #[must_use]
649 pub fn in_flight(&self) -> usize {
650 self.slots.iter().filter(|slot| slot.is_some()).count()
651 }
652
653 /// The `capacity` this was built with.
654 #[must_use]
655 pub fn capacity(&self) -> usize {
656 self.slots.len()
657 }
658}
659
660#[cfg(test)]
661mod tests;