@woosh/meep-engine 3.49.0 → 3.51.0

package/src/shade/renderer/shader/ShaderDescriptor.d.ts

@@ -1,6 +1,3 @@
-/**
- * @typedef {import("./compiler/ShaderSwitch.js").ShaderSwitch} ShaderSwitch
- */
 export class ShaderDescriptor {
     /**
      *
@@ -24,6 +21,13 @@ export class ShaderDescriptor {
      * @return {ShaderResourceSetDescriptor}
      */
     get resources(): ShaderResourceSetDescriptor;
+    /**
+     * The chunk graph this shader links, before its resources' declarations are added at link. It may
+     * still hold choices: `body.specialize(set)` is the graph {@link variant} links for `set`.
+     *
+     * @returns {CodeChunk}
+     */
+    get body(): CodeChunk;
     /**
      *
      * @return {string|GPUFeatureName[]}
@@ -69,8 +73,10 @@ export class ShaderDescriptor {
     validate_gpu_features(device: GPUDevice): boolean;
     #private;
 }
+export type CodeChunkResourceRequirement = import("./compiler/CodeChunk.js").CodeChunkResourceRequirement;
 export type ShaderSwitch = import("./compiler/ShaderSwitch.js").ShaderSwitch;
+export type ShaderResourceDescriptor = import("./resource/ShaderResourceDescriptor.js").ShaderResourceDescriptor;
 import { ShaderResourceSetDescriptor } from "./resource/ShaderResourceSetDescriptor.js";
-import { ShaderSwitchSet } from "./compiler/ShaderSwitchSet.js";
 import { CodeChunk } from "./compiler/CodeChunk.js";
+import { ShaderSwitchSet } from "./compiler/ShaderSwitchSet.js";
 //# sourceMappingURL=ShaderDescriptor.d.ts.map

package/src/shade/renderer/shader/ShaderDescriptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShaderDescriptor.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/shader/ShaderDescriptor.js"],"names":[],"mappings":"AAKA;;GAEG;AAEH;IA+NI;;;;;;OAMG;IACH;QAJ4B,KAAK,GAAtB,MAAM;QACgC,SAAS,GAA/C,2BAA2B;QACR,IAAI,EAAvB,SAAS;yBAuBnB;IApPD;;;OAGG;IACH,oBAEC;IAOD;;;OAGG;IACH,6CAEC;IAaD;;;OAGG;IACH,0CAEC;IAQD;;;OAGG;IACH,qBAQC;IAOD;;;;;OAKG;IACH,oEAMC;IASD;;;;;;;OAOG;IACH,aAHW,eAAe,GACb,gBAAgB,CA8B5B;IAED;;;OAGG;IACH,WAFY,MAAM,CAiCjB;IAED;;;OAGG;IACH,iDA6BC;IAED;;;;;OAKG;IACH,0CAHa,OAAO,CAenB;;CA+BJ;2BA/PY,OAAO,4BAA4B,EAAE,YAAY;4CAHlB,2CAA2C;gCADvD,+BAA+B;0BADrC,yBAAyB"}
+{"version":3,"file":"ShaderDescriptor.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/shader/ShaderDescriptor.js"],"names":[],"mappings":"AA2EA;IA2OI;;;;;;OAMG;IACH;QAJ4B,KAAK,GAAtB,MAAM;QACgC,SAAS,GAA/C,2BAA2B;QACR,IAAI,EAAvB,SAAS;yBAuBnB;IAhQD;;;OAGG;IACH,oBAEC;IAOD;;;OAGG;IACH,6CAEC;IAOD;;;;;OAKG;IACH,sBAEC;IAQD;;;OAGG;IACH,0CAEC;IAQD;;;OAGG;IACH,qBAQC;IAOD;;;;;OAKG;IACH,oEAMC;IASD;;;;;;;OAOG;IACH,aAHW,eAAe,GACb,gBAAgB,CA8B5B;IAED;;;OAGG;IACH,WAFY,MAAM,CAmCjB;IAED;;;OAGG;IACH,iDA6BC;IAED;;;;;OAKG;IACH,0CAHa,OAAO,CAenB;;CA+BJ;2CA7UY,OAAO,yBAAyB,EAAE,4BAA4B;2BAC9D,OAAO,4BAA4B,EAAE,YAAY;uCACjD,OAAO,wCAAwC,EAAE,wBAAwB;4CAL1C,2CAA2C;0BAF7D,yBAAyB;gCACnB,+BAA+B"}

package/src/shade/renderer/shader/ShaderDescriptor.js

@@ -4,9 +4,75 @@ import { ShaderSwitchSet } from "./compiler/ShaderSwitchSet.js";
 import { ShaderResourceSetDescriptor } from "./resource/ShaderResourceSetDescriptor.js";
 
 /**
+ * @typedef {import("./compiler/CodeChunk.js").CodeChunkResourceRequirement} CodeChunkResourceRequirement
  * @typedef {import("./compiler/ShaderSwitch.js").ShaderSwitch} ShaderSwitch
+ * @typedef {import("./resource/ShaderResourceDescriptor.js").ShaderResourceDescriptor} ShaderResourceDescriptor
  */
 
+/**
+ * A chunk's name for an error: the first thing its text declares, as a reader searching for it would type it.
+ *
+ * @param {CodeChunk} chunk
+ * @returns {string}
+ */
+function chunk_name(chunk) {
+    const match = /\b(?:fn|struct|const|alias|override|var(?:<[^>]*>)?)\s+([A-Za-z_][A-Za-z0-9_]*)/.exec(chunk.text);
+
+    return match === null ? `a chunk beginning '${chunk.text.trim().slice(0, 40)}'` : `'${match[1]}'`;
+}
+
+/**
+ * How a binding reads in WGSL terms, for an error.
+ *
+ * @param {ShaderResourceDescriptor} resource
+ * @returns {string}
+ */
+function describe_resource(resource) {
+    const member = resource.member_descriptor;
+
+    if (resource.buffer_type !== undefined) {
+        return `a ${member.type} buffer of ${resource.buffer_type.wgsl_ref}`;
+    }
+
+    if (member.sampleType !== undefined) {
+        return `a ${member.multisampled ? "multisampled " : ""}${member.viewDimension} ${member.sampleType} texture`;
+    }
+
+    if (member.format !== undefined) {
+        return `a ${member.viewDimension} ${member.format} ${member.access} storage texture`;
+    }
+
+    return `a ${member.type} sampler`;
+}
+
+/**
+ * Throw unless `resources` binds every binding the linked graph declared it reads, each as the declaration
+ * says. A shader's own resources are the one place its bindings are written down, so a chunk that reads
+ * one the shader lacks is the shader's error, named here rather than as an unresolved identifier.
+ *
+ * @param {CodeChunkResourceRequirement[]} required
+ * @param {ShaderResourceSetDescriptor} resources
+ * @param {string} label the shader's
+ */
+function check_required_resources(required, resources, label) {
+    for (let i = 0; i < required.length; i++) {
+        const { resource, chunk } = required[i];
+
+        const bound = resources.getResourceByName(resource.name);
+
+        if (bound === undefined) {
+            throw new Error(`${chunk_name(chunk)} reads '${resource.name}', which '${label}' does not bind`);
+        }
+
+        if (!resource.isSatisfiedBy(bound)) {
+            throw new Error(
+                `${chunk_name(chunk)} reads '${resource.name}' as ${describe_resource(resource)},`
+                + ` which '${label}' binds as ${describe_resource(bound)}`
+            );
+        }
+    }
+}
+
 export class ShaderDescriptor {
     /**
      * Human-readable label
@@ -40,6 +106,16 @@ export class ShaderDescriptor {
      */
     #body;
 
+    /**
+     * The chunk graph this shader links, before its resources' declarations are added at link. It may
+     * still hold choices: `body.specialize(set)` is the graph {@link variant} links for `set`.
+     *
+     * @returns {CodeChunk}
+     */
+    get body() {
+        return this.#body;
+    }
+
     /**
      *
      * @type {string|GPUFeatureName[]}
@@ -149,6 +225,8 @@ export class ShaderDescriptor {
 
         const compiled = chunk.compile();
 
+        check_required_resources(compiled.resources, this.#resources, this.#label);
+
         /**
          *
          * @type {string[]}

package/src/shade/renderer/shader/chunk/brdf/FRESNEL_BRIEF_2026_10_16.md

@@ -0,0 +1,394 @@
+# Fresnel for the direct lobe and the split-sum LUT: a brief (2026-10-16)
+
+**Status: decided and built.** Alex chose Schlick, in the form Unreal's rasterizer uses; it landed in dbdb1cdb1
+(§7). The sections before §7 are the brief as it was written, with the shading it describes as current. Every number
+here was measured; how, and where the scripts are, is in §8.
+
+Shade evaluates one material with two Fresnels. The direct lobe (`chunk_BRDF_GGX`) uses `F_Hauber`; the split-sum LUT
+`tSplitSum`, read by every indirect specular path and by `re_direct_multiscatter`, encodes `f0 · A + f90 · B` with
+Schlick's form at the fourth power. `MULTISCATTER.md` records three consequences: a dielectric's indirect specular is up
+to 0.068 of a uniform sky above its direct, a white metal's direct path reaches only 0.93, and Turquin's eq. 16
+overshoots the Heitz 2016 random walk partly because Hauber's dip compounds on every bounce.
+
+## 1. Recommendation
+
+**Use Schlick's `(1 − VoH)⁵` in the direct lobe, and regenerate the split-sum LUT with the same weight in both
+channels.** Keep the LUT, a 64² rg16float texture read with one fetch, and replace its contents. In §5 this is
+pairing E.
+
+- **All three inconsistencies close.** Direct and indirect agree to the LUT's precision: the worst gap in the f64
+  model goes from 0.071 to 0.000. A white metal's direct furnace goes from 0.929 to 1.000. At roughness 0.99, eq. 16
+  against a random walk using the same Fresnel goes from +4.7% to 0.0% for a white metal and from +5.7% to +1.0% for
+  silver.
+- **It costs one multiply per light.** Per vec3, it is 13 DXIL float operations against Hauber's 12, with no
+  transcendental. The LUT fetch and the per-pixel compensation are unchanged.
+- **Against exact Fresnel it ties with Hauber.**
+  - Dielectrics: the two are within 0.0033 of each other at every angle.
+  - Five measured metals: mean |ΔF| 0.0139 against Hauber's 0.0148. Each wins on different metals (§3).
+  - It is far more accurate than what the indirect path uses now. The shipped x⁴ LUT is up to +0.079 in albedo at
+    IOR 1.5 (up to +29%).
+- **What it changes visually** (§6):
+  - Dielectric reflections at grazing view darken toward the exact value: −12% to −34% of a sphere rim's linear
+    luminance. At roughness 0.26, N·V 0.26, the indirect albedo goes from 0.288 to 0.2225, and exact is 0.229.
+  - Metal spheres move by less than 2.3% at the rim.
+  - A back-lit white-metal or silver rim brightens by about 1%.
+- **It is the white-tint case of F82-tint**, the metal Fresnel of OpenPBR and Adobe's Standard Material. If a metal
+  edge tint is ever added to the material, it becomes a third LUT channel on top of this, not a rewrite (§4).
+
+**What would reverse it: preferring the grazing dip of high-index grey metals over silver, gold, copper and the perfect
+conductor.** For aluminium and iron at low roughness, Hauber is 0.03 to 0.06 closer in albedo; chromium, nickel and
+titanium follow the same physics. For silver, Hauber is 0.06 worse.
+
+If that look matters, Hauber's consistent form is pairing B (§5): it adds an `Ess` channel to the LUT. That closes the
+gap, but the white furnace stays at 0.93 and the walk overshoot at +4.7%.
+
+## 2. Why the two paths disagree: Hauber's dip forces a choice
+
+At `f90 = 1`, which every caller passes, `F_Hauber = f0 (1 − x⁴) + x⁵` with `x = 1 − VoH`. At `F0 = 1` it is
+`1 − VoH x⁴`, which dips to 0.918 at VoH = 0.2.
+
+Turquin's compensation needs `Ess`, the albedo with `F ≡ 1`, and Shade reads it as `A + B`. A two-channel LUT can hold
+Hauber's split or `A + B = Ess`, but not both:
+
+- **Before 933feac74**, the asset held Hauber's split exactly. That commit's own check found A within 4.9e-4 of the
+  `1 − f⁴` term and B within 4.8e-4 of the `f⁵` term. Its `A + B` was therefore the dipped white albedo. 933feac74 read
+  that shortfall (up to −8.2%) as a stale asset.
+- **933feac74 moved B to x⁴.** Now `A + B = Ess`, but `f0 · A + B` is Schlick at the fourth power, not Hauber, and the
+  indirect path has used a different Fresnel since. The furnace's 0.068 dielectric gap is that difference:
+  `(1 − f0)x⁴ − (x − f0)x⁴ = VoH x⁴`, up to 0.082.
+
+**The f64 model of the pre-933feac74 pairing gives no gap and a white furnace of 1.000, but for the wrong reason.**
+`Kms = (1 − A − B) / (A + B)` counts the dip as missing multiple scattering, so it stays positive even as roughness
+goes to 0.
+
+**Any Fresnel that is linear in F0, with `F(1, μ) ≡ 1`, removes the choice.** `f0 · A + f90 · B` is then its split,
+and `A + B` is its `Ess`. Schlick at any exponent qualifies; Hauber does not.
+
+## 3. Hauber's approximation, re-examined
+
+### Source
+
+Niklas Hauber, "Finding Alternatives to Schlick's Approximation of the Fresnel Equations", photometric.io, 2024-06-27
+(the URL in `chunk_F_Hauber`). He found it by GPU symbolic regression, with parameters R0 and 1 − cos θ:
+
+    R(θ) = R0 + (1 − cos θ − R0)(1 − cos θ)⁴
+
+**What he fitted it to:**
+
+- 4,096 points, θ uniform "from 0 to π" as written.
+- 40% at IOR 1.5, and 40% at an IOR uniform in [1.34, 1.7].
+- 20% from seven complex IORs: 0.3+3i, 0.15+4i, 0.3+3.35i, 1.4+7i, 1.84+3.73i, 2.1+4i, 2.9+3.1i.
+
+So the fit covers both dielectrics and conductors, mostly dielectrics, and most of its metals have a real part large
+enough to dip.
+
+**What he reports:** 34% lower MSE than Schlick, essentially the same shape for dielectrics, almost 50% better on his
+metals, with the warning that another dataset would differ. He also reports 5 CUDA instructions against 6. He offers a
+shape blend, `R0 + (1 − R0 − s cos θ)(1 − cos θ)⁴`, where `s = 1` is his form and `s = 0` is Schlick at the fourth
+power. The post does not discuss F0 → 1.
+
+### Shade's form
+
+`mix(f0, f90 − VoH, x⁴)` is `f0 + (f90 − VoH − f0) x⁴`. At `f90 = 1` this is Hauber's formula exactly, and it equals
+Schlick x⁵ minus `F0 · VoH x⁴`: the dip is proportional to F0, so it is deepest at F0 = 1. The `f90` is
+Shade's own generalisation; the post has none. The dip term does not scale with it, so at `f90 = 0` the form is
+negative (`−VoH x⁴`). Every caller passes 1, so that never runs.
+
+**His claim reproduces on his dataset:** 35.5% lower MSE (θ in [0, π/2]; the same with |cos θ| over [0, π]), 1.6% on
+dielectrics, 49% on metals. So the formula is read correctly.
+
+### Against exact Fresnel
+
+**Dielectrics** use the exact unpolarised Fresnel. Error over θ uniform in [0°, 90°]; "albedo" is the GGX lobe's
+directional albedo at the 25 furnace points (roughness 0.26–0.99, N·V 0.10–0.99):
+
+| IOR 1.5 (F0 0.04) | max \|ΔF\| | mean \|ΔF\| | ΔF_avg | worst Δalbedo | worst relative Δalbedo |
+|---|---|---|---|---|---|
+| Hauber | 0.033 at 85° | 0.0093 | −0.0068 | −0.0185 | −21.5% |
+| Schlick x⁵ | 0.036 at 85° | 0.0092 | −0.0061 | +0.0194 | −20.2% |
+| Schlick x⁴ (the shipped LUT) | 0.103 at 82° | 0.0214 | +0.0122 | +0.0785 | +28.7% |
+
+The worst absolute and the worst relative errors fall at different points. For Hauber and Schlick x⁵ the worst
+relative error is at mid angles, where the albedo is small and both read low (0.054 against 0.069 at roughness 0.51,
+N·V 0.51).
+
+Over IOR 1.3–2.0, the worst case for each:
+
+| | max \|ΔF\| | mean \|ΔF\| | worst \|Δalbedo\| | worst relative |
+|---|---|---|---|---|
+| Hauber | 0.067 | 0.0119 | 0.047 | −21.5% |
+| Schlick x⁵ | 0.068 | 0.0121 | 0.048 | −20.2% |
+| Schlick x⁴ | 0.142 | 0.0313 | 0.109 | +54.1% (IOR 1.3) |
+
+For a dielectric, Hauber is Schlick x⁵ minus `F0 · VoH x⁴`, at most 0.0033 at F0 0.04.
+
+**Conductors** use measured n and k: Johnson & Christy 1972 for gold, silver and copper; Johnson & Christy 1974 for
+iron; McPeak et al. 2015 for aluminium (Rakić 1995 has 13 rows in the visible, and its dip agrees to 0.012). The full
+complex Fresnel equations are integrated over 380–780 nm against D65 and the CIE 1931 2° observer (the CIE's own
+1 nm tables, taken at 5 nm), then projected to linear sRGB. That gives gold F0 (1.038, 0.729, 0.365) and aluminium
+(0.906, 0.916, 0.923). Each candidate is fed the exact curve's own F0; gold's red is left above 1.
+
+Worst channel per metal. The Δalbedo column is the worst over the 25 lobes:
+
+| metal | Hauber max \|ΔF\| | Schlick x⁵ max \|ΔF\| | Hauber Δalbedo | Schlick x⁵ Δalbedo | measured dip below F0 |
+|---|---|---|---|---|---|
+| silver | 0.078 | 0.007 | −0.065 | +0.005 | 0.3% |
+| gold | 0.062 | 0.033 | −0.051 | +0.029 | 4.5% (red) |
+| copper | 0.055 | 0.043 | −0.044 | +0.033 | 1.3% (red) |
+| aluminium | 0.049 | 0.109 | −0.026 | +0.082 | 7.1% (red) |
+| iron | 0.141 | 0.178 | +0.103 | +0.135 | 4.7% (red) |
+| mean of the 15 channels' mean \|ΔF\| | 0.0148 | 0.0139 | | | |
+
+Over all five metals, Hauber's MSE is 22% below Schlick's. That comes from aluminium (85% lower) and iron (47%). On
+gold it is 5× Schlick's, on silver 212×, on copper about equal.
+
+**As F0 → 1**, Hauber's minimum over angle falls further below F0:
+
+| F0 | 0.5 | 0.8 | 0.9 | 0.95 | 0.98 | 1.0 |
+|---|---|---|---|---|---|---|
+| Hauber, minimum | −0.5% | −3.4% | −5.4% | −6.7% | −7.6% | −8.2% (0.918 at VoH 0.20) |
+
+Schlick at either exponent never falls below F0, and is exactly 1 at F0 = 1. Only a perfect conductor has F0 = 1, and
+it has no dip. Silver, the nearest real metal (F0 0.98), dips 0.3%.
+
+### The dip belongs to n, not to F0
+
+Fitting Hauber's shape parameter `s` to each measured channel by least squares:
+
+| | silver | gold | copper | aluminium | iron |
+|---|---|---|---|---|---|
+| best `s` (R, G, B) | 0.09, 0.09, 0.05 | 0.38, 0.24, 0.58 | 0.34, 0.86, 0.88 | 1.15, 0.88, 0.64 | 2.24, 2.21, 1.96 |
+| F0 (R, G, B) | 0.99, 0.98, 0.98 | 1.04, 0.73, 0.36 | 0.93, 0.62, 0.52 | 0.91, 0.92, 0.92 | 0.53, 0.51, 0.49 |
+
+Silver and aluminium have nearly the same F0 and need opposite shapes. The dip comes from the real part of the index
+(Lazányi's correction has its slope at 2n), and the G-buffer carries only F0.
+
+**So no function of F0 alone can carry the dip.** Hauber's fit applies the average dip of its seven metals to every
+F0, including F0 = 1. It is right for aluminium-like metals and wrong for silver-like ones.
+
+## 4. The state of the art in pure functions
+
+### Fresnel
+
+DXIL is from Chrome's own Tint and DXC on the RTX 4090. Float operations per vec3 are counted, with the input loads
+excluded.
+
+| form | inputs | DXIL float ops (div, sqrt, exp/log) | five metals: worst max \|ΔF\| / mean \|ΔF\| | dielectric IOR 1.5 max \|ΔF\| | F0 = 1 |
+|---|---|---|---|---|---|
+| Schlick 1994, x⁵ (multiplies) | F0 | 13 (0) | 0.178 / 0.0139 | 0.036 | 1 |
+| Schlick x⁵ as `chunk_F_Schlick` (`pow`) | F0 | 13 (log + exp) | same | same | 1 |
+| Schlick x⁴ (the shipped LUT) | F0 | 12 (0) | 0.213 / 0.0186 | 0.103 | 1 |
+| Hauber 2024 (shipped direct) | F0 | 12 (0) | 0.141 / 0.0148 | 0.033 | 0.918 |
+| Lazányi–Schlick 2005 | n, k → F0, a, α | 25 (log + exp) | needs n | — | — |
+| F82-tint: Hoffman 2019, Adobe ASM, OpenPBR | F0 + edge tint | 40 (3 div) | 0.020 / 0.0026 (tint from data) | — | 1 at tint 1 |
+| Gulbrandsen 2014, (r, g) → n, k | F0 + edge tint | 109 (15 div, 3 sqrt) | exact up to its approximate conductor formula | — | singular, clamped to 0.99 |
+| exact dielectric (`F_dielectric`) | IOR | 28, scalar (4 div, 1 sqrt), branch | — | 0 | — |
+| exact conductor | n, k | 85 (6 div, 6 sqrt) | 0 | — | — |
+
+Notes on the sources (the literature summaries are with the scripts, §8):
+
+- **Schlick 1994** was not read first-hand: the only reachable copy is an image-only scan. Its formula is as Hoffman
+  2019 (eq. 1) and OpenPBR give it.
+
+- **Lazányi & Szirmay-Kalos 2005** (WSCG): subtract `a μ (1 − μ)^α` from Schlick. `a = 2n` comes from the slope at
+  grazing incidence; α is fitted at μ = 0.15. Their stated relative errors: Cu 1.9–4.9%, Au 5.0–5.4%, Ag 4.4–9.0%,
+  Al 2.0–17.5%. The inputs are n and k.
+- **Gulbrandsen 2014** (JCGT 3(4)): maps reflectivity and edge tint to n, k, then evaluates PBRT's approximate
+  conductor formula. Standard Surface uses it; MaterialX feeds the result to its full conductor Fresnel.
+- **Hoffman 2019 and 2023, Kutz et al. 2021/2023 (Adobe Standard Material), OpenPBR 1.1.1:**
+  `F = Schlick(μ) − b μ (1 − μ)⁶`, with `b = Schlick(1/7)(1 − tint)/(μ̄(1 − μ̄)⁶)` and μ̄ = 1/7, so that F(82°) =
+  tint · Schlick(82°). It is linear in F0, F90 and b, so a split-sum LUT needs one more channel, `∫ μ(1 − μ)⁶`.
+  The OpenPBR companion paper gives its hemispherical average as `F0 + (1 − F0)/21 − b/126`. Unreal 5.4 has
+  `F_AdobeF82` only in the Substrate path tracer, behind `SUBSTRATE_FRESNEL_F82 = 0`; its rasterizer runs Schlick.
+- **Filament and Frostbite** use Schlick with a shadowed F90. Belcour et al. 2020 needs a tabulated basis.
+  Vernooij 2024 fits the Lazányi form per metal. No F0-only metal approximation newer than Hauber's was found.
+
+### Split-sum (DFG) fits
+
+**Keep the LUT.** It is one fetch that both paths already pay, since the compensation reads it anyway. It is also an
+order of magnitude more accurate than the best published fit, which costs 26 to 89 float operations.
+
+Each fit was measured against the f64 x⁵ split of Shade's lobe (GGX, height-correlated Smith, α = r²). The points are
+a 32² grid of N·V ≥ 0.05 and roughness, which falls midway between the 64-wide LUT's texel centres, its worst place to
+interpolate. DXIL is counted as above.
+
+| fit | fitted to | DXIL float ops | white (F0 1) albedo: max \|ΔE\| / mean | F0 0.04: max \|ΔE\| |
+|---|---|---|---|---|
+| **the LUT, regenerated at x⁵** | Shade's lobe | **1 sample** | **0.0027 (0.3%) / 0.0002** | **0.0009** |
+| Karis 2014 `EnvBRDFApprox` (`DFGApprox`) | UE4's G, "adapted" | 16 (1 exp) | 0.342 (−43%) / 0.106 | 0.083 |
+| Narkowicz 2014, polynomial | uncorrelated Smith, α = (1 − gloss)⁴ | 36 (1 sqrt) | 0.221 (−28%) / 0.019 | 0.080 |
+| Narkowicz 2014, Lazarov form | same | — | 0.315 (−39%) / 0.041 | 0.080 |
+| Pesce & Iwanicki 2015 | not stated; roughness = √r, the best of three readings | 15 (1 sqrt, 1 exp) | 0.126 (−15%) / 0.028 | 0.135 |
+| UE 5.4 energy fit (`USE_ENERGY_CONSERVATION == 2`, "WIP") | height-correlated table | 26 (2 div, 3 log, 3 exp) | 0.058 (+6.5%) / 0.0064 | 0.015 |
+| MaterialX `mx_ggx_dir_albedo_analytic` (2022) | height-correlated, Schlick | 89 (2 div) | 0.084 (−8.4%) / 0.0060 | 0.025 |
+| Kulla & Conty 2017, E only | height-correlated | 38 (div, sqrt, log, exp) | 0.011 (3.5%) / 0.0022 | — |
+| Sforza & Pellacini 2022, E only | uncorrelated Smith | — | 0.226 (−28%) / 0.016 | — |
+
+Notes on the table:
+
+- **Worst cases.** Most fits are worst at grazing (N·V 0.08) and rough. The LUT's three columns below N·V 0.05 reach
+  0.019.
+- **Fdez-Agüera 2019 is not a fit.** It reads Epic's LUT, and its contribution is a multiple-scattering form, with
+  `Favg = F0 + (1 − F0)/21` for Schlick.
+- **Kulla & Conty keep tables.** Their slides favour tables over fits. The E-only fits can stand in for Turquin's
+  `Ess`, but not for the split.
+- **Turquin lists analytic fits as future work.** His conclusion names good analytic fits for all the smooth tables as
+  future work, to save texture fetches in real time. No published fit reaches the LUT's accuracy for a
+  height-correlated lobe.
+- **Engines moved from fits to LUTs in 2025.** three.js dropped Karis's fit for a height-correlated LUT (PR #32054,
+  October 2025). Godot's Forward+ renderer moved to a LUT in March 2025; its mobile renderers keep Karis's fit.
+  Filament, EEVEE and Unity HDRP use LUTs only.
+- **One Shade pass still uses a fit:** `ssr_combine_shader.js` weights by `DFGApprox`, which is 0.34 (43%) below Shade's
+  white albedo at grazing, rough. That is already reported (2026-10-03) and separate from this brief.
+
+## 5. The pairings against the three inconsistencies
+
+Measured in an f64 model of Shade's two paths under a uniform sky, at the 25 furnace points, for white, a 0.04
+dielectric and the five measured metals:
+
+- direct = `E_F(F0) · (1 + F0 Kms)`
+- indirect = `(F0 A + B)(1 + F0 Kms)`
+
+The model reproduces the real passes' furnace sweep (`white_furnace.spec.js`'s helpers, run through the emulator):
+white direct 0.9301 against 0.9302, dielectric 0.2198 against 0.2196, gap 0.0682 against 0.0684.
+
+The walk is the shared bench's port of Heitz 2016, 4M paths per point. Each Fresnel candidate and the exact Fresnel
+are applied at every bounce, and the conductors are walked per wavelength (10 nm) before projection.
+
+| pairing | worst indirect − direct | white direct, min | eq. 16 vs its own walk, r 0.99: white / silver | LUT |
+|---|---|---|---|---|
+| A. shipped: Hauber direct, LUT x⁴ | +0.071 (white), +0.068 (dielectric) | 0.929 | +4.7% / +5.7% | as is |
+| B. Hauber direct, LUT (1 − x⁴, x⁵) + an `Ess` channel | 0.000 | 0.929 | +4.7% / +5.7% | 3 channels |
+| C. Hauber direct, LUT (1 − x⁴, x⁵), `Kms` from A + B (pre-933feac74) | 0.000 | 1.000, by booking the dip as multiple scattering | — | regenerate |
+| D. Schlick x⁴ in both | 0.000 | 1.000 | 0.0% / +0.9% | as is |
+| **E. Schlick x⁵ in both** | **0.000** | **1.000** | **0.0% / +1.0%** | **regenerate** |
+
+**D needs no new asset, but it moves the direct path to the least accurate form.** For a dielectric, it puts the
++29% albedo error of today's indirect path into the direct one, and it is worse on every metal (§3).
+
+**E is the shipped LUT's two channels, regenerated.**
+
+**Against the walk with exact Fresnel**, the worst over N·V and channels, at roughness 0.26:
+
+| | white | silver | gold | copper | aluminium | iron | dielectric IOR 1.5 |
+|---|---|---|---|---|---|---|---|
+| Hauber (A's, B's direct) | −7.1% | −6.9% | −8.0% | −5.4% | +3.4% | +17.3% | −22% |
+| Schlick x⁵ (E) | 0.0% | +0.5% | −4.1% | +4.3% | +10.7% | +23.4% | −21% |
+| Schlick x⁴ (A's indirect, D) | 0.0% | +0.6% | +6.4% | +9.2% | +11.5% | +28.9% | +25% |
+
+The dielectric's relative errors are on small values. At N·V 0.51 they are 0.0687 (x⁵) and 0.0962 (x⁴) against an
+exact 0.0869. At N·V 0.26 they are 0.2225 and 0.2879 against 0.2294.
+
+**At roughness 0.99, the Fresnel no longer decides; Turquin's `Fms = F0` does.** Against the exact walk, eq. 16 is
++21.7% for iron, +17.2% for copper and +23.8% in gold's blue under every Fresnel. That is the compensation's own
+saturation error, which `MULTISCATTER.md` already ledgers.
+
+**Hauber's dip compounding is the part E removes.** Against walks with their own Fresnel at roughness 0.99, eq. 16's
+mean overshoot is:
+
+| | white | silver | aluminium | gold | copper | iron |
+|---|---|---|---|---|---|---|
+| Hauber | +0.026 | +0.029 | +0.036 | +0.024 | +0.031 | +0.025 |
+| Schlick x⁵ | 0.000 | +0.004 | +0.016 | +0.010 | +0.020 | +0.021 |
+
+Against the exact walk the totals move the other way, by 0.003 to 0.008 for the metals: Hauber's dip had been
+offsetting part of `Fms = F0`'s overshoot.
+
+## 6. The visual change
+
+Rendered on the RTX 4090 with the multiscatter bench's sphere sweep: seven roughnesses (0.1–1.0) by seven materials
+(gold, copper, aluminium, iron and silver at their table F0, a white metal at F0 1, and a black dielectric), IBL, TAA,
+EV −1.
+
+Two lightings:
+
+- the bench's sun, which comes from the camera's side, so VoH is about 0.9 on every sphere;
+- the same sun from behind the spheres, so their rims see VoH ≈ 0.27, where Hauber's dip lives.
+
+No engine file was edited. The "after" page's prelude rewrites `F_Hauber`'s body to Schlick x⁵ in the one module that
+declares it, and replaces `split_sum.bin`'s texels as they are fetched. The replacement is the shipped texels plus the
+f64 change of weight, `∫ VoH x⁴`, so only the Fresnel differs, not the integration. A repeat of the shipped arm
+differed by at most 0.27% (front) and 0.09% (back).
+
+Change in mean linear luminance, after against before, over the outer rim (0.75–0.92 of the radius):
+
+| | 0.1 | 0.25 | 0.4 | 0.55 | 0.7 | 0.85 | 1.0 |
+|---|---|---|---|---|---|---|---|
+| black dielectric, front | −34.1% | −32.8% | −27.6% | −21.4% | −18.4% | −14.9% | −12.3% |
+| black dielectric, back | −33.7% | −17.3% | −7.5% | −11.6% | −17.2% | −15.6% | −13.4% |
+| iron, front | −2.3% | −2.2% | −1.6% | −0.9% | −0.6% | −0.4% | −0.3% |
+| copper, front | −1.5% | −1.4% | −1.0% | −0.5% | −0.3% | −0.2% | −0.1% |
+| white metal, back | 0.0% | +0.9% | +1.3% | +0.8% | +0.2% | 0.0% | 0.0% |
+| silver, back | −0.1% | +0.6% | +1.0% | +0.5% | +0.1% | 0.0% | 0.0% |
+
+Over whole spheres, metals move by at most 0.4% and the black dielectric by 2–8%.
+
+**Where the eye sees it is the dielectric's Fresnel rim under the sky.** It loses the x⁴ LUT's excess and lands near
+exact: 0.2225 against 0.2294 at roughness 0.26, N·V 0.26, where it was 0.288.
+
+Swapping only the direct Fresnel to x⁴ (pairing D) brightens the back-lit black dielectric's rim by up to 28%. The
+images are with the scripts (§8).
+
+## 7. As built (dbdb1cdb1)
+
+**The form is Unreal 5.4's rasterizer.** `F_Schlick(F0, F90, VoH)` in `BRDF.ush`, which Substrate's `Substrate_F_GGX`
+calls, computes `Fc = Pow5(1 − VoH)` by multiplies, then returns `F90 Fc + (1 − Fc) F0`. Its `EnvBRDF(F0, F90)` reads
+a LUT integrated with the same weight. `chunk_F_Schlick` now has that form; its `pow(x, 5.0)` had compiled to a log
+and an exp.
+
+**Every `F_Hauber` caller moved to it,** and `chunk_F_Hauber` is deleted:
+
+- `chunk_BRDF_GGX`;
+- `graph_lpv_shade.js`;
+- the path tracer: `chunk_render_trace_path.js` ×2 and `chunk_sample_material_data.js`;
+- the forward fragment;
+- the view Fresnel of `shader_avboit_splat.js` and `shader_oit_generate_moments.js`.
+
+**`chunk_integrate_brdf` weights `(1 − x⁵, x⁵)`, and `split_sum.bin` was regenerated once on the RTX 4090.** It
+followed the 16cca4c69 procedure: 2^18 samples in 1024-sample blocks through rg32float, f16 encoded on the CPU, then
+the chunk put back at 1024 samples. Checked against the old asset:
+
+- its A + B moved by at most one f16 ulp anywhere;
+- against the old asset plus the f64 change of weight, it is within 5.8e-4 everywhere.
+
+**Pinned red then green:**
+
+- `chunk_BRDF_GGX.spec.js` (new): a perfect conductor's lobe is D V alone, and the lobe's Fresnel is Schlick's fifth
+  power.
+- `split_sum_asset.spec.js`: weight x⁵, and the generator itself held to the same integral.
+- `white_furnace.spec.js`: the dip's slack goes from four checks.
+  - A white metal's direct light reads 0.997 – 1.000 of the sky.
+  - A pure material's direct and indirect specular agree to 0.0031.
+  - A white dielectric's totals agree to 0.0010.
+  - The metalness blend holds to 1.3e-5.
+- `chunk_F_Schlick.spec.js` (new): pins the form.
+
+**The diffuse coupling of 835cba76b now balances exactly.** It keeps 1 − the LUT's dielectric albedo, which is now the
+direct lobe's own, so a white dielectric's direct light reads 1.000 – 1.001 of the sky (it was 0.932 – 1.000).
+
+**Device checks:**
+
+- Every shader that links a changed chunk compiles on the 4090: 19 unique modules, found through the reverse import
+  closure. The lightmap bake pair fails on a struct member already missing on master (a224bc59c1).
+- The sphere sweep, rendered from a detached master worktree and from the change, moves as §6 predicted, to 0.1
+  point.
+
+**Not part of this:** `ssr_combine_shader.js` weights by Karis's fit, not the LUT (§4).
+
+## 8. Method and reproduction
+
+The scripts, data and renders are in the side-session notes folder
+`local_9644ea11-c179-40dd-a485-620475f78a45/fresnel-brief/`, outside the repo:
+
+- `dfg_lib.mjs`: the lobe integrated over microfacet normals, with GGX's CDF as the variable, so that narrow lobes
+  resolve. It is held to `split_sum_asset.spec.js`'s light-direction quadrature and to the shipped texels to about
+  1e-4.
+- `fresnel_lib.mjs`: exact dielectric and complex conductor Fresnel, and the spectral projection.
+- `optical_data.json`: n and k, CIE 1931 and D65, each with its source URL.
+- `study_dielectric.mjs`, `study_metal.mjs`, `hauber_claim.mjs`, `study_dfg.mjs`, `study_dfg_e.mjs`,
+  `pesce_mapping.mjs`, `combos_study.mjs` and `model_check.mjs`, each with its `.txt` output.
+- `dfg_fits.mjs`: every published fit, with its constants.
+- `lit_fresnel.md` and `lit_dfg.md`: the literature, read from the primary sources, with URLs and sections.
+- `walk_candidates.mjs`: the shared bench's Heitz port, with every Fresnel. Run with `analyse_walk.mjs`.
+- `alu/`: the dump page and counter.
+- `render_drive.mjs`, the sphere page and `sphere_diff.py`, with the renders.

package/src/shade/renderer/shader/chunk/brdf/chunk_BRDF_GGX.d.ts

@@ -1,6 +1,9 @@
 /**
  * Specular GGX
- * GGX Distribution, Fresnel, GGX_SmithCorrelated Visibility
+ * GGX Distribution, Schlick's Fresnel, GGX_SmithCorrelated Visibility
+ *
+ *   - the Fresnel is `F_Schlick`, the weight the split-sum LUT integrates (`chunk_integrate_brdf`), so this lobe
+ *     and every indirect path reflect one Fresnel for one material
  *
  *   - alpha = roughness_linear * roughness_linear
  */

package/src/shade/renderer/shader/chunk/brdf/chunk_BRDF_GGX.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_BRDF_GGX.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/brdf/chunk_BRDF_GGX.js"],"names":[],"mappings":"AAMA;;;;;GAKG;AACH,uCAmCC;0BA/CyB,6BAA6B"}
+{"version":3,"file":"chunk_BRDF_GGX.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/brdf/chunk_BRDF_GGX.js"],"names":[],"mappings":"AAMA;;;;;;;;GAQG;AACH,uCAmCC;0BAlDyB,6BAA6B"}

package/src/shade/renderer/shader/chunk/brdf/chunk_BRDF_GGX.js

@@ -2,11 +2,14 @@ import { CodeChunk } from "../../compiler/CodeChunk.js";
 import { chunk_pow2 } from "../math/chunk_pow2.js";
 import { chunk_D_GGX } from "./chunk_D_GGX.js";
 import { chunk_V_GGX_SmithCorrelated } from "./chunk_V_GGX_SmithCorrelated.js";
-import { chunk_F_Hauber } from "./fresnel/chunk_F_Hauber.js";
+import { chunk_F_Schlick } from "./fresnel/chunk_F_Schlick.js";
 
 /**
  * Specular GGX
- * GGX Distribution, Fresnel, GGX_SmithCorrelated Visibility
+ * GGX Distribution, Schlick's Fresnel, GGX_SmithCorrelated Visibility
+ *
+ *   - the Fresnel is `F_Schlick`, the weight the split-sum LUT integrates (`chunk_integrate_brdf`), so this lobe
+ *     and every indirect path reflect one Fresnel for one material
  *
  *   - alpha = roughness_linear * roughness_linear
  */
@@ -28,7 +31,7 @@ fn BRDF_GGX(
 ) -> vec3<f32> {
 
     // Fresnel
-	let F = F_Hauber( f0, f90, VoH );
+	let F = F_Schlick( f0, f90, VoH );
 
     // Masking (geometric term)
 	let V = V_GGX_SmithCorrelated( alpha, NoL, NoV );
@@ -41,7 +44,7 @@ fn BRDF_GGX(
     `,
     [
         chunk_pow2,
-        chunk_F_Hauber,
+        chunk_F_Schlick,
         chunk_D_GGX,
         chunk_V_GGX_SmithCorrelated
     ]

package/src/shade/renderer/shader/chunk/brdf/dfg/chunk_integrate_brdf.d.ts

@@ -1,7 +1,10 @@
 /**
+ * The split-sum terms of Shade's specular lobe: A = ∫ D V (1 - Fc) <n,l>, B = ∫ D V Fc <n,l>, with Fc = (1 - VoH)^5,
+ * the Fresnel weight of `F_Schlick` that the direct lobe applies.
+ *
  * The engine ships this integrated once, as `assets/textures/split_sum.bin` (`generate_dfg_texture`, run on a
  * device), so changing what it integrates means regenerating that; `split_sum_asset.spec.js` holds the asset
- * to the integral.
+ * and this chunk to the integral.
  * @see https://github.com/qiutang98/flower/blob/d67c6f1ae36bad18f6da15a70e2fe8d2949bf401/install/shader/brdf_lut.glsl
  * @see https://www.shadertoy.com/view/fdd3zf
  * @type {CodeChunk}

package/src/shade/renderer/shader/chunk/brdf/dfg/chunk_integrate_brdf.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_integrate_brdf.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/brdf/dfg/chunk_integrate_brdf.js"],"names":[],"mappings":"AAKA;;;;;;;GAOG;AACH,mCAFU,SAAS,CA4DlB;0BAvEyB,gCAAgC"}
+{"version":3,"file":"chunk_integrate_brdf.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/brdf/dfg/chunk_integrate_brdf.js"],"names":[],"mappings":"AAKA;;;;;;;;;;GAUG;AACH,mCAFU,SAAS,CAyDlB;0BAvEyB,gCAAgC"}

package/src/shade/renderer/shader/chunk/brdf/dfg/chunk_integrate_brdf.js

@@ -4,9 +4,12 @@ import { chunk_importance_sample_GGX } from "../chunk_importance_sample_GGX.js";
 import { chunk_V_GGX_SmithCorrelated } from "../chunk_V_GGX_SmithCorrelated.js";
 
 /**
+ * The split-sum terms of Shade's specular lobe: A = ∫ D V (1 - Fc) <n,l>, B = ∫ D V Fc <n,l>, with Fc = (1 - VoH)^5,
+ * the Fresnel weight of `F_Schlick` that the direct lobe applies.
+ *
  * The engine ships this integrated once, as `assets/textures/split_sum.bin` (`generate_dfg_texture`, run on a
  * device), so changing what it integrates means regenerating that; `split_sum_asset.spec.js` holds the asset
- * to the integral.
+ * and this chunk to the integral.
  * @see https://github.com/qiutang98/flower/blob/d67c6f1ae36bad18f6da15a70e2fe8d2949bf401/install/shader/brdf_lut.glsl
  * @see https://www.shadertoy.com/view/fdd3zf
  * @type {CodeChunk}
@@ -44,18 +47,15 @@ fn integrate_brdf( NoV: f32, roughness: f32 ) -> vec2<f32> {
             let G = V_GGX_SmithCorrelated(alpha, NoL, NoV);
             let Gv = 4.0 * NoL * G * VoH / NoH;
             
-            // Fresnel term, Shlick's approximation with Hauber's scale factor.
-            // we use F_Hauber in direct lighting, which is
+            // Schlick's (1 - VoH)^5, the weight F_Schlick applies in the direct lobe, so f0 · A + f90 · B is the
+            // albedo with the direct lobe's own Fresnel and A + B the albedo at F = 1
             let fx = 1.0 - VoH;
             let fx2 = fx * fx;
-            let fx4 = fx2 * fx2;
+            let fx5 = fx2 * fx2 * fx;
 
-            // Both terms use Hauber's (1-VoH)^4 falloff to match the runtime F_Hauber Fresnel used
-            // in direct lighting — the bias term previously used Schlick's (1-VoH)^5, making the
-            // f90/edge weight of indirect specular inconsistent with direct.
             lut += vec2(
-                (1.0 - fx4) * Gv,
-                fx4 * Gv
+                (1.0 - fx5) * Gv,
+                fx5 * Gv
             );
             
         }