@woosh/meep-engine 3.47.0 → 3.49.0

package/src/shade/renderer/shader/chunk/color/tonemap/chunk_tonemap_khronos_pbr.js

@@ -1,35 +1,48 @@
 import { CodeChunk } from "../../../compiler/CodeChunk.js";
 
 /**
+ * Khronos PBR Neutral, with the display's peak in place of the specification's 1.
  *
- * @see https://www.shadertoy.com/view/lXSBzt
+ * - At `peak` 1 it is the specification: base colours under 0.8 come out 1:1, less the 0.04 Fresnel offset, and a
+ *   highlight compresses toward 1 and desaturates toward white.
+ * - At a higher peak the compression starts at the same place, converges on the peak instead of 1, and desaturates by
+ *   how much it compressed. Below the start every peak writes the same colour, so an SDR and an HDR display agree
+ *   there.
+ *
+ * The specification has no HDR form. Lalish's write-up names the 0.8 start as the place to adapt it. Keeping the start
+ * where it is, rather than moving it with the peak, keeps SDR and HDR closest; HDR_TONE_MAPPING_FORMS_BRIEF_2026_10_16.md
+ * beside this file has the measurements.
+ *
+ * Input: non-negative linear Rec.709. Output: linear Rec.709, never above `peak`, which must be at least 1.
+ *
+ * @see https://github.com/KhronosGroup/ToneMapping/tree/main/PBR_Neutral
  * @see https://modelviewer.dev/examples/tone-mapping
  * @type {CodeChunk}
  */
 export const chunk_tonemap_khronos_pbr = CodeChunk.from(
     //language=WGSL
     `
-fn tonemap_khronos_pbr( in_color: vec3<f32> ) -> vec3<f32> {
+fn tonemap_khronos_pbr( in_color: vec3<f32>, peak: f32 ) -> vec3<f32> {
 
     const startCompression = 0.8 - 0.04;
     const desaturation = 0.15;
-    
+
     let x = min(in_color.r, min(in_color.g, in_color.b));
     let offset = select( 0.04, x - 6.25 * x * x, x < 0.08);
     var color = in_color - offset;
-    
-    let peak = max(color.r, max(color.g, color.b));
-    if (peak < startCompression) {
+
+    let color_peak = max(color.r, max(color.g, color.b));
+    if (color_peak < startCompression) {
         return color;
-    } 
-    
-    let d = 1. - startCompression;
-    let newPeak = 1. - d * d / (peak + d - startCompression);
-    color *= newPeak / peak;
-    
-    let g = 1. - 1. / (desaturation * (peak - newPeak) + 1.);
-    
+    }
+
+    let d = peak - startCompression;
+    let newPeak = peak - d * d / (color_peak + d - startCompression);
+    color *= newPeak / color_peak;
+
+    let g = 1. - 1. / (desaturation * (color_peak - newPeak) + 1.);
+
     return mix(color, newPeak * vec3(1, 1, 1), g);
 }
     `
-);
+);

package/src/shade/renderer/shader/chunk/color/tonemap/gt7/chunk_tonemap_gt7.d.ts

@@ -1,4 +1,16 @@
 /**
+ * GT7 tone mapping, after Polyphony's sample code (`gt7_tone_mapping.cpp`, SIGGRAPH 2025 PBS course).
+ *
+ * One function for every display, which is the point of the operator: `peak_nits` is the display's peak, and
+ * `paper_white_nits` is the luminance the input's 1.0 shows at. The output is in units of that paper white, in
+ * Rec.709. SDR is the sample code's `initializeAsSDR()`: peak and paper white both at {@link chunk_PAPER_WHITE_NITS},
+ * so the output reaches 1.0 and no further. HDR keeps the same paper white and raises the peak, so everything below
+ * the SDR shoulder comes out the same on both.
+ *
+ * It follows the sample code in the curve, the chroma fade, the blend ratio and the clamp at the target. It blends
+ * in ICtCp where the sample code blends in RGB. That costs up to 0.3 sRGB codes in the mid-tones and up to 14 in
+ * saturated highlights, measured against the compiled sample code over 648 inputs.
+ *
  * `REF_LUMINANCE` is the paper's "Standard 1.0 unit" and must stay equal to the `REFERENCE_LUMINANCE` in
  * {@link chunk_eotfSt2084} / {@link chunk_inverseEotfSt2084}, which this function round-trips through. It is
  * not the BT.2408 SDR white of 203 nits used on the CPU side; see the note on `chunk_eotfSt2084` for how the

package/src/shade/renderer/shader/chunk/color/tonemap/gt7/chunk_tonemap_gt7.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_tonemap_gt7.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/shade/renderer/shader/chunk/color/tonemap/gt7/chunk_tonemap_gt7.js"],"names":[],"mappings":"AAUA;;;;;;;;;GASG;AACH,gCAFU,SAAS,CA4FlB;0BA9GyB,mCAAmC"}
+{"version":3,"file":"chunk_tonemap_gt7.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/shade/renderer/shader/chunk/color/tonemap/gt7/chunk_tonemap_gt7.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,gCAFU,SAAS,CAkGlB;0BAhIyB,mCAAmC"}

package/src/shade/renderer/shader/chunk/color/tonemap/gt7/chunk_tonemap_gt7.js

@@ -1,111 +1,129 @@
-import { CodeChunk } from "../../../../compiler/CodeChunk.js";
-import { chunk_CRM_FROM_REC2020_TO_REC709 } from "../../conversion/chunk_CRM_FROM_REC2020_TO_REC709.js";
-import { chunk_CRM_FROM_REC709_TO_REC2020 } from "../../conversion/chunk_CRM_FROM_REC709_TO_REC2020.js";
-import { chunk_eotfSt2084 } from "../../iCtCp/chunk_eotf_st2084.js";
-import { chunk_iCtCp_to_rgb } from "../../iCtCp/chunk_iCtCp_to_rgb.js";
-import { chunk_inverseEotfSt2084 } from "../../iCtCp/chunk_inverse_eotf_st2084.js";
-import { chunk_rgb_to_iCtCp } from "../../iCtCp/chunk_rgb_to_iCtCp.js";
-import { chunk_gt_evaluate_curve } from "./chunk_gt_evaluate_curve.js";
-import { GT7_TONE_MAPPING_CURVE_STRUCT } from "./GT7_TONE_MAPPING_CURVE_STRUCT.js";
-
-/**
- * `REF_LUMINANCE` is the paper's "Standard 1.0 unit" and must stay equal to the `REFERENCE_LUMINANCE` in
- * {@link chunk_eotfSt2084} / {@link chunk_inverseEotfSt2084}, which this function round-trips through. It is
- * not the BT.2408 SDR white of 203 nits used on the CPU side; see the note on `chunk_eotfSt2084` for how the
- * three reference whites in this engine relate.
- *
- * @see "Driving Toward Reality: Physically Based Tone Mapping and Perceptual Fidelity in Gran Turismo 7"
- * @see chunk_eotfSt2084
- * @type {CodeChunk}
- */
-export const chunk_tonemap_gt7 = CodeChunk.from(
-    //language=WGSL
-    `
-fn tonemap_gt7(
-    rgb_rec709:vec3<f32>,
-    peak_nits: f32,
-    paper_white_nits: f32,
-) -> vec3<f32>{
-
-    // Constants for the GT7 "Standard" 1.0 unit
-    const REF_LUMINANCE: f32 = 100.0;
-    
-    // input is in rec.709, the tonemapper is in rec.2020
-    var color_linear = CRM_FROM_REC709_TO_REC2020 * rgb_rec709;
-    
-    // normalize to paper white
-    let paper_white = paper_white_nits / REF_LUMINANCE;
-    color_linear *= paper_white;
-    
-    var curve: ${GT7_TONE_MAPPING_CURVE_STRUCT.wgsl_ref};
-    // initialize curve
-    const alpha = 0.25;
-    const gray_point = 0.538;
-    const linear_section = 0.444;
-    const toe_strength = 1.280;
-    
-    let peak_intensity = peak_nits / REF_LUMINANCE;
-    
-    //
-    curve.peakIntensity = peak_intensity;
-    curve.midPoint = gray_point;
-    curve.linearSection = linear_section;
-    curve.toeStrength = toe_strength;
-    
-    // Pre-compute constants for the shoulder region.
-    let k = (linear_section - 1.0) / (alpha - 1.0);
-    curve.kA = peak_intensity * linear_section + peak_intensity * k;
-    curve.kB = -peak_intensity * k * exp(linear_section / k);
-    curve.kC = -1.0 / (k * peak_intensity);
-    
-    //
-    // PATH A: Create "Twisted" RGB (Per-channel Mapping)
-    // This creates the "film/camera-like" look where highlights shift to CMY/White
-    var rgb_twisted: vec3<f32>;
-    rgb_twisted.r = gt_evaluate_curve(&curve, color_linear.r);
-    rgb_twisted.g = gt_evaluate_curve(&curve, color_linear.g);
-    rgb_twisted.b = gt_evaluate_curve(&curve, color_linear.b);
-    
-   // PATH B: Create "Untwisted" RGB (Luminance from Twisted, Chroma from Original)
-    // 1. Get ICtCp for both Original and Twisted
-    let ictcp_original = rgb_to_iCtCp(color_linear);
-    let ictcp_twisted  = rgb_to_iCtCp(rgb_twisted);
-
-    const CHROMA_START_PQ = 0.7; 
-    const CHROMA_END_PQ = 1.0;
-
-    // 2. Calculate Whitening Scale based on Original Luminance (PQ encoded)
-    // As luminance increases, we reduce chroma to avoid artifacts and simulate saturation limit
-    let luminance_pq = ictcp_original.x; // rgb_to_iCtCp returns PQ encoding in X
-    let shoulder_saturation_scale = 1.0 - smoothstep(CHROMA_START_PQ, CHROMA_END_PQ, luminance_pq);
-
-    // Blend Ratio: 0.0 = Fully Untwisted (Preserves hue/sat), 1.0 = Fully Twisted (Camera-like shift)
-    const BLEND_RATIO = 0.7;
-        
-    // Mix between the Twisted (Per-channel) and Untwisted (ICtCp reconstructed) versions
-    let ictcp_final = vec3<f32>(
-        ictcp_twisted.x,
-        mix(ictcp_original.yz * shoulder_saturation_scale, ictcp_twisted.yz, BLEND_RATIO)
-    );
-    
-    var final_color = iCtCp_to_rgb(ictcp_final);
-        
-    // renormalize
-    final_color /= paper_white;
-    
-    // go back to rec.709
-    final_color = CRM_FROM_REC2020_TO_REC709 * final_color;
-    
-    return final_color;
-}
-    `, [
-        chunk_CRM_FROM_REC709_TO_REC2020,
-        chunk_CRM_FROM_REC2020_TO_REC709,
-        GT7_TONE_MAPPING_CURVE_STRUCT.declaration_chunk,
-        chunk_gt_evaluate_curve,
-        chunk_iCtCp_to_rgb,
-        chunk_rgb_to_iCtCp,
-            chunk_eotfSt2084,
-            chunk_inverseEotfSt2084,
-    ]
+import { CodeChunk } from "../../../../compiler/CodeChunk.js";
+import { chunk_CRM_FROM_REC2020_TO_REC709 } from "../../conversion/chunk_CRM_FROM_REC2020_TO_REC709.js";
+import { chunk_CRM_FROM_REC709_TO_REC2020 } from "../../conversion/chunk_CRM_FROM_REC709_TO_REC2020.js";
+import { chunk_eotfSt2084 } from "../../iCtCp/chunk_eotf_st2084.js";
+import { chunk_iCtCp_to_rgb } from "../../iCtCp/chunk_iCtCp_to_rgb.js";
+import { chunk_inverseEotfSt2084 } from "../../iCtCp/chunk_inverse_eotf_st2084.js";
+import { chunk_rgb_to_iCtCp } from "../../iCtCp/chunk_rgb_to_iCtCp.js";
+import { chunk_gt_evaluate_curve } from "./chunk_gt_evaluate_curve.js";
+import { GT7_TONE_MAPPING_CURVE_STRUCT } from "./GT7_TONE_MAPPING_CURVE_STRUCT.js";
+
+/**
+ * GT7 tone mapping, after Polyphony's sample code (`gt7_tone_mapping.cpp`, SIGGRAPH 2025 PBS course).
+ *
+ * One function for every display, which is the point of the operator: `peak_nits` is the display's peak, and
+ * `paper_white_nits` is the luminance the input's 1.0 shows at. The output is in units of that paper white, in
+ * Rec.709. SDR is the sample code's `initializeAsSDR()`: peak and paper white both at {@link chunk_PAPER_WHITE_NITS},
+ * so the output reaches 1.0 and no further. HDR keeps the same paper white and raises the peak, so everything below
+ * the SDR shoulder comes out the same on both.
+ *
+ * It follows the sample code in the curve, the chroma fade, the blend ratio and the clamp at the target. It blends
+ * in ICtCp where the sample code blends in RGB. That costs up to 0.3 sRGB codes in the mid-tones and up to 14 in
+ * saturated highlights, measured against the compiled sample code over 648 inputs.
+ *
+ * `REF_LUMINANCE` is the paper's "Standard 1.0 unit" and must stay equal to the `REFERENCE_LUMINANCE` in
+ * {@link chunk_eotfSt2084} / {@link chunk_inverseEotfSt2084}, which this function round-trips through. It is
+ * not the BT.2408 SDR white of 203 nits used on the CPU side; see the note on `chunk_eotfSt2084` for how the
+ * three reference whites in this engine relate.
+ *
+ * @see "Driving Toward Reality: Physically Based Tone Mapping and Perceptual Fidelity in Gran Turismo 7"
+ * @see chunk_eotfSt2084
+ * @type {CodeChunk}
+ */
+export const chunk_tonemap_gt7 = CodeChunk.from(
+    //language=WGSL
+    `
+fn tonemap_gt7(
+    rgb_rec709:vec3<f32>,
+    peak_nits: f32,
+    paper_white_nits: f32,
+) -> vec3<f32>{
+
+    // Constants for the GT7 "Standard" 1.0 unit
+    const REF_LUMINANCE: f32 = 100.0;
+    
+    // input is in rec.709, the tonemapper is in rec.2020
+    var color_linear = CRM_FROM_REC709_TO_REC2020 * rgb_rec709;
+    
+    // normalize to paper white
+    let paper_white = paper_white_nits / REF_LUMINANCE;
+    color_linear *= paper_white;
+    
+    var curve: ${GT7_TONE_MAPPING_CURVE_STRUCT.wgsl_ref};
+    // initialize curve
+    const alpha = 0.25;
+    const gray_point = 0.538;
+    const linear_section = 0.444;
+    const toe_strength = 1.280;
+    
+    let peak_intensity = peak_nits / REF_LUMINANCE;
+    
+    //
+    curve.peakIntensity = peak_intensity;
+    curve.midPoint = gray_point;
+    curve.linearSection = linear_section;
+    curve.toeStrength = toe_strength;
+    
+    // Pre-compute constants for the shoulder region.
+    let k = (linear_section - 1.0) / (alpha - 1.0);
+    curve.kA = peak_intensity * linear_section + peak_intensity * k;
+    curve.kB = -peak_intensity * k * exp(linear_section / k);
+    curve.kC = -1.0 / (k * peak_intensity);
+    
+    //
+    // PATH A: Create "Twisted" RGB (Per-channel Mapping)
+    // This creates the "film/camera-like" look where highlights shift to CMY/White
+    var rgb_twisted: vec3<f32>;
+    rgb_twisted.r = gt_evaluate_curve(&curve, color_linear.r);
+    rgb_twisted.g = gt_evaluate_curve(&curve, color_linear.g);
+    rgb_twisted.b = gt_evaluate_curve(&curve, color_linear.b);
+    
+   // PATH B: Create "Untwisted" RGB (Luminance from Twisted, Chroma from Original)
+    // 1. Get ICtCp for both Original and Twisted
+    let ictcp_original = rgb_to_iCtCp(color_linear);
+    let ictcp_twisted  = rgb_to_iCtCp(rgb_twisted);
+
+    // GT7ToneMapping::fadeStart_ and fadeEnd_, as fractions of the target's own intensity
+    const FADE_START = 0.98;
+    const FADE_END = 1.16;
+
+    // 2. Fade the original's chroma toward white as its intensity reaches the target's. Relative to the target,
+    // so the fade sits at the shoulder for every peak, a 250 cd/m² SDR target as much as a 1000 cd/m² display.
+    let target_intensity = rgb_to_iCtCp(vec3<f32>(peak_intensity)).x;
+    let shoulder_saturation_scale = 1.0 - smoothstep(FADE_START, FADE_END, ictcp_original.x / target_intensity);
+
+    // GT7ToneMapping::blendRatio_: the untwisted colour's share, 0.6, so the twisted colour keeps 0.4
+    const BLEND_RATIO = 0.6;
+
+    // Mix between the Twisted (Per-channel) and Untwisted (ICtCp reconstructed) versions. The sample code blends
+    // in RGB; this blends in ICtCp, which the talk says works as well (slides 150 and 153).
+    let ictcp_final = vec3<f32>(
+        ictcp_twisted.x,
+        mix(ictcp_twisted.yz, ictcp_original.yz * shoulder_saturation_scale, BLEND_RATIO)
+    );
+
+    var final_color = iCtCp_to_rgb(ictcp_final);
+
+    // never past the target: the sample code's min(blended, framebufferLuminanceTarget_). The shoulder converges
+    // on 1.185 times the peak, so without this a white overshoots the display by 18.5%.
+    final_color = min(final_color, vec3<f32>(peak_intensity));
+
+    // renormalize
+    final_color /= paper_white;
+    
+    // go back to rec.709
+    final_color = CRM_FROM_REC2020_TO_REC709 * final_color;
+    
+    return final_color;
+}
+    `, [
+        chunk_CRM_FROM_REC709_TO_REC2020,
+        chunk_CRM_FROM_REC2020_TO_REC709,
+        GT7_TONE_MAPPING_CURVE_STRUCT.declaration_chunk,
+        chunk_gt_evaluate_curve,
+        chunk_iCtCp_to_rgb,
+        chunk_rgb_to_iCtCp,
+            chunk_eotfSt2084,
+            chunk_inverseEotfSt2084,
+    ]
 )

package/src/shade/renderer/shader/chunk/geometry/ray/chunk_offset_ray_from_depth.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Where a ray starts from a surface position rebuilt from the depth buffer.
+ *
+ * {@link chunk_offset_ray} offsets in proportion to the position's own magnitude, which is the error of
+ * a ray's hit. A position rebuilt from depth is off by an amount that grows with its distance from the
+ * camera instead, so ground near the world's origin seen from far away gets almost no offset (1.5e-5 m
+ * at y = 0, whatever the distance), starts under its own surface and shadows itself. This first steps
+ * along the geometric normal in proportion to that distance.
+ *
+ * `DEPTH_RAY_NORMAL_OFFSET` is measured: on an RTX 4090 at 1578×802 (contact-shadow playground, still
+ * camera), counting pixels a ray toward the sun's centre finds shadowed, `offset_ray` alone gives
+ * 180,140 in `combine` and 96,352 in `grazing` (the far ground shadowing itself); 43,101 and 45,579 at
+ * 1e-6 of the distance; 25,166 and 9,709 at 1e-5, where both settle (3e-5 … 3e-4 within 0.2% of it); at
+ * 1e-3 real contacts start to go. 3e-5 is three times the onset.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_offset_ray_from_depth: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_offset_ray_from_depth.d.ts.map

package/src/shade/renderer/shader/chunk/geometry/ray/chunk_offset_ray_from_depth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_offset_ray_from_depth.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/ray/chunk_offset_ray_from_depth.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AACH,0CAFU,SAAS,CAcZ;0BAhCmB,gCAAgC"}

package/src/shade/renderer/shader/chunk/geometry/ray/chunk_offset_ray_from_depth.js

@@ -0,0 +1,33 @@
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+import { chunk_offset_ray } from "./chunk_offset_ray.js";
+
+/**
+ * Where a ray starts from a surface position rebuilt from the depth buffer.
+ *
+ * {@link chunk_offset_ray} offsets in proportion to the position's own magnitude, which is the error of
+ * a ray's hit. A position rebuilt from depth is off by an amount that grows with its distance from the
+ * camera instead, so ground near the world's origin seen from far away gets almost no offset (1.5e-5 m
+ * at y = 0, whatever the distance), starts under its own surface and shadows itself. This first steps
+ * along the geometric normal in proportion to that distance.
+ *
+ * `DEPTH_RAY_NORMAL_OFFSET` is measured: on an RTX 4090 at 1578×802 (contact-shadow playground, still
+ * camera), counting pixels a ray toward the sun's centre finds shadowed, `offset_ray` alone gives
+ * 180,140 in `combine` and 96,352 in `grazing` (the far ground shadowing itself); 43,101 and 45,579 at
+ * 1e-6 of the distance; 25,166 and 9,709 at 1e-5, where both settle (3e-5 … 3e-4 within 0.2% of it); at
+ * 1e-3 real contacts start to go. 3e-5 is three times the onset.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_offset_ray_from_depth = CodeChunk.from(
+    //language=WGSL
+    `
+const DEPTH_RAY_NORMAL_OFFSET: f32 = 3e-5;
+
+fn offset_ray_from_depth(position: vec3<f32>, geometric_normal: vec3<f32>, camera_position: vec3<f32>) -> vec3<f32> {
+    let view_distance = length(position - camera_position);
+
+    return offset_ray(position + geometric_normal * (DEPTH_RAY_NORMAL_OFFSET * view_distance), geometric_normal);
+}
+`, [
+        chunk_offset_ray
+    ]);

package/src/shade/renderer/shader/chunk/light/chunk_compute_multiscattering_specular.d.ts

@@ -1,6 +1,10 @@
 /**
  * @see "Practical multiple scattering compensation for microfacet models" by Emmanuel Turquin
  * Approximates multiple-scattering to preserve energy.
+ *
+ * `specularF0` is the surface's F0, the metalness blend of `specularF0_dielectric` and `specularF0_metal`.
+ * The pure two are needed because the term is quadratic in F0 while metalness blends linearly; see
+ * `MULTISCATTER.md` in `chunk/material`.
  */
 export const chunk_compute_multiscattering_specular: CodeChunk;
 import { CodeChunk } from "../../compiler/CodeChunk.js";

package/src/shade/renderer/shader/chunk/light/chunk_compute_multiscattering_specular.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_compute_multiscattering_specular.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/light/chunk_compute_multiscattering_specular.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH,+DAoCC;0BA1CyB,6BAA6B"}
+{"version":3,"file":"chunk_compute_multiscattering_specular.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/light/chunk_compute_multiscattering_specular.js"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,+DA2CC;0BArDyB,6BAA6B"}

package/src/shade/renderer/shader/chunk/light/chunk_compute_multiscattering_specular.js

@@ -3,6 +3,10 @@ import { CodeChunk } from "../../compiler/CodeChunk.js";
 /**
  * @see "Practical multiple scattering compensation for microfacet models" by Emmanuel Turquin
  * Approximates multiple-scattering to preserve energy.
+ *
+ * `specularF0` is the surface's F0, the metalness blend of `specularF0_dielectric` and `specularF0_metal`.
+ * The pure two are needed because the term is quadratic in F0 while metalness blends linearly; see
+ * `MULTISCATTER.md` in `chunk/material`.
  */
 export const chunk_compute_multiscattering_specular = CodeChunk.from(
 // language=WGSL
@@ -10,6 +14,8 @@ export const chunk_compute_multiscattering_specular = CodeChunk.from(
 fn compute_multiscattering_specular( 
     AB: vec2<f32>,
     specularF0: vec3<f32>,
+    specularF0_dielectric: vec3<f32>,
+    specularF0_metal: vec3<f32>,
     specularF90: f32,
     single_scatter: ptr<function, vec3<f32>>,
     multi_scatter: ptr<function, vec3<f32>> 
@@ -30,13 +36,18 @@ fn compute_multiscattering_specular(
 	
     let Ess_clamped = max(Ess, 1e-4); // Avoid div by zero
     let Kms = Ems / Ess_clamped;
+
+    // Fms = F0 makes the term quadratic in F0, so at the metalness blend of two F0s it is not the blend of
+    // the term at each: it falls short by Kms * A * m(1 - m)(F0_metal - F0_dielectric)^2. That is the
+    // product below, written without the metalness; zero for a pure dielectric and for a pure metal.
+    let F0_variance = (f0 - specularF0_dielectric) * (specularF0_metal - f0);
             
     // write out
 	*single_scatter += FssEss;
 	
     // The multi-scattering contribution is the single scattering scaled by (Fms * Kms).
     // Note: This maintains the "shape" of the specular highlight.
-	*multi_scatter += FssEss * (Fms * Kms);
+	*multi_scatter += FssEss * (Fms * Kms) + Kms * AB.x * F0_variance;
 	
 }
     `

package/src/shade/renderer/shader/chunk/material/MATERIAL_SHADING_INFO_STRUCT.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MATERIAL_SHADING_INFO_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/material/MATERIAL_SHADING_INFO_STRUCT.js"],"names":[],"mappings":"AAIA,wDAgB0B;6BAnBG,4BAA4B"}
+{"version":3,"file":"MATERIAL_SHADING_INFO_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/material/MATERIAL_SHADING_INFO_STRUCT.js"],"names":[],"mappings":"AAIA,wDAuB0B;6BA1BG,4BAA4B"}

package/src/shade/renderer/shader/chunk/material/MATERIAL_SHADING_INFO_STRUCT.js

@@ -16,6 +16,13 @@ export const MATERIAL_SHADING_INFO_STRUCT = WebGPUStruct.from({
     specularF0: vec3f,
     specularF90: f32,
 
+    /**
+     * The two F0s that `specularF0` blends by metalness: the dielectric's (from its IOR) and the metal's (its
+     * base color). Multiple-scattering compensation needs them apart, see `compute_multiscattering_specular`.
+     */
+    specularF0_dielectric: vec3f,
+    specularF0_metal: vec3f,
+
     emissive: vec3f,
     opacity: f32,
 }, "MaterialShadingInfo");

package/src/shade/renderer/shader/chunk/material/MULTISCATTER.md

@@ -0,0 +1,108 @@
+# Multiple-scattering specular compensation
+
+Single-scattering GGX loses the light that bounces between microfacets more than once, and it loses the most
+on rough metals: a white metal at roughness 1 reflects 0.31 of a uniform sky (1 − ln 2 at N·V = 1). Both
+paths now restore it with Turquin's compensation (2019, eq. 16), from the split-sum LUT `tSplitSum`:
+
+- **Indirect**, `compute_indirect_specular` → `compute_multiscattering_specular`, as before.
+- **Direct**, `re_direct_multiscatter`: one LUT fetch per pass that shades direct light, after its last
+  light, scales the accumulated direct specular by (single + multiple) / single scattering. The ratio
+  depends on N·V, roughness and F0 alone, so it serves every light. It is called by
+  `shade_standard_material_direct` (the deferred and the forward paths), its ReSTIR twin, and
+  `restir_resolve`, so a ReSTIR pixel fetches twice (its directional lights, then its resampled light);
+  that cost is not measured. Not by the ReSTIR target function: that is a resampling weight, and the
+  compensation is a per-pixel scale of one lobe.
+
+It uses the material's roughness, not the roughness a sphere light widens it to in `re_direct_physical`.
+
+## Why GI does not already cover it
+
+The indirect path's compensation scales the environment's light. The sun and local lights reach a pixel
+only through `re_direct_physical`, a separate additive pass. Measured in the Sponza playground with its
+shipped sun (intensity 7.2) and default IBL environment, the G-buffer read as rough gold
+(F0 1.0, 0.766, 0.336) in both the deferred pass and the indirect resolve, each pass replayed into cleared
+targets so that each pass's own contribution is measured. Means over shaded pixels, linear:
+
+| view | roughness | direct red, before → after | indirect red | direct share | luminance lost before |
+|---|---|---|---|---|---|
+| sunlit exterior | 0.8 | 0.734 → 1.193 | 0.577 | 64% | 22% (26% in red) |
+| sunlit exterior | 0.5 | 0.939 → 1.063 | 0.576 | 61% | 6% |
+| shaded atrium | 0.8 | 0.013 → 0.022 | 1.170 | 2% | 0.6% |
+
+Where the sun does not reach, GI dominates and the loss was already compensated. On sunlit rough metal,
+direct light is most of the pixel. Dielectrics barely move: Turquin's scale at F0 0.04 is at most 1.09.
+
+## Metalness
+
+Turquin's Fms = F0 makes the term quadratic in F0; metalness blends a dielectric F0 and a metal F0
+linearly. Evaluated at the blend, the term falls short by Kms · A · m(1 − m)(F0_metal − F0_dielectric)², so
+`compute_multiscattering_specular` takes both pure F0s (`specularF0_dielectric` and `specularF0_metal` on
+`MaterialShadingInfo`) and adds that back, written as a product that needs no metalness. EEVEE, Frostbite
+and three.js (#32190) evaluate the two separately and mix. For the albedo this is the same sum: exactly so
+in the indirect path, and in the direct path summed over a sky. Per light it is not, because the direct
+path applies the sum as one per-pixel ratio to the blend's lobe: under one directional light, a white
+surface at metalness 0.5 comes out −1.8% to +7.8% of the separately evaluated mix (worst at roughness 1,
+N·V 0.2, the light in the mirror direction). The blended F0 it replaced was up to 30% short there (roughness
+1, N·V 0.9, lit from beside the viewer).
+
+The indirect diffuse sits under the dielectric part only, so it keeps what the *dielectric's* specular
+leaves, not the blend's: the blend's also subtracted the metal's reflection, which the `1 − metalness` in
+`diffuse` had already removed.
+
+Measured against applying the term at the blended F0 (`deferred/white_furnace.spec.js`, white base,
+metalness 0.5): the direct specular came up to 0.157 of the sky short, the indirect resolve up to 0.33.
+Split, the direct is within 0.0028 of the blend and the indirect is the blend to one f32 ulp.
+
+## What the furnace holds
+
+`deferred/white_furnace.spec.js` lights one texel through the real passes: `shader_deferred_main` (a
+uniform sky as directional lights from GGX visible-normal sampling, or one point light through the cluster)
+and `shader_resolve_indirect_lighting`. It holds:
+
+1. a white metal's direct light is the sky less only `F_Hauber`'s dip over the half vectors that view can
+   reach, a floor derived per N·V (0.32 – 0.99 before, 0.93 – 1.00 now);
+2. the direct specular at any metalness is the blend of the pure dielectric's and the pure metal's, white
+   and gold, every channel, to the 0.0028 the Fresnel offset leaves (1.7e-5 without it);
+3. the indirect resolve is that blend to float rounding (0.67 – 0.90 of the sky at metalness 0.25 – 0.75
+   before);
+4. for a pure dielectric and a pure gold, the indirect specular exceeds the direct by no less than 0 and no
+   more than the Fresnel dip the LUT drops: this, not the white furnace, is what sees where the LUT is read;
+5. a point light is compensated as a directional light is;
+6. the ReSTIR twin shades its directional lights as the brute-force pass does;
+7. each channel is shaded by its own colour alone.
+
+Every mutant of the adversarial review is killed — the call doubled or moved ahead of the cluster loop, F0
+for the variance, the variance's sign or half of it, either path's LUT read with its coordinates swapped or at
+roughness², the guard at 1e-1, the diffuse coupled to the blend, a dielectric F0 of 0.08, the term at
+0.5, 0.9, 0.97 or 1.1 of itself, Fms = 1, the diffuse compensated too, a metal F0 of 1 in either path, one
+channel's ratio for all or none for blue, the ReSTIR twin's call removed — but one: `restir_resolve`'s own
+call. That pass needs the ray-tracing group and is not run at this tier.
+
+What is left on purpose:
+
+- **The direct lobe's Fresnel dip.** `F_Hauber(1, 1, VoH) = 1 − VoH (1 − VoH)⁴` is below 1, least at
+  VoH = 1/5 (1 − 256/3125); the compensation does not hide it. That is the 0.93 at low roughness, grazing.
+- **The LUT's edge.** Texel centres are (i + 0.5) / 64, so roughness 1 reads 0.992's albedo: 3% at
+  roughness 1, N·V 1.
+- **The resolve's horizon occlusion.** Its bent-normal specular occlusion cuts a lobe reaching under the
+  horizon even with nothing there: 0.0041 at roughness 0.51, N·V 0.10. The spec divides it out.
+
+## Cost
+
+RTX 4090, Sponza from inside the atrium at 1898 × 982 (every pixel shaded), one sun, "Shade From G-Buffer"
+with and without the call, interleaved in one capture (4-frame blocks, alternating order, 4 captures per
+view): 79.8 against 74.6 µs and 89.6 against 83.0 µs, +7%, ~0.2% of the frame. A byte-identical twin read
+0.997 – 1.009 of the shipped pass.
+
+## Measured and not changed here
+
+- **Direct diffuse is not coupled to the specular.** EON's albedo is the base colour, and the direct
+  path adds the specular on top, so a white dielectric returns 1.01 – 1.49 of a uniform sky through direct
+  light (the most at low roughness, grazing). The indirect path couples them.
+- **Direct and indirect Fresnel differ.** The LUT splits `F_Hauber` into `f0 · A + f90 · B` and drops its
+  `− VoH (1 − VoH)⁴` term, so the indirect specular is up to 0.068 of the sky above the direct for the same
+  dielectric (0.288 against 0.220 at roughness 0.26, N·V 0.26).
+- **Light the LPV injects is single-scattering.** `graph_lpv_shade.js` shades a probe ray's hit with its own
+  `BRDF_GGX` and (1 − F) diffuse, so in LPV mode a rough metal bounces its uncompensated direct light.
+- **The path tracer is single-scattering**, so for rough metals it is not the reference: it reflects what
+  the rasterizer did before this.

package/src/shade/renderer/shader/chunk/material/chunk_compute_indirect_specular.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_compute_indirect_specular.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/material/chunk_compute_indirect_specular.js"],"names":[],"mappings":"AAKA,wDAmDC;0BAxDyB,6BAA6B"}
+{"version":3,"file":"chunk_compute_indirect_specular.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/material/chunk_compute_indirect_specular.js"],"names":[],"mappings":"AAKA,wDAsEC;0BA3EyB,6BAA6B"}

package/src/shade/renderer/shader/chunk/material/chunk_compute_indirect_specular.js

@@ -13,6 +13,8 @@ fn compute_indirect_specular(
     view_direction: vec3<f32>,
     material_diffuse: vec3<f32>,
     material_specularF0: vec3<f32>,
+    material_specularF0_dielectric: vec3<f32>,
+    material_specularF0_metal: vec3<f32>,
     material_specularF90: f32,
     material_roughness: f32
 ) -> mat2x3<f32> {
@@ -28,17 +30,34 @@ fn compute_indirect_specular(
 	compute_multiscattering_specular(
         f_ab,
         material_specularF0,
+        material_specularF0_dielectric,
+        material_specularF0_metal,
         material_specularF90,
         &single_scattering,
-        &multi_scattering 
+        &multi_scattering
     );
 
 	let totalScattering = single_scattering + multi_scattering;
-	
+
 	var indirect_specular = radiance * totalScattering;
-	
+
+	// diffuse lies under the dielectric part of the surface only (material_diffuse carries its 1 - metalness),
+	// so it keeps what the dielectric's specular leaves; the blend's would subtract the metal's reflection too
+	var single_scattering_dielectric = vec3<f32>( 0.0 );
+	var multi_scattering_dielectric = vec3<f32>( 0.0 );
+
+	compute_multiscattering_specular(
+        f_ab,
+        material_specularF0_dielectric,
+        material_specularF0_dielectric,
+        material_specularF0_dielectric,
+        material_specularF90,
+        &single_scattering_dielectric,
+        &multi_scattering_dielectric
+    );
+
 	// diffuse refelections will only be a portion of whatever remain after spec
-	let conservation_factor = saturate(vec3<f32>(1.0) - totalScattering);
+	let conservation_factor = saturate(vec3<f32>(1.0) - (single_scattering_dielectric + multi_scattering_dielectric));
 	
 	let cosineWeightedIrradiance = irradiance * RECIPROCAL_PI;
 	let diffuse = material_diffuse * conservation_factor;