@woosh/meep-engine 3.60.3 → 3.60.5

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

@@ -1,159 +0,0 @@
-# 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`.
-
-The same call scales the direct diffuse by what the dielectric's specular leaves, from the same fetch; see
-[Direct diffuse under the specular](#direct-diffuse-under-the-specular).
-
-## 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.
-
-## Direct diffuse under the specular
-
-`re_direct_physical` adds the EON diffuse on top of the GGX specular, and the light the specular reflected reached
-the diffuse as well: under a uniform sky a white dielectric returned 1.01 – 1.40 of it through direct light, the
-most at low roughness and grazing view. `re_direct_multiscatter` now scales the accumulated direct diffuse by
-1 − the dielectric's specular albedo at N·V: `compute_multiscattering_specular` at `specularF0_dielectric`, on the
-`f_ab` it already fetched. That is the indirect path's factor, "albedo scaling"; UE 5.4 does the same for direct
-light (`ComputeEnergyPreservation`, by luminance: always under Substrate, in legacy shading only with the project's
-energy-conservation setting on), as do EEVEE Next (by the RGB maximum) and OpenPBR / MaterialX
-(`throughput = 1 − dirAlbedo`). Filament leaves direct diffuse uncoupled (a TODO in
-`surface_shading_model_standard.fs`); three.js since #33985 scales it per light by 1 − F(V·H).
-
-The candidates, measured through `shader_deferred_main` on a white dielectric (roughness 0.26 – 0.99, N·V 0.10 –
-0.99, the spec's grid), and their cost on "Shade From G-Buffer" in Sponza (RTX 4090, 1898 × 982, inside the
-atrium, 16 unshadowed point lights added so that a per-light term shows; with the one sun all were within noise).
-The furnace is to ±0.005, the sky sampled coarsely; under a finer one the taken coupling reads 0.932 – 1.000 and
-Kulla–Conty's at most 1.002. These were measured with the direct lobe on F_Hauber and the LUT on Schlick's fourth
-power; with both on Schlick's fifth (`brdf/FRESNEL_BRIEF_2026_10_16.md`) the LUT's dielectric albedo is the direct
-lobe's own and the taken coupling reads 1.000 – 1.001 under the spec's sky:
-
-| coupling | furnace | cost, 16 point lights |
-|---|---|---|
-| none (before) | 1.01 – 1.40 | 427.6 µs |
-| 1 − E(N·V), per pixel (taken) | 0.93 – 1.00 | +0.1 – 0.2% (copy twin 0.998 – 1.002) |
-| 1 − F(V·H), per light (three.js) | 0.97 – 1.34 | +1.3% |
-| Kulla–Conty, (1 − E(N·L))(1 − E(N·V)) / (1 − E_avg), per light | 0.93 – 1.00 | +1.5% |
-| the same without 1 / (1 − E_avg) | 0.86 – 0.98 | |
-
-Per light, the Fresnel at V·H does not hold the furnace at grazing view. Kulla–Conty's does, is reciprocal, and adds
-the light's side of the interface, at a `tSplitSum` fetch per light, an E_avg it would need from a fit or a third
-LUT channel, and `tSplitSum` in the two ReSTIR passes that reach `re_direct_physical` through the target function
-(resample, whose candidates and temporal reuse call it, and spatial reuse).
-
-The ReSTIR target function stays uncoupled: it is a resampling weight, and the coupling is a per-pixel scale.
-
-Shipped: "Shade From G-Buffer" 80.2 against 80.2 µs and 88.6 against 87.8 µs without the coupling's line (Sponza
-with its sun, the views above; copy twin 0.991 – 1.010), and the pass's mean output 3% lower. On a grid of
-dielectric spheres under a sun, the change is at the lit rims and falls with roughness.
-
-## 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, with cosine samples beside them where a
-diffuse is lit, or one point light through the cluster) and `shader_resolve_indirect_lighting`. It holds:
-
-1. a white metal's direct light is the sky, to the sampling and the LUT's error (0.32 – 0.99 before the
-   compensation, 0.93 – 1.00 while the direct lobe was F_Hauber, whose dip the LUT did not hold, 0.997 – 1.000
-   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 1.3e-5 (0.0028 under F_Hauber's offset);
-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 is the direct, to the sampling and the LUT's
-   error (up to 0.068 above it under F_Hauber): 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;
-8. a white dielectric's direct light is at most the sky (1.01 – 1.40 before, 0.932 – 1.000 with the coupling
-   under F_Hauber, 1.000 – 1.001 now);
-9. a white dielectric's direct and indirect totals agree, to the sampling and the LUT's and EON's errors;
-10. the direct diffuse keeps the share of the sky the indirect diffuse keeps, to EON's own albedo error and
-    the sampling's, 0.0015: this sees the coupling's strength more sharply than the totals, which carry EON's
-    albedo and the sampling of both lobes as well.
-
-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.
-
-So is every mutant of the diffuse coupling: removed, doubled, put on the specular, taken from the blend's albedo,
-without the dielectric's multiple scattering, at 0.9, 0.97, 1.03 or 1.1 of itself, at F0 0.08, by F0 alone, with
-F90 = 0, by the white lobe's albedo, or read at N·V = 1, with its coordinates swapped, at roughness² or at 0.8 N·V.
-The multiple-scattering and ±3% ones die only by item 10.
-
-What is left on purpose:
-
-- **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
-
-- **The direct diffuse is coupled on the view's side only.** It keeps 1 − E(N·V) whatever the light's
-  angle, so a smooth dielectric's diffuse under a grazing light is not dimmed by the Fresnel the light meets on
-  the way in: at roughness 0.26, N·V 0.9, it keeps 0.96 of the uncoupled diffuse at every N·L, where
-  Kulla–Conty's keeps 0.57 at N·L 0.1 and 1.02 at N·L 1 (within 7% of each other at roughness 0.99). Under a
-  uniform sky the two agree within 0.007 of it; the cost of Kulla–Conty's is in the section above.
-- **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/mboit/NOTES.md

@@ -1,38 +0,0 @@
-Alan Wake 2 talk references moment-based OIT, they used it due to simplicity of implementation and integration.
-
-* https://github.com/fedoriusv/V3DGameEngine/blob/1f3ef7ad93ee023dfb8f00518f40e55a46b68fe4/Engine/Data/Shaders/transparency_mboit.hlsl#L244
-* https://github.com/AlicesoftHumika/UnityOIT/blob/612c3c04263acb22980f33fa3cb2d3653ed389ff/Assets/Shader/MBOIT/MomentOIT.hlsli#L123
-
-## Numerical guards
-
-The reference HLSL divides by quantities that legitimately reach zero; the live
-4-power-moment chunk guards its inline quadratic (magnitude clamp on `c[2]`, discriminant
-floor, citardauq root recovery), and the unused 6/8-power and trigonometric variants carry
-the same treatment so they are safe to wire up later:
-
-* Deflated-polynomial leading coefficients are clamped through `magnitude_floor` /
-  `complex_magnitude_floor` at 1e-4 **of the largest lower coefficient** before entering a
-  root solver. The ratio is a range budget, not a precision limit: the solvers normalize
-  by the leading coefficient, and normalized coefficients <= ~1e4 keep every solver
-  intermediate inside f32 range even when the pivot scaling has amplified the whole
-  vector, while the escaped support point out at ~1e4 carries negligible weight in the
-  reconstruction.
-* Divided-difference denominators (support-point separations) are floored at the same
-  1e-4 — coincident support points otherwise produce 0/0 = NaN.
-* Solver-internal radicands that are non-negative under the "all real roots" contract are
-  floored (`safe_sqrt`, or `max(x, 1e-20)` where the root also divides, as in Neumark's
-  `tmp`) — rounding pushes them across zero near repeated roots.
-* `complex_square_root` snaps `|z| < 1e-20` to `(1e-20, 0)`: the unsafe kernel evaluates
-  `0 * inverseSqrt(0) = NaN` at zero, exactly where a double root lands.
-  `complex_solve_cubic_blinn` snaps its `cubed_root` the same way (triple root).
-
-The generate chunks (power and trigonometric) return the fragment's raw contribution as a
-struct; summing belongs to additive blending. The reference's quantized-storage variant
-(quantize + normalize + offset against the already-accumulated moments, an ROV) is
-deliberately not ported — it cannot be expressed through additive blending.
-
-Specs sit next to the chunks. The division singularities are pinned with exactly-singular
-dyadic moment vectors, because the WGSL emulator computes in f64 — inputs must collapse
-the leading coefficient to exactly 0.0, not merely near it. The emulator also does not
-propagate writes through pointer-to-scalar parameters, which is why the generate chunks
-return structs instead of filling scalar out-parameters.

package/src/shade/renderer/shader/chunk/spherical_harmonics/l1i/NOTES.md

@@ -1,3 +0,0 @@
-# L1 YCoCg irradiance encoding
-
-see ["Exploring Ray-Traced Future in Metro Exodus"](https://developer.download.nvidia.com/video/gputechconf/gtc/2019/presentation/s9985-exploring-ray-traced-future-in-metro-exodus.pdf)

package/src/shade/renderer/shader/chunk/spherical_harmonics/sampling/NOTES.md

@@ -1,8 +0,0 @@
-Sampling Spherical Harmonics function
-
-Useful for efficient PDF representation for things like incoming dominant light direction in path tracing
-
-References:
-
-* "Importance Sampling Spherical Harmonics" by Wojciech Jarosz et al, EUROGRAPHICS 2009
-* https://github.com/mitsuba-renderer/mitsuba/blob/10af06f365886c1b6dd8818e0a3841078a62f283/src/libcore/shvector.cpp#L394