Skip to main content

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;