diff --git a/quest/m1/README.md b/quest/m1/README.md index ebc75594efe..b92219bd314 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -55,7 +55,6 @@ the same reason, gates the cut through the - [Vendor and trim the WebRTC stack](/quest/m1/webrtc-vendor.md) - str0m, dimpl, `is`, and sctp-proto live in moq-webrtc with unused code removed, so moq-rtc can take rind - [MoQ on rind](/quest/m1/rind/README.md) - every MoQ crate takes its crypto from rind, a pure-Rust graviola fork, so no build compiles C crypto - [VAAPI encode and decode](/quest/m1/video-vaapi.md) - H.265 encode and decode, pre-generated bindings, and pooled resize surfaces, including the moq-dev/vaapi release that carries them -- [Read a texture back without an encoder](/quest/m1/video-readback.md) - moq-video copies a wgpu texture into packed RGBA with no encoder probe, for the studio's Linux virtual camera - [The over-limit PUBLISH refusal invites a retry](/quest/m1/retry-interval-overload.md) - `EXCESSIVE_LOAD` sends the may-pass retry interval, not 0 - [A relay forwards an upstream refusal's retry interval](/quest/m1/retry-interval-forward.md) - a forwarded SUBSCRIBE refusal keeps the upstream's retry interval - [Tests run on a mocked clock](/quest/m1/mock-clock-tests/README.md) - about 300 tests stop proving nothing happened by waiting, sleeping to settle, or asserting on elapsed time diff --git a/quest/m1/video-readback.md b/quest/m1/video-readback.md deleted file mode 100644 index af311c27846..00000000000 --- a/quest/m1/video-readback.md +++ /dev/null @@ -1,30 +0,0 @@ -# [S] Read a texture back without an encoder - -## Goal - -moq-video exposes a public readback that copies a wgpu texture into tightly -packed RGBA rows on the CPU with no encoder behind it, so a consumer that -needs the raw picture reuses the export path's staging buffers, row -unpadding, and mapping lifecycle instead of copying them. A moq-side test -covers it. - -## Plan - -Decided 2026-11-05 (maintainer, on moq-dev/studio's /quest-plan): the -studio's [Linux virtual camera](https://github.com/moq-dev/studio/blob/main/quest/m0/vcam/linux.md) -([moq-dev/studio#9](https://github.com/moq-dev/studio/pull/9)) reads the -program through this readback rather than a copy of it in the studio, and the -work joins m1 because it is additive and that camera has waited on it since -2026-11-02. The studio bumps its pin in -[its own quest](https://github.com/moq-dev/studio/blob/main/quest/m0/pin-readback.md). - -The readback exists: `render/export.rs`'s private `Readback` and its test -`readback_round_trips_and_drops_past_its_depth`. Today it is reachable only -through `Exporter`, whose setup probes for an encoder. Make that type public -and keep one implementation, so `Exporter`'s CPU route still reads through it. - -Recommendation, not settled: mirror `Exporter`'s shape, a non-blocking copy -that drops past its depth and returns a pending handle whose wait yields the -RGBA bytes, named by role under `render`. Refuse a texture whose size or -format does not match, as `Exporter::copy` does. Add a `MIGRATE.md` note -under `## Unreleased`. diff --git a/rs/justfile b/rs/justfile index 6b3f5b8e152..40071ca2224 100644 --- a/rs/justfile +++ b/rs/justfile @@ -446,7 +446,7 @@ render-sw: -E 'test(/^render::renderer::tests::(the_declared_color_space_beats_the_size_guess|cpu_frames_survive_the_round_trip|config_size_overrides_the_frame_size|an_unimportable_gpu_frame_is_refused|the_output_follows_the_device)$/)' # Mesa's software driver exports no memory, so this covers the readback route. LD_LIBRARY_PATH="$loader/lib" VK_DRIVER_FILES="${icd[0]}" \ - just rs test -p moq-video --features render,openh264 --lib --run-ignored only -E 'test(/^render::export::(nv12::)?tests::/)' + just rs test -p moq-video --features render,openh264 --lib --run-ignored only -E 'test(/^render::(readback::|export::(nv12::)?)tests::/)' # Run the ignored mDNS tests, which multicast on the host's network interfaces. multicast: diff --git a/rs/moq-video/src/convert.rs b/rs/moq-video/src/convert.rs index 9bb8c00a3b3..e2a774edb4b 100644 --- a/rs/moq-video/src/convert.rs +++ b/rs/moq-video/src/convert.rs @@ -44,6 +44,17 @@ pub struct Rgba { } impl Rgba { + /// Wrap tightly packed `size` RGBA8 pixels. + #[cfg(feature = "render")] + pub(crate) fn new(size: Size, data: Vec) -> Self { + debug_assert_eq!(data.len(), size.width as usize * size.height as usize * 4); + Self { + size, + stride: size.width as usize * 4, + data, + } + } + /// Image dimensions in pixels. pub fn size(&self) -> Size { self.size diff --git a/rs/moq-video/src/render/export.rs b/rs/moq-video/src/render/export.rs index f51c6ab5c96..3958acb7e9a 100644 --- a/rs/moq-video/src/render/export.rs +++ b/rs/moq-video/src/render/export.rs @@ -21,18 +21,17 @@ //! Foundation hardware encoder reads it directly. //! //! Every other encoder reads frames on the CPU, so it takes -//! [`Route::Readback`]: each slot is a staging buffer and the frame is read back -//! as I420. An encoder never switches routes. Choosing among encoders passes over +//! [`Route::Readback`]: each copy goes through a [`Readback`] and the frame is +//! converted to I420. An encoder never switches routes. Choosing among encoders passes over //! one that cannot read this device's surface (NVENC with the device on another //! GPU), but one asked for by name fails [`Exporter::new`] instead, and a copy //! that fails on the GPU is an error. // The variants are deliberately not doc links: each exists on one platform, so // a link fails the `-D warnings` rustdoc build on every other. -use std::sync::{Arc, Mutex}; - use moq_net::Timestamp; +use super::readback::{self, Readback, extent, finish}; use crate::{Error, Frame, Size, Surface}; #[cfg(target_os = "windows")] @@ -86,9 +85,9 @@ enum Slots { } impl Exporter { - /// Copies in flight at once: one being encoded, one being copied, and one - /// spare so a slow encode does not drop the very next picture. - pub const DEPTH: usize = 3; + /// Copies in flight at once, as many as a [`Readback`] holds: one being + /// encoded, one being copied, and one spare. + pub const DEPTH: usize = Readback::DEPTH; /// Export textures drawn on `device` to an encoder `config` allows, and /// return the rendition it produces. @@ -226,7 +225,7 @@ impl Exporter { fn open(device: &wgpu::Device, queue: &wgpu::Queue, size: Size, route: Route) -> Result { size.validate_nonzero("export")?; let slots = match route { - Route::Readback => Slots::Readback(Readback::new(device, queue, size)), + Route::Readback => Slots::Readback(Readback::new(device, queue, size)?), #[cfg(target_os = "linux")] Route::Gpu => Slots::Vulkan(Box::new(vulkan::Export::open(device, queue, size)?)), #[cfg(apple)] @@ -275,23 +274,14 @@ impl Exporter { /// `None` when every slot is still held by an earlier [`Pending`] or by the /// encoder. pub fn copy(&mut self, texture: &wgpu::Texture, timestamp: Timestamp) -> Result, Error> { - let size = Size::new(texture.width(), texture.height()); - if size != self.size || texture.format() != wgpu::TextureFormat::Rgba8Unorm { - return Err(Error::Unsupported(format!( - "cannot export a {size} {:?} texture; expected {} Rgba8Unorm", - texture.format(), - self.size - ))); - } - let usage = wgpu::TextureUsages::COPY_SRC | wgpu::TextureUsages::TEXTURE_BINDING; - if !texture.usage().contains(usage) { - return Err(Error::Unsupported(format!( - "cannot export a texture created without {usage:?}" - ))); - } + readback::check( + texture, + self.size, + wgpu::TextureUsages::COPY_SRC | wgpu::TextureUsages::TEXTURE_BINDING, + )?; let wait = match &mut self.slots { - Slots::Readback(readback) => readback.copy(texture).map(Wait::Readback), + Slots::Readback(readback) => readback.copy(texture)?.map(Wait::Readback), #[cfg(target_os = "linux")] Slots::Vulkan(export) => export.copy(texture)?.map(Wait::Vulkan), #[cfg(apple)] @@ -315,7 +305,7 @@ pub struct Pending { } enum Wait { - Readback(Staged), + Readback(readback::Pending), #[cfg(target_os = "linux")] Vulkan(vulkan::Copy), #[cfg(apple)] @@ -328,7 +318,10 @@ impl Pending { /// Block until the copy lands, then hand back the frame for an encoder. pub fn wait(self) -> Result { let surface = match self.wait { - Wait::Readback(staged) => staged.wait(&self.device)?, + Wait::Readback(pending) => { + let rgba = pending.wait()?; + Surface::rgba(rgba.data(), rgba.size())? + } #[cfg(target_os = "linux")] Wait::Vulkan(copy) => copy.wait(&self.device)?, #[cfg(apple)] @@ -345,165 +338,8 @@ impl Pending { } } -/// Block until `submission` has finished on the GPU. -fn finish(device: &wgpu::Device, submission: wgpu::SubmissionIndex) -> Result<(), Error> { - device - .poll(wgpu::PollType::Wait { - submission_index: Some(submission), - timeout: None, - }) - .map_err(|e| err(format!("waiting for the export copy: {e}")))?; - Ok(()) -} - -/// The CPU route: copies into a pool of staging buffers, read back as I420. -struct Readback { - device: wgpu::Device, - queue: wgpu::Queue, - size: Size, - /// Bytes per row in a staging buffer, padded to the copy alignment. - row: u32, - pool: Arc>, -} - -/// Staging buffers not held by a [`Staged`]. -#[derive(Default)] -struct Buffers { - free: Vec, - /// Buffers in existence, up to [`Exporter::DEPTH`]. - allocated: usize, -} - -impl Readback { - fn new(device: &wgpu::Device, queue: &wgpu::Queue, size: Size) -> Self { - Self { - device: device.clone(), - queue: queue.clone(), - size, - row: (size.width * 4).next_multiple_of(wgpu::COPY_BYTES_PER_ROW_ALIGNMENT), - pool: Arc::default(), - } - } - - fn copy(&mut self, texture: &wgpu::Texture) -> Option { - let mut pool = self.pool.lock().unwrap(); - let buffer = match pool.free.pop() { - Some(buffer) => buffer, - None if pool.allocated < Exporter::DEPTH => { - pool.allocated += 1; - self.device.create_buffer(&wgpu::BufferDescriptor { - label: Some("moq-video export readback"), - size: u64::from(self.row) * u64::from(self.size.height), - usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ, - mapped_at_creation: false, - }) - } - None => return None, - }; - drop(pool); - - let mut encoder = self.device.create_command_encoder(&wgpu::CommandEncoderDescriptor { - label: Some("moq-video export readback"), - }); - encoder.copy_texture_to_buffer( - texture.as_image_copy(), - wgpu::TexelCopyBufferInfo { - buffer: &buffer, - layout: wgpu::TexelCopyBufferLayout { - offset: 0, - bytes_per_row: Some(self.row), - rows_per_image: Some(self.size.height), - }, - }, - extent(self.size), - ); - let submission = self.queue.submit([encoder.finish()]); - - Some(Staged { - buffer: Some(buffer), - submission, - size: self.size, - row: self.row, - pool: self.pool.clone(), - mapping: false, - }) - } -} - -/// One readback in flight. Dropping it returns its buffer to the pool. -struct Staged { - buffer: Option, - submission: wgpu::SubmissionIndex, - size: Size, - row: u32, - pool: Arc>, - /// Set while a mapping was requested and not yet undone, so a wait that - /// failed partway does not hand a mapped buffer to the next copy. - mapping: bool, -} - -impl Staged { - fn wait(mut self, device: &wgpu::Device) -> Result { - let rgba = self.rgba(device)?; - Surface::rgba(&rgba, self.size) - } - - /// Block until the copy lands, then hand back tightly packed RGBA rows. - fn rgba(&mut self, device: &wgpu::Device) -> Result, Error> { - let buffer = self.buffer.as_ref().expect("held until drop"); - let (send, recv) = std::sync::mpsc::channel(); - self.mapping = true; - buffer.map_async(wgpu::MapMode::Read, .., move |result| { - let _ = send.send(result); - }); - finish(device, self.submission.clone())?; - recv.recv() - .map_err(|_| err("the readback was dropped"))? - .map_err(|e| err(format!("mapping the readback: {e}")))?; - - let width = self.size.width as usize * 4; - let mut rgba = Vec::with_capacity(width * self.size.height as usize); - { - let mapped = buffer - .slice(..) - .get_mapped_range() - .map_err(|e| err(format!("reading the readback: {e}")))?; - for row in mapped.chunks_exact(self.row as usize) { - rgba.extend_from_slice(&row[..width]); - } - } - buffer.unmap(); - self.mapping = false; - Ok(rgba) - } -} - -impl Drop for Staged { - fn drop(&mut self) { - let Some(buffer) = self.buffer.take() else { - return; - }; - let mut pool = self.pool.lock().unwrap(); - // The pool only holds buffers the next copy can write. One a failed wait - // left mapped, or waiting on a mapping, is let go and replaced. - if self.mapping { - pool.allocated -= 1; - } else { - pool.free.push(buffer); - } - } -} - -fn extent(size: Size) -> wgpu::Extent3d { - wgpu::Extent3d { - width: size.width, - height: size.height, - depth_or_array_layers: 1, - } -} - /// A `size` texture an exporter takes, filled with `rgba` in every pixel. -fn texture(device: &wgpu::Device, queue: &wgpu::Queue, size: Size, rgba: [u8; 4]) -> wgpu::Texture { +pub(super) fn texture(device: &wgpu::Device, queue: &wgpu::Queue, size: Size, rgba: [u8; 4]) -> wgpu::Texture { let texture = device.create_texture(&wgpu::TextureDescriptor { label: Some("moq-video export"), size: extent(size), @@ -669,14 +505,6 @@ pub(crate) mod tests { ) } - /// Tightly packed RGBA rows of a `COPY_SRC` texture. - #[cfg(target_os = "linux")] - pub(crate) fn pixels(device: &wgpu::Device, queue: &wgpu::Queue, texture: &wgpu::Texture) -> Vec { - let size = Size::new(texture.width(), texture.height()); - let mut readback = Readback::new(device, queue, size); - readback.copy(texture).unwrap().rgba(device).unwrap() - } - /// The center pixel of `frame`, read on the CPU. pub(crate) fn center(frame: &Frame) -> [u8; 4] { let size = frame.size(); @@ -690,11 +518,11 @@ pub(crate) mod tests { actual.iter().zip(expected).all(|(a, e)| a.abs_diff(e) <= 24) } - /// A readback hands back what was drawn, and drops copies past its depth - /// rather than queuing them. + /// The readback route hands back what was drawn as I420, and drops copies + /// past its depth rather than queuing them. #[tokio::test] #[ignore = "needs a GPU; run by just rs render-sw"] - async fn readback_round_trips_and_drops_past_its_depth() { + async fn the_readback_route_hands_back_i420() { let (device, queue) = gpu().await.expect("a GPU adapter"); let size = Size::new(64, 32); let red = texture(&device, &queue, size, [255, 0, 0, 255]); @@ -711,7 +539,6 @@ pub(crate) mod tests { assert!(matches!(frame.surface, Surface::I420(_))); let actual = center(&frame); assert!(near(actual, [255, 0, 0, 255]), "{actual:?}"); - assert!(exporter.copy(&red, Timestamp::ZERO).unwrap().is_some()); } /// The exporter takes the route the encoder it probed reads: GPU frames @@ -809,14 +636,4 @@ pub(crate) mod tests { }; assert!(matches!(err, Error::Unsupported(_)), "{err}"); } - - /// A texture of another size or format is refused rather than misread. - #[tokio::test] - #[ignore = "needs a GPU; run by just rs render-sw"] - async fn refuses_a_mismatched_texture() { - let (device, queue) = gpu().await.expect("a GPU adapter"); - let mut exporter = Exporter::open(&device, &queue, Size::new(64, 32), Route::Readback).unwrap(); - let other = texture(&device, &queue, Size::new(32, 32), [0; 4]); - assert!(exporter.copy(&other, Timestamp::ZERO).is_err()); - } } diff --git a/rs/moq-video/src/render/export/vulkan.rs b/rs/moq-video/src/render/export/vulkan.rs index fd75f6f77ea..b3aaa78a14d 100644 --- a/rs/moq-video/src/render/export/vulkan.rs +++ b/rs/moq-video/src/render/export/vulkan.rs @@ -601,7 +601,7 @@ mod tests { use moq_net::Timestamp; - use super::super::tests::{gpu, pixels}; + use super::super::tests::gpu; use super::super::texture; use super::super::{Exporter, Route}; use super::*; @@ -836,7 +836,9 @@ mod tests { pass.dispatch_workgroups(contract.size.width.div_ceil(8), contract.size.height.div_ceil(8), 1); } queue.submit([encoder.finish()]); - pixels(device, queue, &plain) + let size = Size::new(plain.width(), plain.height()); + let mut readback = crate::render::readback::Readback::new(device, queue, size).unwrap(); + readback.copy(&plain).unwrap().unwrap().wait().unwrap().into_data() } } } diff --git a/rs/moq-video/src/render/mod.rs b/rs/moq-video/src/render/mod.rs index 900ad7279b1..f9e56fc77cb 100644 --- a/rs/moq-video/src/render/mod.rs +++ b/rs/moq-video/src/render/mod.rs @@ -45,13 +45,16 @@ //! //! [`export`] runs the other way, handing a texture you drew to an encoder as a //! [`Frame`](crate::Frame): on the GPU when the encoder reads this platform's -//! GPU surface, read back to the CPU when it does not. +//! GPU surface, read back to the CPU when it does not. [`readback`] is that +//! read back on its own, for a consumer that wants the picture's RGBA pixels +//! with no encoder behind it. //! //! Enabled by the non-default `render` feature, which is what pulls in `wgpu`. mod color; mod device; pub mod export; +pub mod readback; mod renderer; mod source; diff --git a/rs/moq-video/src/render/readback.rs b/rs/moq-video/src/render/readback.rs new file mode 100644 index 00000000000..440d5d24a95 --- /dev/null +++ b/rs/moq-video/src/render/readback.rs @@ -0,0 +1,283 @@ +//! Read textures drawn with `wgpu` back to the CPU, as packed RGBA. +//! +//! For a consumer that needs the raw picture rather than an encoded one, such as +//! a virtual camera or a screenshot. [`Readback::copy`] snapshots a texture into +//! one of a few staging buffers it owns and returns at once, so the caller keeps +//! drawing into its texture; [`Pending::wait`] then waits for the GPU on whatever +//! thread consumes the picture, and hands back its pixels. +//! +//! The [`export`](super::export) module reads through this when its encoder +//! takes frames on the CPU. + +use std::sync::{Arc, Mutex}; + +use crate::convert::Rgba; +use crate::{Error, Size}; + +fn err(message: impl std::fmt::Display) -> Error { + Error::Render(anyhow::anyhow!("{message}")) +} + +/// Copies textures back to the CPU, through a small pool of staging buffers. +/// +/// A copy that finds every buffer still in flight is refused rather than +/// queued, so a consumer that falls behind drops pictures instead of adding +/// latency. +pub struct Readback { + device: wgpu::Device, + queue: wgpu::Queue, + size: Size, + /// Bytes per row in a staging buffer, padded to the copy alignment. + row: u32, + pool: Arc>, +} + +/// Staging buffers not held by a [`Pending`]. +#[derive(Default)] +struct Buffers { + free: Vec, + /// Buffers in existence, up to [`Readback::DEPTH`]. + allocated: usize, +} + +impl Readback { + /// Copies in flight at once: one being consumed, one being copied, and one + /// spare so a slow consumer does not drop the very next picture. + pub const DEPTH: usize = 3; + + /// Read back `size` textures drawn on `device`. + /// + /// # Errors + /// + /// Fails when `size` has a zero dimension. + pub fn new(device: &wgpu::Device, queue: &wgpu::Queue, size: Size) -> Result { + size.validate_nonzero("readback")?; + Ok(Self { + device: device.clone(), + queue: queue.clone(), + size, + row: (size.width * 4).next_multiple_of(wgpu::COPY_BYTES_PER_ROW_ALIGNMENT), + pool: Arc::default(), + }) + } + + /// The size of every texture this copies, and of every picture it hands back. + pub fn size(&self) -> Size { + self.size + } + + /// Start copying `texture` back to the CPU. + /// + /// `texture` is [`size`](Self::size), [`wgpu::TextureFormat::Rgba8Unorm`], + /// and created with `COPY_SRC`. The copy is submitted to the queue before + /// this returns, so draw into `texture` again freely. + /// + /// `None` when every buffer is still held by an earlier [`Pending`]. + pub fn copy(&mut self, texture: &wgpu::Texture) -> Result, Error> { + check(texture, self.size, wgpu::TextureUsages::COPY_SRC)?; + + let mut pool = self.pool.lock().unwrap(); + let buffer = match pool.free.pop() { + Some(buffer) => buffer, + None if pool.allocated < Self::DEPTH => { + pool.allocated += 1; + self.device.create_buffer(&wgpu::BufferDescriptor { + label: Some("moq-video readback"), + size: u64::from(self.row) * u64::from(self.size.height), + usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ, + mapped_at_creation: false, + }) + } + None => return Ok(None), + }; + drop(pool); + + let mut encoder = self.device.create_command_encoder(&wgpu::CommandEncoderDescriptor { + label: Some("moq-video readback"), + }); + encoder.copy_texture_to_buffer( + texture.as_image_copy(), + wgpu::TexelCopyBufferInfo { + buffer: &buffer, + layout: wgpu::TexelCopyBufferLayout { + offset: 0, + bytes_per_row: Some(self.row), + rows_per_image: Some(self.size.height), + }, + }, + extent(self.size), + ); + let submission = self.queue.submit([encoder.finish()]); + + Ok(Some(Pending { + device: self.device.clone(), + buffer: Some(buffer), + submission, + size: self.size, + row: self.row, + pool: self.pool.clone(), + mapping: false, + })) + } +} + +/// One readback in flight. Dropping it gives its buffer back. +pub struct Pending { + device: wgpu::Device, + buffer: Option, + submission: wgpu::SubmissionIndex, + size: Size, + row: u32, + pool: Arc>, + /// Set while a mapping was requested and not yet undone, so a wait that + /// failed partway does not hand a mapped buffer to the next copy. + mapping: bool, +} + +impl Pending { + /// Block until the copy lands, then hand back its pixels. + pub fn wait(mut self) -> Result { + let buffer = self.buffer.as_ref().expect("held until drop"); + let (send, recv) = std::sync::mpsc::channel(); + self.mapping = true; + buffer.map_async(wgpu::MapMode::Read, .., move |result| { + let _ = send.send(result); + }); + finish(&self.device, self.submission.clone())?; + recv.recv() + .map_err(|_| err("the readback was dropped"))? + .map_err(|e| err(format!("mapping the readback: {e}")))?; + + let width = self.size.width as usize * 4; + let mut rgba = Vec::with_capacity(width * self.size.height as usize); + { + let mapped = buffer + .slice(..) + .get_mapped_range() + .map_err(|e| err(format!("reading the readback: {e}")))?; + for row in mapped.chunks_exact(self.row as usize) { + rgba.extend_from_slice(&row[..width]); + } + } + buffer.unmap(); + self.mapping = false; + Ok(Rgba::new(self.size, rgba)) + } +} + +impl Drop for Pending { + fn drop(&mut self) { + let Some(buffer) = self.buffer.take() else { + return; + }; + let mut pool = self.pool.lock().unwrap(); + // The pool only holds buffers the next copy can write. One a failed wait + // left mapped, or waiting on a mapping, is let go and replaced. + if self.mapping { + pool.allocated -= 1; + } else { + pool.free.push(buffer); + } + } +} + +/// Refuse a texture that is not `size`, `Rgba8Unorm`, and created with `usage`. +pub(super) fn check(texture: &wgpu::Texture, size: Size, usage: wgpu::TextureUsages) -> Result<(), Error> { + let actual = Size::new(texture.width(), texture.height()); + if actual != size || texture.format() != wgpu::TextureFormat::Rgba8Unorm { + return Err(Error::Unsupported(format!( + "cannot read a {actual} {:?} texture; expected {size} Rgba8Unorm", + texture.format(), + ))); + } + if !texture.usage().contains(usage) { + return Err(Error::Unsupported(format!( + "cannot read a texture created without {usage:?}" + ))); + } + Ok(()) +} + +/// Block until `submission` has finished on the GPU. +pub(super) fn finish(device: &wgpu::Device, submission: wgpu::SubmissionIndex) -> Result<(), Error> { + device + .poll(wgpu::PollType::Wait { + submission_index: Some(submission), + timeout: None, + }) + .map_err(|e| err(format!("waiting for the copy: {e}")))?; + Ok(()) +} + +pub(super) fn extent(size: Size) -> wgpu::Extent3d { + wgpu::Extent3d { + width: size.width, + height: size.height, + depth_or_array_layers: 1, + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::render::export::tests::gpu; + use crate::render::export::texture; + + // The readback lives on the drawing thread and each copy is waited on by the + // consuming one. + const _: fn() = || { + fn send() {} + send::(); + send::(); + }; + + /// A readback hands back exactly what was drawn, unpadded, and drops copies + /// past its depth rather than queuing them. + #[tokio::test] + #[ignore = "needs a GPU; run by just rs render-sw"] + async fn round_trips_and_drops_past_its_depth() { + let (device, queue) = gpu().await.expect("a GPU adapter"); + // 60 pixels is 240 bytes a row, short of the 256-byte copy alignment, so + // the staging rows are padded and the unpadding is exercised. + let size = Size::new(60, 32); + let pixel = [255, 128, 7, 200]; + let drawn = texture(&device, &queue, size, pixel); + let mut readback = Readback::new(&device, &queue, size).unwrap(); + + let mut held: Vec<_> = (0..Readback::DEPTH) + .map(|_| readback.copy(&drawn).unwrap().expect("a free buffer")) + .collect(); + assert!(readback.copy(&drawn).unwrap().is_none()); + + let rgba = held.pop().unwrap().wait().unwrap(); + assert_eq!(rgba.size(), size); + assert_eq!(rgba.data(), pixel.repeat((size.width * size.height) as usize)); + + // The waited buffer went back to the pool. + assert!(readback.copy(&drawn).unwrap().is_some()); + } + + /// A texture of another size or format, or one that cannot be copied from, is + /// refused rather than misread. + #[tokio::test] + #[ignore = "needs a GPU; run by just rs render-sw"] + async fn refuses_a_mismatched_texture() { + let (device, queue) = gpu().await.expect("a GPU adapter"); + let size = Size::new(64, 32); + let mut readback = Readback::new(&device, &queue, size).unwrap(); + let other = texture(&device, &queue, Size::new(32, 32), [0; 4]); + assert!(readback.copy(&other).is_err()); + + let unreadable = device.create_texture(&wgpu::TextureDescriptor { + label: None, + size: extent(size), + mip_level_count: 1, + sample_count: 1, + dimension: wgpu::TextureDimension::D2, + format: wgpu::TextureFormat::Rgba8Unorm, + usage: wgpu::TextureUsages::TEXTURE_BINDING, + view_formats: &[], + }); + assert!(readback.copy(&unreadable).is_err()); + } +}