Skip to main content

sui_render_wgpu/
capture.rs

1use crate::WgpuRenderer;
2use crate::output::DebugCaptureEncoding;
3use crate::output::DebugCaptureRequest;
4use crate::output::DebugCaptureStage;
5use crate::output::DebugSdrVisualization;
6use crate::output::DisplayColorPrimaries;
7use crate::surface::normalize_framebuffer_size;
8use half::f16;
9use sui_core::Error;
10use sui_core::Result;
11use sui_core::WindowId;
12
13#[derive(Debug, Clone, PartialEq, Eq)]
14pub struct RgbaImage {
15    pub(crate) width: u32,
16    pub(crate) height: u32,
17    pub(crate) pixels: Vec<u8>,
18}
19
20#[derive(Debug, Clone, PartialEq)]
21pub struct HdrRgbaImage {
22    pub(crate) width: u32,
23    pub(crate) height: u32,
24    pub(crate) pixels: Vec<f32>,
25}
26
27#[derive(Debug, Clone, PartialEq)]
28pub enum DebugCaptureArtifact {
29    SdrRgba8(RgbaImage),
30    HdrLinearRgbaF32(HdrRgbaImage),
31}
32
33impl RgbaImage {
34    pub fn new(width: u32, height: u32, pixels: Vec<u8>) -> Result<Self> {
35        let expected_len = width as usize * height as usize * 4;
36        if pixels.len() != expected_len {
37            return Err(Error::new(format!(
38                "RGBA image pixel buffer length {} does not match {}x{} image size",
39                pixels.len(),
40                width,
41                height
42            )));
43        }
44
45        Ok(Self {
46            width,
47            height,
48            pixels,
49        })
50    }
51
52    pub const fn width(&self) -> u32 {
53        self.width
54    }
55
56    pub const fn height(&self) -> u32 {
57        self.height
58    }
59
60    pub fn pixels(&self) -> &[u8] {
61        &self.pixels
62    }
63
64    pub fn into_pixels(self) -> Vec<u8> {
65        self.pixels
66    }
67}
68
69impl HdrRgbaImage {
70    pub fn new(width: u32, height: u32, pixels: Vec<f32>) -> Result<Self> {
71        let expected_len = width as usize * height as usize * 4;
72        if pixels.len() != expected_len {
73            return Err(Error::new(format!(
74                "HDR RGBA image pixel buffer length {} does not match {}x{} image size",
75                pixels.len(),
76                width,
77                height
78            )));
79        }
80
81        Ok(Self {
82            width,
83            height,
84            pixels,
85        })
86    }
87
88    pub const fn width(&self) -> u32 {
89        self.width
90    }
91
92    pub const fn height(&self) -> u32 {
93        self.height
94    }
95
96    pub fn pixels(&self) -> &[f32] {
97        &self.pixels
98    }
99
100    pub fn into_pixels(self) -> Vec<f32> {
101        self.pixels
102    }
103}
104
105pub(crate) fn strip_padded_readback_rows(
106    mapped: &[u8],
107    bytes_per_row: usize,
108    padded_bytes_per_row: usize,
109    rows: usize,
110) -> Vec<u8> {
111    let mut tightly_packed = Vec::with_capacity(bytes_per_row * rows);
112    for row in 0..rows {
113        let start = row * padded_bytes_per_row;
114        tightly_packed.extend_from_slice(&mapped[start..start + bytes_per_row]);
115    }
116    tightly_packed
117}
118
119pub(crate) fn decode_rgba16f_pixels(raw: &[u8]) -> Vec<f32> {
120    let mut pixels = Vec::with_capacity(raw.len() / 2);
121    for chunk in raw.chunks_exact(2) {
122        pixels.push(f16::from_bits(u16::from_le_bytes([chunk[0], chunk[1]])).to_f32());
123    }
124    pixels
125}
126
127pub(crate) fn hdr_image_to_sdr_rgba(
128    image: &HdrRgbaImage,
129    visualization: DebugSdrVisualization,
130    reference_white: f32,
131    output_primaries: DisplayColorPrimaries,
132) -> Result<RgbaImage> {
133    let reference_white = if reference_white.is_finite() && reference_white > 0.0 {
134        reference_white
135    } else {
136        1.0
137    };
138    let mut pixels = Vec::with_capacity((image.width() * image.height() * 4) as usize);
139    for rgba in image.pixels().chunks_exact(4) {
140        let normalized = linear_output_primaries_to_srgb(
141            [
142                rgba[0] / reference_white,
143                rgba[1] / reference_white,
144                rgba[2] / reference_white,
145            ],
146            output_primaries,
147        );
148        match visualization {
149            DebugSdrVisualization::ToneMappedColor => {
150                // Native HDR final targets store SDR white above 1.0. Divide that
151                // headroom back out, convert the output primaries to linear sRGB,
152                // then clamp during sRGB encoding. SDR-authored sRGB colors round
153                // back to their original PNG bytes; HDR values overflow to white.
154                pixels.extend_from_slice(&[
155                    linear_to_srgb_capture_u8(normalized[0]),
156                    linear_to_srgb_capture_u8(normalized[1]),
157                    linear_to_srgb_capture_u8(normalized[2]),
158                    linear_alpha_to_capture_u8(rgba[3]),
159                ]);
160            }
161            DebugSdrVisualization::LuminanceHeatmap => {
162                let luminance =
163                    (normalized[0] * 0.2126 + normalized[1] * 0.7152 + normalized[2] * 0.0722)
164                        .max(0.0);
165                let normalized = (luminance / (1.0 + luminance)).clamp(0.0, 1.0);
166                let value = (normalized * 255.0).round() as u8;
167                pixels.extend_from_slice(&[value, value, value, 255]);
168            }
169            DebugSdrVisualization::HeadroomHeatmap => {
170                let headroom = normalized[0].max(normalized[1]).max(normalized[2]).max(0.0);
171                let normalized = (headroom / (1.0 + headroom)).clamp(0.0, 1.0);
172                let red = (normalized * 255.0).round() as u8;
173                let blue = ((1.0 - normalized) * 96.0).round() as u8;
174                pixels.extend_from_slice(&[red, 32, blue, 255]);
175            }
176            DebugSdrVisualization::ClipMask => {
177                let clipped = normalized[0].max(normalized[1]).max(normalized[2]) > 1.0;
178                if clipped {
179                    pixels.extend_from_slice(&[255, 64, 64, 255]);
180                } else {
181                    pixels.extend_from_slice(&[0, 0, 0, 255]);
182                }
183            }
184        }
185    }
186    RgbaImage::new(image.width(), image.height(), pixels)
187}
188
189pub(crate) fn linear_output_primaries_to_srgb(
190    color: [f32; 3],
191    output_primaries: DisplayColorPrimaries,
192) -> [f32; 3] {
193    match output_primaries {
194        DisplayColorPrimaries::Srgb => color,
195        DisplayColorPrimaries::DisplayP3 => {
196            let det = (0.822_461_96 * 0.966_805_76) - (0.177_538_02 * 0.033_194_2);
197            let red = (0.966_805_76 * color[0] - 0.177_538_02 * color[1]) / det;
198            let green = (-0.033_194_2 * color[0] + 0.822_461_96 * color[1]) / det;
199            let blue = (color[2] - (0.017_082_63 * red) - (0.072_397_43 * green)) / 0.910_519_96;
200            [red, green, blue]
201        }
202    }
203}
204
205pub(crate) fn encode_hdr_debug_artifact(
206    image: HdrRgbaImage,
207    request: DebugCaptureRequest,
208    sdr_reference_white: f32,
209    output_primaries: DisplayColorPrimaries,
210) -> Result<DebugCaptureArtifact> {
211    match request.encoding {
212        DebugCaptureEncoding::Exr => Ok(DebugCaptureArtifact::HdrLinearRgbaF32(image)),
213        DebugCaptureEncoding::Png => hdr_image_to_sdr_rgba(
214            &image,
215            request.sdr_visualization,
216            sdr_reference_white,
217            output_primaries,
218        )
219        .map(DebugCaptureArtifact::SdrRgba8),
220    }
221}
222
223pub(crate) fn linear_to_srgb_capture_u8(channel: f32) -> u8 {
224    let value = channel.clamp(0.0, 1.0);
225    let encoded = if value <= 0.003_130_8 {
226        value * 12.92
227    } else {
228        (1.055 * value.powf(1.0 / 2.4)) - 0.055
229    };
230    (encoded.clamp(0.0, 1.0) * 255.0).round() as u8
231}
232
233pub(crate) fn linear_alpha_to_capture_u8(alpha: f32) -> u8 {
234    (alpha.clamp(0.0, 1.0) * 255.0).round() as u8
235}
236impl WgpuRenderer {
237    pub fn capture_last_frame_rgba(&mut self, window_id: WindowId) -> Result<RgbaImage> {
238        match self.capture_last_frame_debug(window_id, DebugCaptureRequest::default())? {
239            DebugCaptureArtifact::SdrRgba8(image) => Ok(image),
240            DebugCaptureArtifact::HdrLinearRgbaF32(_) => Err(Error::new(format!(
241                "window {} returned an HDR debug artifact when SDR RGBA capture was requested",
242                window_id.get()
243            ))),
244        }
245    }
246
247    pub fn capture_last_frame_debug(
248        &mut self,
249        window_id: WindowId,
250        request: DebugCaptureRequest,
251    ) -> Result<DebugCaptureArtifact> {
252        let frame = self.last_frames.get(&window_id).cloned().ok_or_else(|| {
253            Error::new(format!(
254                "window {} does not have a previously rendered frame available for capture",
255                window_id.get()
256            ))
257        })?;
258
259        let size = normalize_framebuffer_size(frame.surface_size).ok_or_else(|| {
260            Error::new(format!(
261                "window {} last rendered frame has an invalid framebuffer size",
262                window_id.get()
263            ))
264        })?;
265
266        self.render_debug_capture_stage(&frame, size, request)?;
267        self.capture_debug_frame(window_id, request)
268    }
269
270    pub fn capture_debug_frame(
271        &self,
272        window_id: WindowId,
273        request: DebugCaptureRequest,
274    ) -> Result<DebugCaptureArtifact> {
275        match request.stage {
276            DebugCaptureStage::FinalComposed => {
277                self.capture_final_composed_debug_artifact(window_id, request)
278            }
279            DebugCaptureStage::HdrIntermediate => {
280                let image = self.capture_hdr_intermediate_rgba_f32(window_id)?;
281                encode_hdr_debug_artifact(image, request, 1.0, DisplayColorPrimaries::Srgb)
282            }
283        }
284    }
285
286    pub fn capture_rgba(&self, window_id: WindowId) -> Result<RgbaImage> {
287        let target = self.offscreen_targets.get(&window_id).ok_or_else(|| {
288            Error::new(format!(
289                "window {} does not have an offscreen render target available for screenshot capture",
290                window_id.get()
291            ))
292        })?;
293        let raw = self.readback_target_bytes(
294            &target.texture,
295            target.size,
296            4,
297            "SUI screenshot readback",
298            "SUI screenshot readback encoder",
299        )?;
300
301        let mut pixels = Vec::with_capacity((target.size.0 * target.size.1 * 4) as usize);
302        for chunk in raw.chunks_exact(4) {
303            pixels.extend_from_slice(&[chunk[2], chunk[1], chunk[0], chunk[3]]);
304        }
305
306        RgbaImage::new(target.size.0, target.size.1, pixels)
307    }
308
309    pub fn capture_hdr_intermediate_rgba_f32(&self, window_id: WindowId) -> Result<HdrRgbaImage> {
310        let target = self.intermediate_targets.get(&window_id).ok_or_else(|| {
311            Error::new(format!(
312                "window {} does not have an HDR intermediate target available for debug capture",
313                window_id.get()
314            ))
315        })?;
316        let raw = self.readback_target_bytes(
317            &target.texture,
318            target.size,
319            8,
320            "SUI HDR intermediate readback",
321            "SUI HDR intermediate readback encoder",
322        )?;
323        let pixels = decode_rgba16f_pixels(&raw);
324        HdrRgbaImage::new(target.size.0, target.size.1, pixels)
325    }
326
327    pub(crate) fn capture_final_composed_debug_artifact(
328        &self,
329        window_id: WindowId,
330        request: DebugCaptureRequest,
331    ) -> Result<DebugCaptureArtifact> {
332        let target = self.offscreen_targets.get(&window_id).ok_or_else(|| {
333            Error::new(format!(
334                "window {} does not have an offscreen target available for final composed debug capture",
335                window_id.get()
336            ))
337        })?;
338
339        match target.format {
340            wgpu::TextureFormat::Bgra8UnormSrgb => self
341                .capture_rgba(window_id)
342                .map(DebugCaptureArtifact::SdrRgba8),
343            wgpu::TextureFormat::Rgba16Float => {
344                let image = self.capture_hdr_offscreen_rgba_f32(window_id)?;
345                encode_hdr_debug_artifact(
346                    image,
347                    request,
348                    self.final_composed_sdr_reference_white(window_id),
349                    self.final_composed_output_primaries(window_id),
350                )
351            }
352            other => Err(Error::new(format!(
353                "window {} uses unsupported final composed debug capture format {other:?}",
354                window_id.get()
355            ))),
356        }
357    }
358
359    pub(crate) fn capture_hdr_offscreen_rgba_f32(
360        &self,
361        window_id: WindowId,
362    ) -> Result<HdrRgbaImage> {
363        let target = self.offscreen_targets.get(&window_id).ok_or_else(|| {
364            Error::new(format!(
365                "window {} does not have an offscreen HDR target available for debug capture",
366                window_id.get()
367            ))
368        })?;
369        let raw = self.readback_target_bytes(
370            &target.texture,
371            target.size,
372            8,
373            "SUI HDR final readback",
374            "SUI HDR final readback encoder",
375        )?;
376        let pixels = decode_rgba16f_pixels(&raw);
377        HdrRgbaImage::new(target.size.0, target.size.1, pixels)
378    }
379
380    pub(crate) fn final_composed_sdr_reference_white(&self, window_id: WindowId) -> f32 {
381        self.surfaces
382            .get(&window_id)
383            .map(|surface| {
384                crate::output::output_sdr_content_scale(
385                    surface.output_strategy,
386                    surface.color_management.sdr_content_brightness_nits,
387                    surface.display_capabilities.sdr_white_nits,
388                )
389            })
390            .filter(|scale| scale.is_finite() && *scale > 0.0)
391            .unwrap_or(1.0)
392    }
393
394    pub(crate) fn final_composed_output_primaries(
395        &self,
396        window_id: WindowId,
397    ) -> DisplayColorPrimaries {
398        self.surfaces
399            .get(&window_id)
400            .map(|surface| crate::output::output_primaries(surface.output_strategy))
401            .unwrap_or(DisplayColorPrimaries::Srgb)
402    }
403
404    pub(crate) fn readback_target_bytes(
405        &self,
406        texture: &wgpu::Texture,
407        size: (u32, u32),
408        bytes_per_pixel: u32,
409        buffer_label: &'static str,
410        encoder_label: &'static str,
411    ) -> Result<Vec<u8>> {
412        let shared = self
413            .shared
414            .as_ref()
415            .ok_or_else(|| Error::new("renderer has not initialized a wgpu device yet"))?;
416        let bytes_per_row = size.0 * bytes_per_pixel;
417        let padded_bytes_per_row = bytes_per_row.div_ceil(wgpu::COPY_BYTES_PER_ROW_ALIGNMENT)
418            * wgpu::COPY_BYTES_PER_ROW_ALIGNMENT;
419        let buffer_size = padded_bytes_per_row as u64 * size.1 as u64;
420        let buffer = shared.device.create_buffer(&wgpu::BufferDescriptor {
421            label: Some(buffer_label),
422            size: buffer_size,
423            usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ,
424            mapped_at_creation: false,
425        });
426
427        let mut encoder = shared
428            .device
429            .create_command_encoder(&wgpu::CommandEncoderDescriptor {
430                label: Some(encoder_label),
431            });
432        encoder.copy_texture_to_buffer(
433            wgpu::TexelCopyTextureInfo {
434                texture,
435                mip_level: 0,
436                origin: wgpu::Origin3d::ZERO,
437                aspect: wgpu::TextureAspect::All,
438            },
439            wgpu::TexelCopyBufferInfo {
440                buffer: &buffer,
441                layout: wgpu::TexelCopyBufferLayout {
442                    offset: 0,
443                    bytes_per_row: Some(padded_bytes_per_row),
444                    rows_per_image: Some(size.1),
445                },
446            },
447            wgpu::Extent3d {
448                width: size.0,
449                height: size.1,
450                depth_or_array_layers: 1,
451            },
452        );
453        shared.queue.submit([encoder.finish()]);
454
455        let (sender, receiver) = std::sync::mpsc::channel();
456        let slice = buffer.slice(..);
457        slice.map_async(wgpu::MapMode::Read, move |result| {
458            let _ = sender.send(result);
459        });
460        shared
461            .device
462            .poll(wgpu::PollType::wait_indefinitely())
463            .map_err(|error| {
464                Error::new(format!(
465                    "failed to poll device for screenshot capture: {error}"
466                ))
467            })?;
468        receiver
469            .recv()
470            .map_err(|error| {
471                Error::new(format!(
472                    "failed to receive screenshot readback completion: {error}"
473                ))
474            })?
475            .map_err(|error| {
476                Error::new(format!("failed to map screenshot readback buffer: {error}"))
477            })?;
478
479        let mapped = slice.get_mapped_range().map_err(|error| {
480            Error::new(format!(
481                "failed to access mapped screenshot readback buffer: {error}"
482            ))
483        })?;
484        let tightly_packed = strip_padded_readback_rows(
485            &mapped,
486            bytes_per_row as usize,
487            padded_bytes_per_row as usize,
488            size.1 as usize,
489        );
490        drop(mapped);
491        buffer.unmap();
492        Ok(tightly_packed)
493    }
494}