HDR: light itself above paper white

Surfaces at the strongest block and sky light rise above paper white, sky light by how a face
meets the sun, and the whole of it eases into the peak. Part of the frame's alpha carries it
to the last pass, where it amounts to vanilla's lightmap going past 1. Off while a shader
pack's post or material stage runs. Fog and water take it away as they should.

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

crates/horizon-client-render/src/entity.wgsl

@@ -31,6 +31,9 @@ struct Globals {
     // HDR output's tier windows (hdr.rs `Hdr::windows`): x..w low to very bright,
     // [0] where the lift starts, [1] where it is full.
     hdr_windows: array<vec4<f32>, 2>,
+    // HDR lighting: x how strongly the sky lights the world now (`Sky::sky_light_factor`),
+    // y what the sky and fog get: the same, but none under water.
+    hdr_light: vec4<f32>,
 }
 @group(0) @binding(0) var<uniform> globals: Globals;
 @group(0) @binding(1) var atlas: texture_2d<f32>;
@@ -69,6 +72,8 @@ struct Out {
     // HDR tier of a light-giving particle (mesher::hdr_tier), from the overlay's
     // high bits (particles.rs): fs_hdr_mark marks the frame with it.
     @location(13) @interpolate(flat) tier: u32,
+    // HDR lighting (`hdr_scene`), 0 for what isn't lit.
+    @location(14) scene: f32,
 }
 // Shipped light.glsl; normals are already transformed and RGBA8_SNORM packed.
 fn entity_light(normal: vec3<f32>, nether: bool) -> f32 {
@@ -107,6 +112,16 @@ fn native_colored_light(pos: vec3<f32>) -> vec3<f32> {
     }
     return min(rgb, vec3(1.0));
 }
+// HDR lighting: how far an entity's light carries it above paper white, 0 to 1, as terrain's.
+fn hdr_scene(block: f32, sky: f32) -> f32 {
+    let b = smoothstep(11.0, 15.0, block);
+    let s = smoothstep(11.0, 15.0, sky) * globals.hdr_light.x;
+    return max(b, s);
+}
+// The frame's alpha for it, between 1 (none) and the light sources' marks below 0.75.
+fn hdr_scene_alpha(scene: f32) -> f32 {
+    return 1.0 - 0.24 * scene;
+}
 fn entity_vertex(position: vec3<f32>, uv: vec2<f32>,
     overlay: u32, color: vec4<f32>, light: vec4<u32>, normal: vec4<f32>) -> Out {
     var out: Out;
@@ -120,6 +135,7 @@ fn entity_vertex(position: vec3<f32>, uv: vec2<f32>,
     let unlit = overlay == 2u || overlay == 4u || overlay == 6u || overlay == 9u || overlay == 10u
         || overlay == 11u || overlay == 12u;
     out.light_color = select(lm, vec4(1.0), unlit);
+    out.scene = select(hdr_scene(l.x / 16.0, l.y / 16.0), 0.0, unlit);
     if globals.colored_count.x > 0u && !unlit {
         out.light_color = vec4(min(out.light_color.rgb + native_colored_light(position), vec3(1.0)), out.light_color.a);
     }
@@ -328,10 +344,13 @@ fn shadow_color(in: Out) -> vec4<f32> {
     var uv = in.uv;
     if in.overlay == 6u { uv.y = in.wrap.x + fract(in.uv.y) * in.wrap.y; }
     let texel = textureSample(atlas, atlas_sampler, uv);
-    if in.tier == 0u || texel.a < 0.1 { discard; }
-    // Fog hides a light source as it hides everything else.
+    if texel.a < 0.1 { discard; }
+    // Fog hides a light source and the light on a surface as it hides everything else.
     let fogged = max(linear_fog(in.spherical, globals.fog.x, globals.fog.y),
         linear_fog(in.cylindrical, globals.fog.z, globals.fog.w)) * globals.fog_color.a;
+    if in.tier == 0u {
+        return vec4(0.0, 0.0, 0.0, hdr_scene_alpha(mix(in.scene, globals.hdr_light.y, fogged)));
+    }
     return vec4(0.0, 0.0, 0.0, hdr_mark(in.tier, brightness(texel.rgb * in.color.rgb) * (1.0 - fogged)));
 }
 fn brightness(c: vec3<f32>) -> f32 {
@@ -351,7 +370,7 @@ fn hdr_mark(tier: u32, y: f32) -> f32 {
 // no longer shines; fs_hdr_mark then marks the light sources it holds.
 @fragment fn fs_hdr_hand_unmark(in: Out) -> @location(0) vec4<f32> {
     if textureSample(atlas, atlas_sampler, in.uv).a < 0.1 { discard; }
-    return vec4(0.0, 0.0, 0.0, 1.0);
+    return vec4(0.0, 0.0, 0.0, hdr_scene_alpha(in.scene));
 }
 
 fn celestial_color(in: Out) -> vec4<f32> {
@@ -378,8 +397,12 @@ fn celestial_color(in: Out) -> vec4<f32> {
     let added = color.rgb * color.a;
     // The sun at the brightest tier, the moon at its own (in.tier); geometry that sets
     // none (the End sky, the End flash) stays brightest.
-    let keep = 1.0 - hdr_mark(select(in.tier, 4u, in.tier == 0u), brightness(added));
-    return vec4(added, keep * smoothstep(0.1, 0.3, max(added.r, max(added.g, added.b))));
+    let tier = select(in.tier, 4u, in.tier == 0u);
+    let y = brightness(added);
+    // Only what's past the tier's window takes the mark: a soft edge keeps the sky's light,
+    // or it would come out darker than the sky around it.
+    if y < globals.hdr_windows[1][clamp(tier, 1u, 4u) - 1u] { return vec4(added, 0.0); }
+    return vec4(added, 1.0 - hdr_mark(tier, y));
 }
 
 // RenderPipelines.ENERGY_SWIRL (entity.fsh with EMISSIVE and NO_OVERLAY): the sprite, scrolled by

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

@@ -328,6 +328,7 @@ struct Globals {
     /// HDR output's tier windows, low to very bright: where the lift starts, where it is
     /// full (`hdr::Hdr::windows`); zero without HDR.
     hdr_windows: [[f32; 4]; 2],
+    hdr_light: [f32; 4],
 }
 pub type SectionKey = (i32, i32, i32);
 /// The water mirror's targets: the world as a camera mirrored about the water plane sees
@@ -5643,6 +5644,17 @@ impl Renderer {
                 0.0,
             ],
             hdr_windows: self.hdr.as_ref().map_or([[0.0; 4]; 2], hdr::Hdr::windows),
+            hdr_light: [
+                frame.sky.sky_light_factor,
+                // The underwater overlay: the sky and fog are the water's own colour there.
+                if frame.screen.iter().any(|q| q.world_tint) {
+                    0.0
+                } else {
+                    frame.sky.sky_light_factor
+                },
+                0.0,
+                0.0,
+            ],
         };
         self.uploads
             .buffer(&mut encoder, &self.globals, 0, bytemuck::bytes_of(&globals));
@@ -6320,6 +6332,12 @@ impl Renderer {
         }
         // GameRenderer.useImprovedTransparency. A shader pack keeps its own
         // path.
+        let hdr_lighting = self.native.is_none()
+            && self.pack_post.as_ref().is_none_or(|p| p.1.is_none())
+            && std::env::var_os("HORIZON_HDR_LIGHTING").is_none_or(|v| v != "0");
+        if let Some(hdr) = &mut self.hdr {
+            hdr.lighting = hdr_lighting;
+        }
         let oit_on = self.improved_transparency
             && !frame.title
             && self.pack_post.as_ref().is_none_or(|p| p.1.is_none())

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

@@ -149,6 +149,9 @@ pub struct Hdr {
     pub ui: f32,
     /// Which pixels of a light source shine (`Masks`).
     pub masks: Masks,
+    /// HDR lighting: off while a shader pack's post or material stage runs, the pack's own, and
+    /// with `HORIZON_HDR_LIGHTING=0`, to compare.
+    pub lighting: bool,
     /// Calibration's test picture while it runs.
     pub calibration: Option<Calibration>,
 }
@@ -293,6 +296,7 @@ impl Hdr {
             tiers: TIERS,
             ui: 1.0,
             masks: MASKS,
+            lighting: true,
             calibration: None,
         }
     }
@@ -539,6 +543,11 @@ impl Hdr {
         ]);
         params[5] = self.black.clamp(0.0, paper);
         params[6] = self.ui.clamp(0.25, 1.0);
+        params[7] = if self.lighting {
+            scene_gain(self.peak, self.paper_white)
+        } else {
+            1.0
+        };
         for (i, t) in self.tiers.iter().enumerate() {
             params[8 + i] = t.share;
         }
@@ -618,6 +627,12 @@ fn logo_mask(device: &wgpu::Device, queue: &wgpu::Queue) -> wgpu::TextureView {
         .create_view(&Default::default())
 }
 
+/// What the strongest light multiplies a surface by, in HDR lighting: 4, which looked right
+/// across biomes; less only where there is little headroom to ease into (`hdr.wgsl`).
+fn scene_gain(peak: f32, paper_white: f32) -> f32 {
+    (peak / paper_white.max(1.0) * 1.75).clamp(1.0, 4.0)
+}
+
 #[cfg(test)]
 mod tests {
     use super::{Output, pick};
@@ -670,3 +685,18 @@ mod tests {
         assert_eq!(pick(&caps(&[(F::Bgra8UnormSrgb, S::SRGB)]), None), None);
     }
 }
+
+#[cfg(test)]
+mod lighting_tests {
+    use super::scene_gain;
+
+    #[test]
+    fn the_lighting_scales_with_the_headroom() {
+        // Enough headroom: the full strength, whatever the paper white.
+        assert_eq!(scene_gain(1000.0, 430.0), 4.0);
+        assert_eq!(scene_gain(1060.0, 203.0), 4.0);
+        // Little headroom, and none.
+        assert_eq!(scene_gain(600.0, 400.0), 2.625);
+        assert_eq!(scene_gain(200.0, 480.0), 1.0);
+    }
+}

crates/horizon-client-render/src/hdr.wgsl

@@ -20,6 +20,8 @@ struct Params {
     black: f32,
     // The HUD and menus' brightness as a share of paper white.
     ui: f32,
+    // HDR lighting: what the strongest light multiplies a surface by, 1 for none.
+    scene: f32,
     // Per tier, low to very bright (hdr.rs `Tier`): the share of the headroom
     // its fully lifted pixels get.
     share: vec4<f32>,
@@ -168,8 +170,23 @@ fn calibration_nits(p: vec2<f32>, size: vec2<f32>) -> f32 {
     // lower the brighter, and where in the band how much (hdr_mark). The hand
     // writes its own alpha there (Hdr::hand_light_view): 1, or a light source it holds.
     var lifted = false;
-    if params.world > 0.5 && params.peak > 1.0 && w.a < 0.75
-        && (hand || (!covered && shows_world(c, w.rgb))) {
+    let shows = params.world > 0.5 && params.peak > 1.0
+        && (hand || (!covered && shows_world(c, w.rgb)));
+    // HDR lighting: alpha between 0.76 and 1 is how much of it the surface gets. Vanilla's
+    // light is albedo times lightmap, so this is the lightmap going past 1. It eases into the
+    // peak from 60% of it, so bright textures keep their detail.
+    if shows && w.a >= 0.75 {
+        let top = max(light.r, max(light.g, light.b));
+        let gain = 1.0 + (params.scene - 1.0) * (1.0 - w.a) / 0.24;
+        let v = top * gain;
+        let knee = max(0.6 * params.peak, 1.0);
+        var out = v;
+        if v > knee && params.peak > knee {
+            out = knee + (params.peak - knee) * (1.0 - exp(-(v - knee) / (params.peak - knee)));
+        }
+        light *= select(gain, out / max(top, 1e-4), v > knee);
+    }
+    if shows && w.a < 0.75 {
         let band = u32(clamp(floor((w.a + 0.005) / 0.175), 0.0, 3.0));
         let tier = 3u - band;
         let lift = 1.0 - clamp((w.a - 0.175 * f32(band)) / 0.165, 0.0, 1.0);

crates/horizon-client-render/src/terrain.wgsl

@@ -37,6 +37,9 @@ struct Globals {
     // HDR output's tier windows (hdr.rs `Hdr::windows`): x..w low to very bright,
     // [0] where the lift starts, [1] where it is full.
     hdr_windows: array<vec4<f32>, 2>,
+    // HDR lighting: x how strongly the sky lights the world now (`Sky::sky_light_factor`),
+    // y what the sky and fog get: the same, but none under water.
+    hdr_light: vec4<f32>,
 }
 @group(0) @binding(0) var<uniform> globals: Globals;
 @group(0) @binding(1) var sprites: texture_2d_array<f32>;
@@ -171,6 +174,8 @@ struct TerrainOut {
     // How the face shines in HDR output (mesher.rs's `EMISSION_BITS`): 0 not
     // at all, 1 to 4 the tier with its bright parts, 5 to 8 the tier all over.
     @location(5) @interpolate(flat) emission: u32,
+    // HDR lighting: block and sky light, as levels 0 to 15.
+    @location(11) scene: vec2<f32>,
     @location(6) @interpolate(flat) fade: u32,
     // A distant tile's tile-relative position, for its fade (`faded`).
     @location(7) local: vec3<f32>,
@@ -361,6 +366,22 @@ fn left_out() -> TerrainOut {
     return terrain_vertex(position, terrain_uv(uv, origin.w), layer, color, light, origin.xyz,
         origin.w);
 }
+// HDR lighting: how far a surface's light carries it above paper white, 0 to 1. Only the
+// strongest light does, so dark stays as dark as in SDR; sky light by how the face meets the sun.
+fn hdr_scene(block: f32, sky: f32, facing: f32) -> f32 {
+    let b = smoothstep(11.0, 15.0, block);
+    let s = smoothstep(11.0, 15.0, sky) * globals.hdr_light.x * facing;
+    return max(b, s);
+}
+// The frame's alpha for it, between 1 (none) and the light sources' marks below 0.75.
+fn hdr_scene_alpha(scene: f32) -> f32 {
+    return 1.0 - 0.24 * scene;
+}
+// The face's normal, from the fragment's derivatives, for how it faces the sun.
+var<private> hdr_normal: vec3<f32>;
+fn hdr_facing() -> f32 {
+    return mix(0.45, 1.0, max(dot(hdr_normal, globals.sun.xyz), 0.0));
+}
 fn terrain_vertex(position: vec3<f32>, uv: vec2<f32>, layer: u32, color: vec4<f32>,
     light: vec2<u32>, origin: vec3<f32>, w: f32) -> TerrainOut {
     let pos = position + origin;
@@ -384,6 +405,7 @@ fn terrain_vertex(position: vec3<f32>, uv: vec2<f32>, layer: u32, color: vec4<f3
     }
     let block = max(f32(light.y), dynamic_block_light(pos));
     out.color = vec4(color.rgb, 1.0) * sample_lightmap(f32(light.x) / 16.0, block / 16.0);
+    out.scene = vec2(block / 16.0, f32(light.x) / 16.0);
     if globals.colored_count.x > 0u {
         out.color = vec4(min(out.color.rgb + color.rgb * native_colored_light(pos), vec3(1.0)), out.color.a);
     }
@@ -426,6 +448,7 @@ fn hdr_mark(tier: u32, y: f32) -> f32 {
 }
 // `fs_solid` for the opaque pass (`opaque_quad`): no fade, no cutout, no discard.
 @fragment fn fs_opaque(in: TerrainOut) -> @location(0) vec4<f32> {
+    hdr_normal = normalize(cross(dpdy(in.local), dpdx(in.local)));
     let texel = sprite(in.uv, in.layer & 0x7fffu);
     var color = texel * in.color;
     color = mix(globals.fog_color * vec4(1.0, 1.0, 1.0, color.a), color, in.visibility);
@@ -440,6 +463,7 @@ fn hdr_mark(tier: u32, y: f32) -> f32 {
 fn solid_color(in: TerrainOut) -> vec4<f32> {
     let dx = dpdx(in.local);
     let dy = dpdy(in.local);
+    hdr_normal = normalize(cross(dy, dx));
     if faded(in.fade, in.local, dx, dy) { discard; }
     // Bit 15 of the layer marks opaque leaves (forceOpaque): no alpha cutout.
     let texel = sprite(in.uv, in.layer & 0x7fffu);
@@ -456,8 +480,15 @@ fn solid_finish(in: TerrainOut, texel: vec4<f32>, color: vec4<f32>) -> vec4<f32>
     // texel's own brightness, so its light level and face shading don't change
     // it. Only pixels as bright as their sprite's threshold may: its bright
     // parts, or all of it. Nothing else reads the frame's alpha.
-    var emissive = 1.0;
+    // Fog turns a far surface into the fog's colour: it takes the fog's light with it, or a
+    // fully fogged mountain would stand out from the fog behind it.
+    let fogged = max(linear_fog(in.spherical, globals.fog.x, globals.fog.y),
+        linear_fog(in.cylindrical, globals.fog.z, globals.fog.w)) * globals.fog_color.a;
+    var emissive = hdr_scene_alpha(mix(hdr_scene(in.scene.x, in.scene.y, hdr_facing()),
+        globals.hdr_light.y, fogged));
     if in.emission > 0u {
+        // A light source's own face shines as one or stays as drawn, without the lighting.
+        emissive = 1.0;
         let whole = in.emission > 4u;
         let tier = select(in.emission, in.emission - 4u, whole);
         let l = in.layer & 0x7fffu;
@@ -466,8 +497,6 @@ fn solid_finish(in: TerrainOut, texel: vec4<f32>, color: vec4<f32>) -> vec4<f32>
         // All over means all over: the sprite's range is one frame's, and an animated sprite's
         // other frames dip below it. Fog hides a light source as it hides everything else.
         if whole || y >= t.r {
-            let fogged = max(linear_fog(in.spherical, globals.fog.x, globals.fog.y),
-                linear_fog(in.cylindrical, globals.fog.z, globals.fog.w)) * globals.fog_color.a;
             emissive = hdr_mark(tier, y * (1.0 - fogged));
         }
     }
@@ -616,7 +645,8 @@ fn sky_along_ray(d: vec3<f32>) -> vec3<f32> {
     return color;
 }
 @fragment fn fs_sky(in: SkyOut) -> @location(0) vec4<f32> {
-    return vec4(sky_along_ray(view_ray(in.ndc)), 1.0);
+    // `hdr_scene_alpha`, spelled out: this part of the file also goes into shader packs' skies.
+    return vec4(sky_along_ray(view_ray(in.ndc)), 1.0 - 0.24 * globals.hdr_light.y);
 }
 // The first-person hand's depth clear inside the world pass: `vs_sky`'s triangle lies at the
 // far plane, written over the whole depth target with no colour.

docs/graphics.md

@@ -37,6 +37,8 @@ Every row has a one-line description and its cost in frame time (none, low, medi
 
 **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. Glowing items shine by their block's tier when dropped, framed, or held by anyone, your own hand included; the hand itself stays at the world's brightness. Not lifted yet: translucent blocks (the nether portal), distant LOD terrain.
 
+HDR also lights the world past paper white: surfaces at block or sky light levels 11 to 15 rise above it, up to 4 times for the strongest light, sky light by how a face meets the sun, easing into the peak from 60% of it so bright textures keep their detail. The frame's alpha between 0.76 and 1 carries it to the last pass, where it amounts to the lightmap going past 1. Darker light stays as in SDR. It's off while a shader pack's post or material stage runs, and `HORIZON_HDR_LIGHTING=0` turns it off to compare.
+
 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, the texel's own before lighting, so a light source shines alike at any light level and on every face (`gfx/hdr.rs` `TIERS`); `HORIZON_HDR_DEBUG=1` greys what isn't lifted and tints what is magenta.
 
 Which settings each screen shows, their descriptions and costs are in `crates/horizon-client-render/src/graphics_ui.rs` (`rows`); `graphics_style.rs` draws them.