Skip to main content

webizen_render/wgpu_renderer/
readback.rs

1//! Bounded offscreen pixel readback, PNG encoding, and runtime receipt generation.
2
3use super::renderer::{reserve_graphics_bytes, GraphicsClass, RenderTarget, WgpuRenderer};
4use super::{
5    pixel_receipt_from_rgba8, readback_layout, PixelReadback, PixelReceipt, PixelReceiptStatus,
6    WebGpuRuntimeReceipt,
7};
8
9impl<'a> WgpuRenderer<'a> {
10    /// Attempt a bounded pixel readback and return both bytes and evidence.
11    pub fn read_pixels_with_receipt(&self) -> PixelReadback {
12        let adapter_backed = self.capabilities.device_available;
13        let (texture, width, height) = match &self.target {
14            RenderTarget::Offscreen {
15                texture,
16                width,
17                height,
18                ..
19            } => (texture, *width, *height),
20            RenderTarget::Surface { .. } => {
21                return PixelReadback {
22                    pixels: None,
23                    receipt: PixelReceipt::refusal(
24                        PixelReceiptStatus::NotOffscreen,
25                        self.requested_extent.0,
26                        self.requested_extent.1,
27                        adapter_backed,
28                    ),
29                }
30            }
31        };
32
33        let (padded_bytes_per_row, unpadded_bytes_per_row, readback_bytes, output_bytes) =
34            match readback_layout(width, height) {
35                Some(layout) => layout,
36                None => {
37                    return PixelReadback {
38                        pixels: None,
39                        receipt: PixelReceipt::refusal(
40                            PixelReceiptStatus::Refused,
41                            width,
42                            height,
43                            adapter_backed,
44                        ),
45                    }
46                }
47            };
48        let _staging_reservation = match reserve_graphics_bytes(
49            GraphicsClass::UploadStaging,
50            readback_bytes,
51            "readback",
52        ) {
53            Ok(reservation) => reservation,
54            Err(error) => {
55                log::warn!("webizen-render pixel readback refused: {error}");
56                return PixelReadback {
57                    pixels: None,
58                    receipt: PixelReceipt::refusal(
59                        PixelReceiptStatus::Refused,
60                        width,
61                        height,
62                        adapter_backed,
63                    ),
64                };
65            }
66        };
67
68        let readback = self.device.create_buffer(&etalon::BufferDescriptor {
69            label: Some("webizen-readback-buffer"),
70            size: readback_bytes,
71            usage: etalon::BufferUsages::MAP_READ | etalon::BufferUsages::COPY_DST,
72            mapped_at_creation: false,
73        });
74
75        let mut encoder = self
76            .device
77            .create_command_encoder(&etalon::CommandEncoderDescriptor {
78                label: Some("webizen-readback-encoder"),
79            });
80        encoder.copy_texture_to_buffer(
81            etalon::TexelCopyTextureInfo {
82                texture,
83                mip_level: 0,
84                origin: etalon::Origin3d::ZERO,
85                aspect: etalon::TextureAspect::All,
86            },
87            etalon::TexelCopyBufferInfo {
88                buffer: &readback,
89                layout: etalon::TexelCopyBufferLayout {
90                    offset: 0,
91                    bytes_per_row: Some(padded_bytes_per_row),
92                    rows_per_image: Some(height),
93                },
94            },
95            etalon::Extent3d {
96                width,
97                height,
98                depth_or_array_layers: 1,
99            },
100        );
101        self.queue.submit(Some(encoder.finish()));
102
103        let slice = readback.slice(..);
104        let (tx, rx) = std::sync::mpsc::channel();
105        slice.map_async(etalon::MapMode::Read, move |r| {
106            let _ = tx.send(r);
107        });
108        if let Err(error) = self.device.poll(etalon::PollType::wait_indefinitely()) {
109            log::warn!("webizen-render pixel readback poll failed: {error:?}");
110            return PixelReadback {
111                pixels: None,
112                receipt: PixelReceipt::refusal(
113                    PixelReceiptStatus::MapFailed,
114                    width,
115                    height,
116                    adapter_backed,
117                ),
118            };
119        }
120        if rx.recv().ok().and_then(|result| result.ok()).is_none() {
121            log::warn!("webizen-render pixel readback mapping failed");
122            return PixelReadback {
123                pixels: None,
124                receipt: PixelReceipt::refusal(
125                    PixelReceiptStatus::MapFailed,
126                    width,
127                    height,
128                    adapter_backed,
129                ),
130            };
131        }
132
133        let mapped = match slice.get_mapped_range() {
134            Ok(mapped) => mapped,
135            Err(error) => {
136                log::warn!("webizen-render pixel readback map range failed: {error}");
137                readback.unmap();
138                return PixelReadback {
139                    pixels: None,
140                    receipt: PixelReceipt::refusal(
141                        PixelReceiptStatus::MapFailed,
142                        width,
143                        height,
144                        adapter_backed,
145                    ),
146                };
147            }
148        };
149        let mut out = Vec::with_capacity(output_bytes);
150        for row in 0..height {
151            let start = row as usize * padded_bytes_per_row as usize;
152            let end = start + unpadded_bytes_per_row as usize;
153            out.extend_from_slice(&mapped[start..end]);
154        }
155        drop(mapped);
156        readback.unmap();
157        let mut receipt = pixel_receipt_from_rgba8(width, height, &out);
158        receipt.adapter_backed = adapter_backed;
159        PixelReadback {
160            pixels: Some(out),
161            receipt,
162        }
163    }
164
165    /// Read the offscreen target to a tightly-packed RGBA8 buffer
166    /// (`width * height * 4` bytes, row-major). Returns `None` for refusal.
167    pub fn read_pixels(&self) -> Option<Vec<u8>> {
168        self.read_pixels_with_receipt().pixels
169    }
170
171    /// Return a complete bounded runtime receipt after attempting readback.
172    pub fn runtime_receipt(&self) -> WebGpuRuntimeReceipt {
173        let pixels = self.read_pixels_with_receipt();
174        WebGpuRuntimeReceipt {
175            capabilities: self.capabilities.clone(),
176            requested_extent: self.requested_extent,
177            effective_extent: self.offscreen_extent(),
178            pixels: pixels.receipt,
179        }
180    }
181
182    /// Read the offscreen target back as PNG-encoded bytes, ready to hand to a
183    /// webview as a data-URI or via a custom protocol. Returns `None` for surface
184    /// targets or if there is no GPU frame to read. Native-only (the wasm build
185    /// renders to a `<canvas>` and never reads back).
186    #[cfg(not(target_arch = "wasm32"))]
187    pub fn read_png(&self) -> Option<Vec<u8>> {
188        use image::ImageEncoder;
189
190        let (width, height) = match &self.target {
191            RenderTarget::Offscreen { width, height, .. } => (*width, *height),
192            RenderTarget::Surface { .. } => return None,
193        };
194
195        let rgba = self.read_pixels()?;
196        let mut png_bytes = Vec::new();
197        image::codecs::png::PngEncoder::new(&mut png_bytes)
198            .write_image(&rgba, width, height, image::ExtendedColorType::Rgba8)
199            .ok()?;
200        Some(png_bytes)
201    }
202
203    /// Read the offscreen frame back as a `data:image/png;base64,...` URI — drop
204    /// straight into a webview `<img src>`. Native-only.
205    #[cfg(not(target_arch = "wasm32"))]
206    pub fn read_data_uri(&self) -> Option<String> {
207        use base64::Engine;
208        let png = self.read_png()?;
209        let b64 = base64::engine::general_purpose::STANDARD.encode(png);
210        Some(format!("data:image/png;base64,{b64}"))
211    }
212}