HDR: screenshots carry an ICC profile, for programs that don't read cICP

Co-Authored-By: Claude Opus 5.5 <[email protected]>

crates/horizon-client-render/src/gfx.rs

@@ -111,6 +111,7 @@ mod end_sky;
 mod flat;
 mod frame_gen;
 mod hdr;
+mod hdr_icc;
 mod hdr_stats;
 pub use hdr::Calibration as HdrCalibration;
 pub mod block_light;
@@ -8246,19 +8247,19 @@ impl Renderer {
         Ok([width, height])
     }
     /// The HDR10 copy (`Hdr::capture`) as a 16-bit PNG tagged BT.2020 with PQ (cICP, PNG's
-    /// third edition), with the peak and paper white as its content light levels (cLLI).
+    /// third edition), with the peak and paper white as its content light levels (cLLI), and
+    /// an ICC profile for the programs that don't read cICP (`hdr_icc`).
     fn write_hdr_screenshot(&self, path: &std::path::Path, buffer: &wgpu::Buffer) -> Result<()> {
         let Some(hdr) = &self.hdr else {
             return Ok(());
         };
         let pixels = hdr10_to_rgb16(&self.read_frame(buffer)?);
-        let mut encoder = png::Encoder::new(
-            std::io::BufWriter::new(std::fs::File::create(path)?),
-            self.config.width,
-            self.config.height,
-        );
-        encoder.set_color(png::ColorType::Rgb);
-        encoder.set_depth(png::BitDepth::Sixteen);
+        let mut info = png::Info::with_size(self.config.width, self.config.height);
+        info.color_type = png::ColorType::Rgb;
+        info.bit_depth = png::BitDepth::Sixteen;
+        info.icc_profile = Some(hdr_icc::profile().into());
+        let encoder =
+            png::Encoder::with_info(std::io::BufWriter::new(std::fs::File::create(path)?), info)?;
         let mut writer = encoder.write_header()?;
         // BT.2020 primaries, PQ, RGB, full range.
         writer.write_chunk(png::chunk::cICP, &[9, 16, 0, 1])?;

crates/horizon-client-render/src/gfx/hdr_icc.rs

@@ -0,0 +1,159 @@
+//! The ICC profile of HDR screenshots, for programs that don't read PNG's `cICP`: BT.2020
+//! primaries and the PQ curve, with HDR reference white (203 nits) as the profile's white.
+//! An ICC profile has no values above white, so those programs show a correct SDR picture
+//! with its highlights clipped, where without it they took PQ's values for sRGB's and showed
+//! them washed out. Programs that read `cICP` ignore this (PNG's third edition).
+
+/// HDR reference white in nits (ITU-R BT.2408): where the curve reaches the profile's white.
+const WHITE: f64 = 203.0;
+/// PQ's values from 0 to 1, in the curve's steps.
+const STEPS: usize = 4096;
+/// BT.2020's primaries, adapted to the profile connection space's D50 (Bradford).
+const RED: [f64; 3] = [0.67348, 0.27904, -0.00193];
+const GREEN: [f64; 3] = [0.16567, 0.67534, 0.02998];
+const BLUE: [f64; 3] = [0.12505, 0.04561, 0.79685];
+const D50: [f64; 3] = [0.9642, 1.0, 0.8249];
+
+/// PQ's EOTF (SMPTE ST 2084): a signal from 0 to 1 in nits.
+fn pq_nits(signal: f64) -> f64 {
+    let (m1, m2) = (2610.0 / 16384.0, 2523.0 / 32.0);
+    let (c1, c2, c3) = (3424.0 / 4096.0, 2413.0 / 128.0, 2392.0 / 128.0);
+    let p = signal.powf(1.0 / m2);
+    10_000.0 * ((p - c1).max(0.0) / (c2 - c3 * p)).powf(1.0 / m1)
+}
+
+fn s15_fixed16(v: f64) -> [u8; 4] {
+    ((v * 65536.0).round() as i32).to_be_bytes()
+}
+
+fn xyz(v: [f64; 3]) -> Vec<u8> {
+    let mut tag = b"XYZ \0\0\0\0".to_vec();
+    tag.extend(v.iter().flat_map(|&c| s15_fixed16(c)));
+    tag
+}
+
+fn curve() -> Vec<u8> {
+    let mut tag = b"curv\0\0\0\0".to_vec();
+    tag.extend((STEPS as u32).to_be_bytes());
+    for i in 0..STEPS {
+        let y = (pq_nits(i as f64 / (STEPS - 1) as f64) / WHITE).min(1.0);
+        tag.extend(((y * 65535.0).round() as u16).to_be_bytes());
+    }
+    tag
+}
+
+/// `textDescriptionType` (ICC v2), with its empty Unicode and ScriptCode parts.
+fn description(text: &str) -> Vec<u8> {
+    let mut tag = b"desc\0\0\0\0".to_vec();
+    tag.extend((text.len() as u32 + 1).to_be_bytes());
+    tag.extend(text.as_bytes());
+    tag.extend([0; 1 + 4 + 4 + 2 + 1 + 67]);
+    tag
+}
+
+/// An ICC v2 matrix-shaper display profile.
+pub(super) fn profile() -> Vec<u8> {
+    let trc = curve();
+    let copyright = b"text\0\0\0\0Public domain\0".to_vec();
+    let tags: [(&[u8; 4], &[u8]); 9] = [
+        (b"desc", &description("BT.2020 PQ, 203 nits = white")),
+        (b"cprt", &copyright),
+        (b"wtpt", &xyz(D50)),
+        (b"rXYZ", &xyz(RED)),
+        (b"gXYZ", &xyz(GREEN)),
+        (b"bXYZ", &xyz(BLUE)),
+        (b"rTRC", &trc),
+        (b"gTRC", &trc),
+        (b"bTRC", &trc),
+    ];
+    let data_start = 128 + 4 + 12 * tags.len();
+    let mut table = (tags.len() as u32).to_be_bytes().to_vec();
+    let mut data = Vec::new();
+    let mut trc_at = None;
+    for (name, tag) in tags {
+        // The three channels share one curve.
+        let is_trc = tag == &trc[..];
+        let at = match trc_at.filter(|_| is_trc) {
+            Some(at) => at,
+            None => {
+                let at = data_start + data.len();
+                data.extend(tag);
+                data.resize(data.len().next_multiple_of(4), 0);
+                at
+            }
+        };
+        if is_trc {
+            trc_at = Some(at);
+        }
+        table.extend(name);
+        table.extend((at as u32).to_be_bytes());
+        table.extend((tag.len() as u32).to_be_bytes());
+    }
+    let mut out = vec![0; 128];
+    let size = data_start + data.len();
+    out[0..4].copy_from_slice(&(size as u32).to_be_bytes());
+    out[8..12].copy_from_slice(&[2, 0x40, 0, 0]);
+    out[12..16].copy_from_slice(b"mntr");
+    out[16..20].copy_from_slice(b"RGB ");
+    out[20..24].copy_from_slice(b"XYZ ");
+    out[36..40].copy_from_slice(b"acsp");
+    // Relative colorimetric, and the connection space's illuminant.
+    out[64..68].copy_from_slice(&1u32.to_be_bytes());
+    for (i, &c) in D50.iter().enumerate() {
+        out[68 + 4 * i..72 + 4 * i].copy_from_slice(&s15_fixed16(c));
+    }
+    out.extend(table);
+    out.extend(data);
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn tag<'a>(profile: &'a [u8], name: &[u8; 4]) -> &'a [u8] {
+        let u32_at = |i: usize| u32::from_be_bytes(profile[i..i + 4].try_into().unwrap()) as usize;
+        let at = (0..u32_at(128))
+            .map(|i| 132 + 12 * i)
+            .find(|&e| &profile[e..e + 4] == name)
+            .unwrap();
+        &profile[u32_at(at + 4)..u32_at(at + 4) + u32_at(at + 8)]
+    }
+
+    #[test]
+    fn the_profile_is_whole() {
+        let p = profile();
+        assert_eq!(
+            u32::from_be_bytes(p[0..4].try_into().unwrap()) as usize,
+            p.len()
+        );
+        assert_eq!(&p[36..40], b"acsp");
+        assert_eq!(p.len() % 4, 0);
+        assert_eq!(&tag(&p, b"desc")[0..4], b"desc");
+        // One curve, shared: the profile stays small.
+        assert_eq!(tag(&p, b"rTRC").as_ptr(), tag(&p, b"bTRC").as_ptr());
+        assert!(p.len() < 10_000, "{}", p.len());
+    }
+
+    #[test]
+    fn the_primaries_add_up_to_white() {
+        for i in 0..3 {
+            assert!((RED[i] + GREEN[i] + BLUE[i] - D50[i]).abs() < 0.0001);
+        }
+    }
+
+    #[test]
+    fn the_curve_reaches_white_at_reference_white_and_stays() {
+        let p = profile();
+        let trc = tag(&p, b"rTRC");
+        let value = |signal: f64| {
+            let i = 12 + 2 * (signal * (STEPS - 1) as f64).round() as usize;
+            u16::from_be_bytes([trc[i], trc[i + 1]])
+        };
+        assert_eq!(value(0.0), 0);
+        // 203 nits in PQ is a signal of 0.5807.
+        assert!(value(0.57) < 65535);
+        assert_eq!(value(0.59), 65535);
+        assert_eq!(value(1.0), 65535);
+    }
+}

docs/graphics.md

@@ -35,7 +35,7 @@ Every row has a one-line description and its cost in frame time (none, low, medi
 
 **Translucent batching** (only in the file for now: `translucentBatching` in `horizon-graphics.txt`, off by default; edit it with the game closed, it applies at the next start) gives water, glass, ice and other translucent quads a vertex buffer of their own, with pages up to 2 GiB, and their sorted indices the same: the back-to-front list then stays in one page and goes out in a few draw calls instead of switching pages every few sections. The picture is the same; it costs a little video memory, as solid and translucent quads no longer share free space. It needs indirect multi-draw that isn't OpenGL's (which loops over the entries on the CPU), and devices whose vanilla frames draw flat (Metal, Intel Gen11 and Gen12 on Vulkan) don't offer it. A `shaders/` pack's terrain and shadow passes, and the `[shadow]` pass of one of Horizon's own packs, draw flat where the device can, reading translucent quads beside their section's solid ones: while such a pack runs they go back there. Such a pack picked at the start has the world laid out for it from the first; switching to or from one later meshes the world again.
 
-**HDR** (off by default) lives on its own screen, Graphics: HDR, behind **HDR Settings...** under Display, which is greyed where the display path offers no HDR output (so players without an HDR display don't take its settings for their display's); there the switch comes first and the sliders below it only while it is on. It presents to an HDR10 swapchain (`Rgb10a2Unorm`, BT.2020 with the PQ curve) or, where only that is offered, an scRGB one (`Rgba16Float`, extended linear sRGB), on displays and compositors that offer either; `HORIZON_HDR_OUTPUT=pq` or `scrgb` allows only one. The frame is drawn exactly as in SDR, in vanilla's gamma space, and a last pass (`hdr.wgsl`) decodes it to linear light at the **Paper White** and lifts light sources (blocks that emit light, lava, the sun and the moon) towards the **Peak Brightness**; everything else stays as in SDR. The mesher puts the light a block's face emits in its vertex colour's alpha (`EMISSION_BITS`), the frame's alpha carries the mark, and only pixels that still show the world before the hand and HUD are lifted. On Vulkan, `horizon-hdr` sends HDR metadata (MaxCLL, mastering luminance), which wgpu doesn't: without it a compositor may clip everything above SDR white. Paper White and Peak Brightness are **Auto** by default: they follow what the system reports for the display. On Wayland that's the compositor's preferred image description of the window (`wp_color_management_v1`, in `horizon-hdr`'s `wayland.rs`), asked and then watched while HDR output is on (with HDR off the game doesn't ask), so a move to another output or a recalibrated desktop applies at once. KWin maps the content's reference white (203 nits) onto the desktop's SDR white, so Auto puts Paper White at 203 and Peak Brightness at the display's peak over that ratio; Hyprland (0.57) doesn't: it reports the standard 203 as reference white, so Auto puts Paper White at 203, and it shows HDR windows below its own SDR white (`sdr_max_luminance`, which it doesn't report): in a test, a white browser page was brighter than both the game's white and a 1000-nit patch in mpv. Other compositors are unchecked. On Windows Auto takes what wgpu reads from the OS (`Surface::display_hdr_info`: DXGI's `MaxLuminance` and the SDR white level of Windows' SDR content brightness slider, both absolute nits), read again every 2 seconds since no event says they changed; these often come from the display's EDID and may run optimistic, and this is untested so far. **Calibrate...** (`hdr_calibration.rs`) sets Black Level, Peak Brightness and Paper White full screen, one test picture at a time, drawn by the last pass straight in nits above a band of controls: Horizon's logo at the slider on black, lowered until it disappears; the logo at the slider inside a tenth of the screen at 10 000 nits (small, so the display doesn't dim), raised until it disappears; a white card, set to a white that's comfortable in the light the player plays in. Save writes the three, Cancel or Escape keeps what was set, and a step left untouched keeps Auto. The Peak step needs a path that doesn't tone-map: on KWin the logo never disappears, so where the system reports its values the button reads **Calibrate Anyway...** and says the display is already set up (**Use Automatic Setup** once they were changed by hand). Where nothing is reported, Auto is 203 and 1000 nits, and the Graphics: HDR screen asks the player to calibrate. **Black Level** (0 by default, for an OLED's true black) is the display's darkest black, in nits: the last pass lifts the shadows onto it with ITU-R BT.2390's black level lift in PQ, which leaves the peak where it is and fades out by the fourth power above black, and the metadata gives it as the minimum luminance; at 0 the picture is unchanged. **UI Brightness** (100% by default) sets the HUD and menus against paper white: once the world is kept for the last pass, the frame's alpha is zeroed, everything drawn after raises it where it covers the world, the first-person hand's is then scaled down to 1/255 (it stays at the world's brightness), and the last pass scales the rest by UI Brightness and lifts none of it (so text over the sun stays text). With HDR on, F2 writes vanilla's screenshot as always and an HDR10 copy beside it (`…-hdr.png`): the HDR pass drawn once more into a 10-bit PQ target, whatever the swapchain is, saved as a 16-bit PNG tagged BT.2020 with PQ (`cICP`, PNG's third edition) and the peak and paper white as content light levels (`cLLI`); viewers that read `cICP` show it in HDR, others show it washed out. Not lifted yet: translucent blocks (the nether portal), distant LOD terrain.
+**HDR** (off by default) lives on its own screen, Graphics: HDR, behind **HDR Settings...** under Display, which is greyed where the display path offers no HDR output (so players without an HDR display don't take its settings for their display's); there the switch comes first and the sliders below it only while it is on. It presents to an HDR10 swapchain (`Rgb10a2Unorm`, BT.2020 with the PQ curve) or, where only that is offered, an scRGB one (`Rgba16Float`, extended linear sRGB), on displays and compositors that offer either; `HORIZON_HDR_OUTPUT=pq` or `scrgb` allows only one. The frame is drawn exactly as in SDR, in vanilla's gamma space, and a last pass (`hdr.wgsl`) decodes it to linear light at the **Paper White** and lifts light sources (blocks that emit light, lava, the sun and the moon) towards the **Peak Brightness**; everything else stays as in SDR. The mesher puts the light a block's face emits in its vertex colour's alpha (`EMISSION_BITS`), the frame's alpha carries the mark, and only pixels that still show the world before the hand and HUD are lifted. On Vulkan, `horizon-hdr` sends HDR metadata (MaxCLL, mastering luminance), which wgpu doesn't: without it a compositor may clip everything above SDR white. Paper White and Peak Brightness are **Auto** by default: they follow what the system reports for the display. On Wayland that's the compositor's preferred image description of the window (`wp_color_management_v1`, in `horizon-hdr`'s `wayland.rs`), asked and then watched while HDR output is on (with HDR off the game doesn't ask), so a move to another output or a recalibrated desktop applies at once. KWin maps the content's reference white (203 nits) onto the desktop's SDR white, so Auto puts Paper White at 203 and Peak Brightness at the display's peak over that ratio; Hyprland (0.57) doesn't: it reports the standard 203 as reference white, so Auto puts Paper White at 203, and it shows HDR windows below its own SDR white (`sdr_max_luminance`, which it doesn't report): in a test, a white browser page was brighter than both the game's white and a 1000-nit patch in mpv. Other compositors are unchecked. On Windows Auto takes what wgpu reads from the OS (`Surface::display_hdr_info`: DXGI's `MaxLuminance` and the SDR white level of Windows' SDR content brightness slider, both absolute nits), read again every 2 seconds since no event says they changed; these often come from the display's EDID and may run optimistic, and this is untested so far. **Calibrate...** (`hdr_calibration.rs`) sets Black Level, Peak Brightness and Paper White full screen, one test picture at a time, drawn by the last pass straight in nits above a band of controls: Horizon's logo at the slider on black, lowered until it disappears; the logo at the slider inside a tenth of the screen at 10 000 nits (small, so the display doesn't dim), raised until it disappears; a white card, set to a white that's comfortable in the light the player plays in. Save writes the three, Cancel or Escape keeps what was set, and a step left untouched keeps Auto. The Peak step needs a path that doesn't tone-map: on KWin the logo never disappears, so where the system reports its values the button reads **Calibrate Anyway...** and says the display is already set up (**Use Automatic Setup** once they were changed by hand). Where nothing is reported, Auto is 203 and 1000 nits, and the Graphics: HDR screen asks the player to calibrate. **Black Level** (0 by default, for an OLED's true black) is the display's darkest black, in nits: the last pass lifts the shadows onto it with ITU-R BT.2390's black level lift in PQ, which leaves the peak where it is and fades out by the fourth power above black, and the metadata gives it as the minimum luminance; at 0 the picture is unchanged. **UI Brightness** (100% by default) sets the HUD and menus against paper white: once the world is kept for the last pass, the frame's alpha is zeroed, everything drawn after raises it where it covers the world, the first-person hand's is then scaled down to 1/255 (it stays at the world's brightness), and the last pass scales the rest by UI Brightness and lifts none of it (so text over the sun stays text). With HDR on, F2 writes vanilla's screenshot as always and an HDR10 copy beside it (`…-hdr.png`): the HDR pass drawn once more into a 10-bit PQ target, whatever the swapchain is, saved as a 16-bit PNG tagged BT.2020 with PQ (`cICP`, PNG's third edition) and the peak and paper white as content light levels (`cLLI`); viewers that read `cICP` show it in HDR, and others that honour its ICC profile (reference white at the profile's white) a correct SDR picture with clipped highlights. Not lifted yet: translucent blocks (the nether portal), distant LOD terrain.
 
 HDR's light sources shine by the kind of light rather than its level (`mesher::hdr_tier`): the sun most, then glowstone, campfires and the soul fires, then flames and lava, torch and candle flames among them (particles too), then faint glowers such as a redstone torch or magma; glow lichen stays as in SDR. Each tier has its share of the headroom and the brightness its lift starts and ends at (`gfx/hdr.rs` `TIERS`); `HORIZON_HDR_DEBUG=1` greys what isn't lifted and tints what is magenta.