Skip to main content

sg_abi/
hdr.rs

1//! HDR output helpers shared by guests (WGSL) and the host's self-tests (Rust).
2//!
3//! A game renders scene-linear BT.709 color in *paper-white units* (1.0 = the
4//! brightness of SDR white, [`DEFAULT_PAPER_WHITE_NITS`] by default) and calls
5//! `sg_encode_output` from [`WGSL`] as the last step of its final pass. That
6//! function tone-maps to what the output can show and applies the output's
7//! encoding:
8//!
9//! | [`OutputMode`] | Surface format / color space | Encoding |
10//! |---|---|---|
11//! | `SdrSrgbFormat` | `*UnormSrgb` / `Srgb` | roll-off to 1.0; the format applies the sRGB curve |
12//! | `SdrUnorm` | `*Unorm` / `Srgb` | roll-off to 1.0, sRGB curve in the shader |
13//! | `ScRgb` | `Rgba16Float` / `ExtendedSrgbLinear` | roll-off to peak, linear, 1.0 = 80 nits |
14//! | `Pq` | `Rgb10a2Unorm` or `Rgba16Float` / `Bt2100Pq` | roll-off to peak, BT.709→BT.2020, SMPTE ST 2084 |
15//!
16//! [`negotiate`] picks the best mode from a surface's format capabilities, and
17//! falls back to SDR when no HDR color space is offered.
18
19use wgt::{SurfaceColorSpace, SurfaceColorSpaces, TextureFormat};
20
21/// BT.2408 reference white for HDR signals.
22pub const DEFAULT_PAPER_WHITE_NITS: f32 = 203.0;
23/// Peak assumed when the platform does not report one (Vulkan on Linux never does).
24pub const DEFAULT_PEAK_NITS: f32 = 1000.0;
25/// scRGB 1.0 is 80 nits (IEC 61966-2-2).
26pub const SCRGB_NITS: f32 = 80.0;
27/// Where the highlight roll-off starts, as a fraction of the peak.
28pub const KNEE: f32 = 0.75;
29/// SDR: identity up to 0.8, then a roll-off towards 1.0 (paper white lands at 0.93).
30pub const SDR_KNEE: f32 = 0.8;
31
32#[derive(Clone, Copy, Debug, PartialEq, Eq)]
33#[repr(u32)]
34pub enum OutputMode {
35    SdrSrgbFormat = 0,
36    SdrUnorm = 1,
37    ScRgb = 2,
38    Pq = 3,
39}
40
41impl OutputMode {
42    pub fn is_hdr(self) -> bool {
43        matches!(self, OutputMode::ScRgb | OutputMode::Pq)
44    }
45
46    /// The mode that renders correctly into `format` presented in `space`, if any.
47    pub fn for_surface(format: TextureFormat, space: SurfaceColorSpace) -> Option<OutputMode> {
48        use SurfaceColorSpace as S;
49        use TextureFormat as F;
50        match (space, format) {
51            (S::Srgb | S::Auto, f) if f.is_srgb() => Some(OutputMode::SdrSrgbFormat),
52            (S::Srgb, F::Bgra8Unorm | F::Rgba8Unorm | F::Rgb10a2Unorm | F::Rgba16Float) => Some(OutputMode::SdrUnorm),
53            // wgpu's Auto picks extended linear sRGB for Rgba16Float when the surface offers it,
54            // plain sRGB otherwise; negotiate() never relies on that and always names the space.
55            (S::Auto, F::Bgra8Unorm | F::Rgba8Unorm | F::Rgb10a2Unorm) => Some(OutputMode::SdrUnorm),
56            (S::ExtendedSrgbLinear, F::Rgba16Float) => Some(OutputMode::ScRgb),
57            (S::Bt2100Pq, F::Rgb10a2Unorm | F::Rgba16Float) => Some(OutputMode::Pq),
58            _ => None,
59        }
60    }
61}
62
63/// The negotiated output: what to put in `SurfaceConfiguration` and the shader uniform.
64#[derive(Clone, Copy, Debug, PartialEq)]
65pub struct Output {
66    pub format: TextureFormat,
67    pub color_space: SurfaceColorSpace,
68    pub mode: OutputMode,
69    pub paper_white_nits: f32,
70    pub peak_nits: f32,
71}
72
73impl Output {
74    /// The `SgOutput` uniform of [`WGSL`] (16 bytes).
75    pub fn uniform(&self) -> [u8; 16] {
76        let mut b = [0u8; 16];
77        b[0..4].copy_from_slice(&(self.mode as u32).to_le_bytes());
78        b[4..8].copy_from_slice(&self.paper_white_nits.to_le_bytes());
79        b[8..12].copy_from_slice(&self.peak_nits.to_le_bytes());
80        b
81    }
82
83    /// Relative headroom above paper white (1.0 in SDR).
84    pub fn headroom(&self) -> f32 {
85        if self.mode.is_hdr() {
86            self.peak_nits / self.paper_white_nits
87        } else {
88            1.0
89        }
90    }
91}
92
93/// Picks the output for a surface offering `formats` (format, color spaces), in
94/// order of preference: PQ on a 10-bit format, scRGB, PQ on fp16, then SDR (an
95/// `*Srgb` format first). `allow_hdr = false` forces SDR. Returns `None` only if
96/// no format is usable at all.
97pub fn negotiate(formats: &[(TextureFormat, SurfaceColorSpaces)], allow_hdr: bool, peak_nits: Option<f32>) -> Option<Output> {
98    let peak = peak_nits.filter(|p| p.is_finite() && *p >= 80.0 && *p <= 10000.0).unwrap_or(DEFAULT_PEAK_NITS);
99    let has = |f: TextureFormat, s: SurfaceColorSpaces| formats.iter().any(|(ff, ss)| *ff == f && ss.contains(s));
100    let mk = |format, color_space, mode, peak_nits| Output { format, color_space, mode, paper_white_nits: DEFAULT_PAPER_WHITE_NITS, peak_nits };
101    if allow_hdr {
102        if has(TextureFormat::Rgb10a2Unorm, SurfaceColorSpaces::BT2100_PQ) {
103            return Some(mk(TextureFormat::Rgb10a2Unorm, SurfaceColorSpace::Bt2100Pq, OutputMode::Pq, peak));
104        }
105        if has(TextureFormat::Rgba16Float, SurfaceColorSpaces::EXTENDED_SRGB_LINEAR) {
106            return Some(mk(TextureFormat::Rgba16Float, SurfaceColorSpace::ExtendedSrgbLinear, OutputMode::ScRgb, peak));
107        }
108        if has(TextureFormat::Rgba16Float, SurfaceColorSpaces::BT2100_PQ) {
109            return Some(mk(TextureFormat::Rgba16Float, SurfaceColorSpace::Bt2100Pq, OutputMode::Pq, peak));
110        }
111    }
112    let sdr_peak = DEFAULT_PAPER_WHITE_NITS;
113    for (f, ss) in formats {
114        if f.is_srgb() && ss.contains(SurfaceColorSpaces::SRGB) {
115            return Some(mk(*f, SurfaceColorSpace::Srgb, OutputMode::SdrSrgbFormat, sdr_peak));
116        }
117    }
118    for (f, ss) in formats {
119        if ss.contains(SurfaceColorSpaces::SRGB) {
120            if let Some(m) = OutputMode::for_surface(*f, SurfaceColorSpace::Srgb) {
121                return Some(mk(*f, SurfaceColorSpace::Srgb, m, sdr_peak));
122            }
123        }
124    }
125    None
126}
127
128// ---- reference implementations (match the WGSL below) ----
129
130const PQ_M1: f32 = 2610.0 / 16384.0;
131const PQ_M2: f32 = 2523.0 / 4096.0 * 128.0;
132const PQ_C1: f32 = 3424.0 / 4096.0;
133const PQ_C2: f32 = 2413.0 / 4096.0 * 32.0;
134const PQ_C3: f32 = 2392.0 / 4096.0 * 32.0;
135
136/// SMPTE ST 2084 inverse EOTF: absolute nits → signal in [0, 1].
137pub fn pq_oetf(nits: f32) -> f32 {
138    let y = (nits / 10000.0).clamp(0.0, 1.0).powf(PQ_M1);
139    ((PQ_C1 + PQ_C2 * y) / (1.0 + PQ_C3 * y)).powf(PQ_M2)
140}
141
142/// SMPTE ST 2084 EOTF: signal → absolute nits.
143pub fn pq_eotf(e: f32) -> f32 {
144    let p = e.clamp(0.0, 1.0).powf(1.0 / PQ_M2);
145    ((p - PQ_C1).max(0.0) / (PQ_C2 - PQ_C3 * p)).powf(1.0 / PQ_M1) * 10000.0
146}
147
148pub fn srgb_oetf(x: f32) -> f32 {
149    let x = x.clamp(0.0, 1.0);
150    if x <= 0.0031308 {
151        12.92 * x
152    } else {
153        1.055 * x.powf(1.0 / 2.4) - 0.055
154    }
155}
156
157pub fn srgb_eotf(e: f32) -> f32 {
158    if e <= 0.04045 {
159        e / 12.92
160    } else {
161        ((e + 0.055) / 1.055).powf(2.4)
162    }
163}
164
165/// Identity below `knee`, then an exponential shoulder that approaches `peak`
166/// with a continuous first derivative.
167pub fn rolloff(x: f32, knee: f32, peak: f32) -> f32 {
168    if x <= knee {
169        return x.max(0.0);
170    }
171    let r = peak - knee;
172    knee + r * (1.0 - (-(x - knee) / r).exp())
173}
174
175/// Tone-maps on max(R,G,B) so hue is kept.
176pub fn tonemap(rgb: [f32; 3], knee: f32, peak: f32) -> [f32; 3] {
177    let m = rgb[0].max(rgb[1]).max(rgb[2]);
178    if m <= knee {
179        return rgb.map(|c| c.max(0.0));
180    }
181    let s = rolloff(m, knee, peak) / m;
182    rgb.map(|c| (c * s).max(0.0))
183}
184
185/// BT.709 → BT.2020 primaries (ITU-R BT.2087), linear light.
186pub const BT709_TO_BT2020: [[f32; 3]; 3] = [
187    [0.627_404, 0.329_282, 0.043_313_6],
188    [0.069_097, 0.919_540, 0.011_361_2],
189    [0.016_391_6, 0.088_013_2, 0.895_595],
190];
191
192pub fn bt709_to_bt2020(c: [f32; 3]) -> [f32; 3] {
193    let m = BT709_TO_BT2020;
194    [0, 1, 2].map(|i| m[i][0] * c[0] + m[i][1] * c[1] + m[i][2] * c[2])
195}
196
197/// What `sg_encode_output` writes for scene-linear BT.709 `rgb` in paper-white units.
198pub fn encode_output(rgb: [f32; 3], o: &Output) -> [f32; 3] {
199    match o.mode {
200        OutputMode::SdrSrgbFormat => tonemap(rgb, SDR_KNEE, 1.0),
201        OutputMode::SdrUnorm => tonemap(rgb, SDR_KNEE, 1.0).map(srgb_oetf),
202        OutputMode::ScRgb => {
203            let h = o.peak_nits / o.paper_white_nits;
204            tonemap(rgb, KNEE * h, h).map(|c| c * o.paper_white_nits / SCRGB_NITS)
205        }
206        OutputMode::Pq => {
207            let h = o.peak_nits / o.paper_white_nits;
208            bt709_to_bt2020(tonemap(rgb, KNEE * h, h)).map(|c| pq_oetf(c.max(0.0) * o.paper_white_nits))
209        }
210    }
211}
212
213/// WGSL for guests: paste (or `concat!`) into a shader module and bind an
214/// `SgOutput` uniform built by [`Output::uniform`].
215pub const WGSL: &str = r#"
216// ---- sg HDR output (sg_abi::hdr) ----
217struct SgOutput { mode: u32, paper_white_nits: f32, peak_nits: f32, _pad: f32 };
218const SG_OUT_SDR_SRGB_FORMAT: u32 = 0u;
219const SG_OUT_SDR_UNORM: u32 = 1u;
220const SG_OUT_SCRGB: u32 = 2u;
221const SG_OUT_PQ: u32 = 3u;
222
223fn sg_pq_oetf(nits: vec3f) -> vec3f {
224    let m1 = 2610.0 / 16384.0;
225    let m2 = 2523.0 / 4096.0 * 128.0;
226    let c1 = 3424.0 / 4096.0;
227    let c2 = 2413.0 / 4096.0 * 32.0;
228    let c3 = 2392.0 / 4096.0 * 32.0;
229    let y = pow(clamp(nits / 10000.0, vec3f(0.0), vec3f(1.0)), vec3f(m1));
230    return pow((c1 + c2 * y) / (1.0 + c3 * y), vec3f(m2));
231}
232
233fn sg_srgb_oetf(x: vec3f) -> vec3f {
234    let c = clamp(x, vec3f(0.0), vec3f(1.0));
235    return select(1.055 * pow(c, vec3f(1.0 / 2.4)) - 0.055, 12.92 * c, c <= vec3f(0.0031308));
236}
237
238fn sg_rolloff(x: f32, knee: f32, peak: f32) -> f32 {
239    if (x <= knee) { return max(x, 0.0); }
240    let r = peak - knee;
241    return knee + r * (1.0 - exp(-(x - knee) / r));
242}
243
244fn sg_tonemap(rgb: vec3f, knee: f32, peak: f32) -> vec3f {
245    let m = max(rgb.r, max(rgb.g, rgb.b));
246    if (m <= knee) { return max(rgb, vec3f(0.0)); }
247    return max(rgb * (sg_rolloff(m, knee, peak) / m), vec3f(0.0));
248}
249
250fn sg_bt709_to_bt2020(c: vec3f) -> vec3f {
251    return vec3f(
252        dot(vec3f(0.627404, 0.329282, 0.0433136), c),
253        dot(vec3f(0.069097, 0.919540, 0.0113612), c),
254        dot(vec3f(0.0163916, 0.0880132, 0.895595), c));
255}
256
257// Scene-linear BT.709 in paper-white units -> the value to write to the surface.
258fn sg_encode_output(rgb: vec3f, o: SgOutput) -> vec4f {
259    let h = o.peak_nits / o.paper_white_nits;
260    switch o.mode {
261        case 0u: { return vec4f(sg_tonemap(rgb, 0.8, 1.0), 1.0); }
262        case 1u: { return vec4f(sg_srgb_oetf(sg_tonemap(rgb, 0.8, 1.0)), 1.0); }
263        case 2u: { return vec4f(sg_tonemap(rgb, 0.75 * h, h) * (o.paper_white_nits / 80.0), 1.0); }
264        default: { return vec4f(sg_pq_oetf(max(sg_bt709_to_bt2020(sg_tonemap(rgb, 0.75 * h, h)), vec3f(0.0)) * o.paper_white_nits), 1.0); }
265    }
266}
267"#;
268
269#[cfg(test)]
270mod tests {
271    use super::*;
272
273    #[test]
274    fn pq_reference_points() {
275        // Published ST 2084 code values (10-bit full range): 100 nits -> 520, 1000 -> 769, 10000 -> 1023.
276        assert_eq!((pq_oetf(100.0) * 1023.0).round(), 520.0);
277        assert_eq!((pq_oetf(1000.0) * 1023.0).round(), 769.0);
278        assert_eq!((pq_oetf(10000.0) * 1023.0).round(), 1023.0);
279        assert!(pq_oetf(0.0) < 1e-6);
280        for n in [0.1f32, 1.0, 80.0, 203.0, 400.0, 4000.0] {
281            let back = pq_eotf(pq_oetf(n));
282            assert!((back - n).abs() / n < 1e-3, "{n} -> {back}");
283        }
284    }
285
286    #[test]
287    fn rolloff_is_monotonic_and_bounded() {
288        let mut prev = -1.0;
289        for i in 0..10000 {
290            let x = i as f32 * 0.01;
291            let y = rolloff(x, 3.0, 4.0);
292            assert!(y >= prev && y < 4.0 + 1e-6);
293            prev = y;
294        }
295        assert_eq!(rolloff(2.0, 3.0, 4.0), 2.0);
296    }
297
298    #[test]
299    fn negotiation_prefers_hdr_and_falls_back() {
300        let sdr = [(TextureFormat::Bgra8UnormSrgb, SurfaceColorSpaces::SRGB), (TextureFormat::Bgra8Unorm, SurfaceColorSpaces::SRGB)];
301        let o = negotiate(&sdr, true, None).unwrap();
302        assert_eq!((o.format, o.mode), (TextureFormat::Bgra8UnormSrgb, OutputMode::SdrSrgbFormat));
303        // GNOME 46 Wayland: fp16 and 10-bit formats, but only the sRGB color space.
304        let wl = [(TextureFormat::Rgba16Float, SurfaceColorSpaces::SRGB), (TextureFormat::Rgb10a2Unorm, SurfaceColorSpaces::SRGB)];
305        let o = negotiate(&wl, true, None).unwrap();
306        assert_eq!(o.mode, OutputMode::SdrUnorm);
307        let hdr = [
308            (TextureFormat::Bgra8UnormSrgb, SurfaceColorSpaces::SRGB),
309            (TextureFormat::Rgba16Float, SurfaceColorSpaces::SRGB | SurfaceColorSpaces::EXTENDED_SRGB_LINEAR),
310            (TextureFormat::Rgb10a2Unorm, SurfaceColorSpaces::SRGB | SurfaceColorSpaces::BT2100_PQ),
311        ];
312        assert_eq!(negotiate(&hdr, true, Some(600.0)).unwrap().mode, OutputMode::Pq);
313        assert_eq!(negotiate(&hdr, true, Some(600.0)).unwrap().peak_nits, 600.0);
314        assert_eq!(negotiate(&hdr[..2], true, None).unwrap().mode, OutputMode::ScRgb);
315        assert_eq!(negotiate(&hdr, false, None).unwrap().mode, OutputMode::SdrSrgbFormat);
316        // Absurd peaks are ignored.
317        assert_eq!(negotiate(&hdr, true, Some(f32::NAN)).unwrap().peak_nits, DEFAULT_PEAK_NITS);
318        assert_eq!(negotiate(&hdr, true, Some(1e9)).unwrap().peak_nits, DEFAULT_PEAK_NITS);
319    }
320
321    #[test]
322    fn encodings() {
323        let o = Output { format: TextureFormat::Rgba16Float, color_space: SurfaceColorSpace::ExtendedSrgbLinear, mode: OutputMode::ScRgb, paper_white_nits: 203.0, peak_nits: 1000.0 };
324        // Paper white is 203 nits = 2.5375 in scRGB; below the knee it is untouched.
325        assert!((encode_output([1.0; 3], &o)[0] - 203.0 / 80.0).abs() < 1e-5);
326        let p = Output { mode: OutputMode::Pq, format: TextureFormat::Rgb10a2Unorm, color_space: SurfaceColorSpace::Bt2100Pq, ..o };
327        assert!((encode_output([1.0; 3], &p)[1] - pq_oetf(203.0)).abs() < 1e-4);
328        // Nothing exceeds the peak however bright the scene.
329        let top = encode_output([1e6; 3], &p)[0];
330        assert!(top <= pq_oetf(1000.0) + 1e-5);
331        let s = Output { mode: OutputMode::SdrSrgbFormat, ..o };
332        assert!(encode_output([50.0; 3], &s)[0] <= 1.0);
333    }
334
335    #[test]
336    fn hdr_metadata_validation() {
337        use crate::display::HdrMetadata;
338        let ok = HdrMetadata::bt2020(1000.0, 0.005, 1000.0, 400.0);
339        assert_eq!(ok.check(), None);
340        assert_eq!(HdrMetadata::from_bytes(&ok.to_bytes()), Some(ok));
341        assert!(HdrMetadata { max_luminance: f32::NAN, ..ok }.check().is_some());
342        assert!(HdrMetadata { max_luminance: 1e9, ..ok }.check().is_some());
343        assert!(HdrMetadata { min_luminance: 2000.0, ..ok }.check().is_some());
344        assert!(HdrMetadata { red: [0.9, 0.9], ..ok }.check().is_some());
345        assert!(HdrMetadata { max_fall: 2000.0, ..ok }.check().is_some());
346        assert!(HdrMetadata { max_cll: -1.0, ..ok }.check().is_some());
347        assert!(HdrMetadata::from_bytes(&[0u8; 47]).is_none());
348    }
349}