@woosh/meep-engine 3.60.4 → 3.60.6

package/src/shade/renderer/shader/chunk/color/tonemap/HDR_TONE_MAPPING_FORMS_BRIEF_2026_10_16.md

@@ -1,322 +0,0 @@
-# HDR forms of ACES, AgX and PBR Neutral: a brief (2026-10-16)
-
-**Status: decided and built.** Alex took all three recommendations (§6): the ACES and AgX chunks are removed, and
-`ShadeToneMappingMode.PBR_NEUTRAL` runs `tonemap_khronos_pbr` with the peak form. The prototypes this brief measured
-are gone from the playground `src/shade/playground/tonemap_sdr/`, which now compares GT7 and PBR Neutral.
-
-**The paper white is 203 cd/m² since `5549db81f` (2026-10-17),** BT.2408's graphics white, not GT7's 250. Every
-measurement below was taken at 250, so peak ×4 was a 1000 cd/m² display; at 203 it is 812 cd/m², and a 1000 cd/m²
-display is ×4.93.
-
-## 1. Recommendation
-
-The question: does each operator have one form, parameterised by the display's peak, that serves an SDR peak and an HDR
-peak with the same mid-tones? That is what `ShadeToneMappingMode` asks of a mode since `6ea10df28`: one mode on every
-output, and SDR and HDR must not look different. GT7 is the yardstick.
-
-| operator | a form that fits? | recommendation |
-|---|---|---|
-| ACES | **No.** ACES 2.0 is one family parameterised by peak, but it lifts mid-grey by 14% of its SDR level per stop of peak, on purpose. | **Remove** |
-| AgX | **No.** Both HDR forms (Chow's, Godot's) keep mid-grey and bend everything above it with the peak. | **Remove** |
-| Khronos PBR Neutral | **Yes**, with the peak in place of the specification's 1. Below the compression start it is exact at every peak. | **Add** as `ShadeToneMappingMode.PBR_NEUTRAL` |
-
-GT7 stays the default.
-
-On the device, in the playground's four scenes at a 1000 cd/m² peak, Neutral with a peak and GT7 leave every mid-tone
-pixel as their SDR forms draw it, to within 1 code. Godot's AgX moves 10.5–87.6% of them by 2 codes or more (§4).
-
-Neutral earns a mode for a reason beyond fitting. The SDR brief named it the fallback if GT7's SDR clip reads as harsh,
-"at the price of SDR and HDR looking different". With a peak, that price is gone:
-
-- its forms agree exactly over a wider range than GT7's, greys to +2.0 EV against +1.5;
-- saturated colours just above its start differ more, a mean of 0.72 codes up to +1 EV against GT7's 0.24.
-
-**What would reverse each:**
-
-- **ACES:** a need to match an ACES 2.0 pipeline, such as grading or film interchange, accepted together with SDR and HDR
-  looking different. It would be a new implementation, not this chunk.
-- **AgX:** a published AgX HDR form that holds tones fixed to about +1.5 EV over mid-grey, measured with the same
-  script. Pestaluky lists a higher crossover as future work.
-- **Neutral:**
-  - Khronos publishing its own HDR form. The HDR pass would then follow it.
-  - Alex's session on an HDR display finding the long shoulder (0.76 to the peak) flat or too colourful.
-  - Alex preferring one operator with no alternative. Then Neutral goes too (F3).
-
-## 2. What the sources say
-
-### ACES 2.0, Academy Output Transforms
-
-Sources read: `aces-aswf/aces-core` (`Lib.Academy.Tonescale.ctl`, `Lib.Academy.OutputTransform.ctl`, CHANGELOG) and
-`aces-aswf/aces-output`, v2.0 of 2025-04-04; the ACES 2 documentation; GT7 talk slides 116–120.
-
-- **One family for every peak.** The CHANGELOG describes the v2 tonescale's "adaptability to produce output for any peak
-  luminance between 100-10000 nits". The output transforms are one CTL each, differing only in `peakLuminance`, the
-  limiting primaries and the encoding.
-- **One of them is Shade's HDR canvas:** `Output.Academy.P3-D65_1000nit_in_P3-D65_sRGB-Piecewise`, "Extended DisplayP3
-  (1000 nit)". It is P3 limited and sRGB-piecewise encoded, with 1.0 at 100 cd/m², clamped at peak/100.
-- **Mid-grey moves with the peak by design.** `init_TSParams` in `Lib.Academy.Tonescale.ctl` sets the grey target as
-  `c_t = c_d / n_r * (1 + w_i * w_g)`, where `w_i = log2(peak / 100)` and `w_g = 0.14`. The comment on `w_g` reads
-  "change in grey between different peak luminance". The GT7 talk says the same on slide 117: mid-grey lands at 10 to
-  15 cd/m² "depending on the ODT".
-- **The gamut stage is per peak.** `init_ODTParams` builds three 360-entry hue tables by search: the reach gamut's M, the
-  limiting gamut's cusps and the upper hull gamma. They depend on the peak. Shade's peak is a runtime value, so every
-  change of peak means a rebuild.
-- **GT7 talk, slide 120:** ACES 2.0 support for variable HDR peaks is "Additional Work Needed".
-- **What Shade has is not ACES 2.0.** `chunk_tonemap_aces` is Hill's fit of the ACES 1.0 sRGB RRT+ODT, SDR only. An HDR
-  ACES would be a new implementation of the JMh model and its tables, not an extension of the chunk.
-
-### AgX
-
-Sources read:
-
-- Eary Chow's `AgX` configuration and README;
-- his generator, `AgX_LUT_Gen`, in particular `AgXHLG.py` and `AgXBaseRec2020.py`;
-- Blender main's `release/datafiles/colormanagement/config.ocio`;
-- Pestaluky's post, cited on GT7 slide 113;
-- Godot master: `tonemap.glsl`, `environment_storage.cpp` and `Environment.xml`.
-
-- **Chow's HDR view is one baked LUT.** "AgX - HDR 1000 nits" is `AgX_Rec2100-HLG_p3_lim.cube`, for a 1000 cd/m² HLG
-  display with reference white at 100. His README says mid-grey is "set to 18% of 100 nits".
-- **Blender main ships the same.** There are two AgX views on Rec.2100 displays, "AgX - SDR" and "AgX - HDR 1000 nits".
-  On sRGB, Display P3 and Rec.1886 displays, AgX is SDR only.
-- **The generator has one parameter, the ratio of HDR peak to SDR white.** A comment expects it to become tunable at
-  runtime. The HDR script is the SDR Rec.2020 script plus three steps:
-  - the shoulder exponent multiplied by ratio^log10(2);
-  - a log-space sigmoid that pulls mid-grey down to 18% of the reference white;
-  - a 50% "HDR purity" mix of hue and saturation.
-
-  At ratio 1 the three steps change nothing: 0.0 codes over the sweep in §3, against the same script with them off.
-- **Pestaluky's curve, which Godot ships as its AgX.** It is parameterised by the output's maximum. The post says values
-  below the crossover do not depend on the output's range, and the crossover is mid-grey, 0.18. Above it, the shoulder
-  is fitted to the peak.
-  - Godot puts the curve between AgX's inset and outset matrices, with an AgX white of 16.29 times the peak. Its
-    matrices are `chunk_tonemap_agx`'s composed with the Rec.709/Rec.2020 conversions, to 1e-6.
-  - This landed in Godot on 2025-12-03, "Add `agx_white`, `agx_contrast` and HDR support to the AgX tonemapper". It is
-    in 4.7-stable and not in 4.6-stable.
-- **GT7 talk, slide 120:** variable HDR peaks are "No" for AgX, as of June 2025. Slide 113 calls the HDR extension work
-  in progress.
-- **Neither is Shade's AgX.** `chunk_tonemap_agx` is the Filament and three.js port, with a log2 encoding, a polynomial
-  sigmoid and a 2.2 decode. It puts 0.18 at 0.2145. Godot's form at peak 1 puts it at 0.18, and differs from the chunk by a mean of
-  20.6 codes over −2 to +1 EV, 35.7 at worst. Adopting either HDR form changes Shade's SDR AgX as well.
-
-### Khronos PBR Neutral
-
-Sources read: the Khronos repository (README, `pbrNeutral.glsl`, commit history to 2026-10-06) and Lalish's
-model-viewer write-up.
-
-- **No HDR form exists.** The README says the operator supports only sRGB output, and that expanding it is a goal for
-  the future. Since June 2024 the repository has changed only in licensing and contribution files.
-- **Lalish names where to adapt it.** The single parameter, the 0.8 compression start, is "likely the most natural place
-  to adjust the curve to HDR output". He also writes that the choice of operator should depend on the output format.
-- **GT7 talk, slide 120:** variable HDR peaks are "No" for Neutral.
-- **So the HDR form is ours.** The prototype puts the peak P where the specification has 1, and keeps the start:
-  - p_n = P − (P − K_s)² / (p + P − 2K_s);
-  - the desaturation term is unchanged.
-
-  At P = 1 it is the specification: 0.0 codes over the sweep. Below K_s it is 1:1 at every P.
-- **The alternative is to move the start with the peak**, 0.8·P, a literal reading of Lalish's pointer. Below 0.76 it is
-  identical, and above it it strays further from SDR. Up to +1 EV the worst case is 35.0 codes against 26.6, and the
-  mean 0.83 against 0.72. So the prototype keeps the start.
-
-## 3. Measured on the CPU
-
-**References, not re-derivations:**
-
-- **ACES 2.0:** OpenColorIO 2.6.0's `FIXED_FUNCTION_ACES_OUTPUT_TRANSFORM_20`, the Academy transform, with P3-D65
-  limiting primaries.
-  - Against OCIO's builtin `HDR-1000nit-P3-D65_2.0`, it agrees to 5e-8 in XYZ.
-  - Against a port of the CTL tonescale, greys agree to five digits.
-  - Input is Rec.709 → ACEScg (Bradford) → ACES2065-1.
-  - The peak at headroom H is 100·H cd/m², since ACES puts SDR white at 100.
-- **AgX, Chow's:** his `AgX_Rec2100` run as written, with `HDR_max_nits` = 100·H.
-- **AgX, Godot's:** a port of `tonemap.glsl` with the parameters `environment_storage.cpp` computes.
-- **GT7:** a port of the engine's `tonemap_gt7` at a peak of 250·H. Against Polyphony's compiled sample code it agrees
-  to 0.36 codes in the mid-tones and 14.7 in saturated highlights, which is the ICtCp blend the SDR brief reports.
-
-**Inputs:**
-
-- Eleven hues:
-  - white, fire, blue, green, magenta, red, mint and a brake light;
-  - the product shot's canary 231,218,63, red 203,63,63 and mint 149,218,188.
-- Each is scaled to luminance 0.18·2^EV, from −6 to +6 EV in quarter stops.
-
-**Outputs** are taken as an HDR canvas shows them below SDR white: linear Display P3, clipped to 1, then 8-bit
-sRGB-encoded. Each operator at peak ×H is compared with itself at peak ×1.
-
-**At peak ×4,** a 1000 cd/m² display under the 250 cd/m² paper white:
-
-| | mid-grey, SDR → HDR | greys equal up to | every hue equal up to | worst, at or below grey | mean, up to +1 EV |
-|---|---|---|---|---|---|
-| GT7 (engine) | 0.179 → 0.179 | +1.5 EV | −0.5 EV | 3.9 (blue) | 0.24 |
-| ACES 2.0 | 0.100 → 0.128 (+0.35 EV) | −4.0 EV | −5.5 EV | 24.5 (blue) | 6.98 |
-| AgX, Godot's | 0.180 → 0.180 | +0.25 EV | −1.5 EV | 20.9 (blue) | 2.25 |
-| AgX, Chow's | 0.180 → 0.180 | 0.0 EV | −1.75 EV | 36.1 (blue) | 3.64 |
-| **Neutral with a peak** | 0.140 → 0.140 | **+2.0 EV** | **0.0 EV** | **0.0** | 0.72 |
-
-"Equal" means within half a code. EV is the input's luminance over 0.18.
-
-- **GT7's own worst case** is a saturated blue at mid-grey luminance. Its blue channel is past the per-channel linear
-  section, 0.444, while its luminance is at grey.
-- **Neutral's 1:1 region** runs on the largest channel too, but up to 0.76, so the same blue does not reach it.
-- **Neutral's higher mean up to +1 EV** comes from saturated colours just above the start. Its worst case is the brake
-  light at +0.75 EV, 26.6 codes, where GT7's worst over the same range is 7.6. Neutral's SDR shoulder compresses the
-  largest channel hard, and at ×4 it barely compresses.
-
-**At ×2 and ×10 the picture is the same:**
-
-| | grey shift ×2 | ×10 | mean up to +1 EV, ×2 | ×10 |
-|---|---|---|---|---|
-| GT7 | 0 | 0 | 0.24 | 0.24 |
-| ACES 2.0 | +0.19 EV | +0.54 EV | 3.47 | 10.89 |
-| AgX, Godot's | 0 | 0 | 1.52 | 2.67 |
-| AgX, Chow's | 0 | 0 | 2.12 | 4.88 |
-| Neutral with a peak | 0 | 0 | 0.59 | 0.78 |
-
-**Grey ramps,** display-linear in units of SDR white, as SDR / peak ×4:
-
-| EV | GT7 | ACES 2.0 | AgX, Godot's | AgX, Chow's | Neutral with a peak |
-|---|---|---|---|---|---|
-| −2 | 0.031 / 0.031 | 0.013 / 0.016 | 0.037 / 0.037 | 0.037 / 0.037 | 0.013 / 0.013 |
-| −1 | 0.078 / 0.078 | 0.040 / 0.048 | 0.085 / 0.085 | 0.084 / 0.084 | 0.050 / 0.050 |
-| 0 | 0.179 / 0.179 | 0.100 / 0.128 | 0.180 / 0.180 | 0.180 / 0.180 | 0.140 / 0.140 |
-| +1 | 0.360 / 0.360 | 0.209 / 0.296 | 0.331 / 0.356 | 0.326 / 0.374 | 0.320 / 0.320 |
-| +2 | 0.674 / 0.720 | 0.370 / 0.612 | 0.511 / 0.664 | 0.484 / 0.759 | 0.680 / 0.680 |
-| +3 | 0.992 / 1.440 | 0.556 / 1.128 | 0.684 / 1.146 | 0.632 / 1.377 | 0.935 / 1.294 |
-
-- **GT7 and Neutral** leave greys alone until their SDR shoulders, GT7 from +1.5 EV and Neutral from +2.
-- **ACES** moves every grey.
-- **AgX** keeps grey itself and lifts everything above it. At +1 EV, Godot's form is 0.11 EV brighter at ×4 and Chow's
-  0.20. At +2 EV they are 0.38 and 0.65 EV brighter.
-
-**Pinning ACES's grey does not rescue it.** With `w_g` = 0 in the CTL tonescale, greys at 100 and 400 cd/m² still
-differ:
-
-| EV | −1 | 0 | +1 | +2 |
-|---|---|---|---|---|
-| codes | 2.8 | 0.0 | 8.0 | 25.4 |
-
-The rest of the curve still depends on the peak, and the result would no longer be the Academy's transform.
-
-## 4. Measured on the device
-
-The playground draws operators 5–7 at a peak, clipped to SDR white (`CompareLayout.Split` shows it beside the SDR form).
-A one-off driver outside the repo ran it once.
-
-ACES 2.0 and Chow's AgX were not ported to WGSL. ACES needs the JMh model and the per-peak hue tables, and Chow's form
-is a LUT generated per ratio. §3 measured both through their reference implementations, so a port would re-measure
-the same functions with a port's error added.
-
-- Headless Chrome on the RTX 4090.
-- The page's per-scene exposure, with bloom, TAA and SSAO off and the projection frozen.
-- Each scene and operator grabbed at peak ×1, ×1 again for the noise floor, then ×4 and ×10.
-- Compared per pixel in Display P3 codes, as the largest channel difference. Two grabs at ×1 differ by exactly 0 in
-  every scene, so the floor is zero.
-
-**Mid-tone pixels at ×4,** those whose SDR largest channel is at most 188 (0.5 linear). Each cell gives the mean
-difference in codes, the share of those pixels that differ by 2 codes or more, and the largest difference.
-
-| scene | mid-tone share of the frame | GT7 | AgX, Godot's | Neutral with a peak |
-|---|---|---|---|---|
-| fire and emitters | 66–70% | 0 · 0% · 0 | 0.91 · 10.5% · 18 | 0 · 0% · 0 |
-| sunlit exterior | 39–40% | 0.008 · 0% · 1 | 5.22 · 87.6% · 23 | 0 · 0% · 0 |
-| dim interior | 83–87% | 0 · 0% · 1 | 1.43 · 20.5% · 23 | 0 · 0% · 0 |
-| product shot | 5–9% | 0.006 · 0% · 1 | 7.15 · 59.0% · 24 | 0 · 0% · 0 |
-
-The mid-tone share varies with the operator, because each one's own SDR frame decides which pixels count.
-
-At ×10, GT7 and Neutral are unchanged. AgX's means grow to 1.10, 6.25, 1.71 and 8.70.
-
-Between 0.5 and SDR white every form differs by design, because the HDR form has headroom there. Over all pixels below
-SDR white, the means at ×4 are 0.2–9.2 codes for GT7, 0.8–14.2 for Neutral and 3.4–34.3 for AgX.
-
-## 5. What each recommendation means for the code
-
-**Removing ACES (F1):**
-
-- `chunk_tonemap_aces.js` (`chunk_tonemap_aces`) goes.
-- The npm package exports `./src/*`, so the deep import breaks for any downstream user. In this repo only the playground
-  imports it, as grid quadrant 1.
-- The CPU `core/color/tonemap/tonemap_aces.js` stays. It is not Shade's tone mapping, and `PathTracedRenderer`
-  (`engine/graphics/sh3/path_tracer`) calls it.
-
-**Removing AgX (F2):**
-
-- `chunk_tonemap_agx.js` (`chunk_tonemap_agx`) goes. The same deep-import break applies. In the repo, only playground
-  quadrant 3 imports it.
-- The playground's `chunk_tonemap_agx_peak.js` goes with it.
-
-**Adding Neutral (F3):**
-
-- `ShadeToneMappingMode.PBR_NEUTRAL`, with two concrete passes beside the GT7 and NONE pairs:
-  `shader_tonemap_LDR_pbr_neutral` at peak 1, and `shader_tonemap_HDR_pbr_neutral` at the display's peak over the paper
-  white.
-- `chunk_tonemap_khronos_pbr` takes the peak. Its WGSL signature changes from `tonemap_khronos_pbr(c)` to
-  `tonemap_khronos_pbr(c, peak)`, a break for any WGSL caller outside the repo. The import path stays.
-- **The paper white becomes a canvas convention, not GT7's.** Neutral's HDR pass divides the display's peak by the same
-  paper white that puts SDR white at the canvas's 1.0: 250 cd/m² then, 203 since `5549db81f`. So `chunk_GT7_PAPER_WHITE_NITS` moves out of `gt7/` under a
-  name of its own, which is an import-path change too.
-- **Mid-grey sits lower.** Neutral puts an exposed 0.18 at 0.140 (the 0.04 Fresnel offset), where GT7 puts it at 0.179.
-  Switching modes darkens mid-grey by 0.36 EV. Auto-exposure meters the scene, not the output, so it will not
-  compensate.
-- **Pins:** the LDR pass equals the specification within float precision, and the HDR pass equals the LDR pass below the
-  start. Both are plain tests in the style of `shader_tonemap_HDR.spec.js`.
-- **Not measured:** Neutral's HDR highlights on an HDR display. This box's headless Chrome reports an SDR display, so §4
-  covers only what lies below SDR white.
-
-**In every case:**
-
-- **`chunk_tonemap_pbr_neutral.js` goes.** It is the Filament-derived duplicate that mixes toward 1 instead of the
-  compressed peak (SDR brief §4.3). Nothing imports it.
-- **The playground's grid** loses each quadrant whose chunk goes. It either drops them or keeps copies beside the page,
-  as it does for the GT7 sample code.
-
-## 6. Forks for Alex, all three taken
-
-- **F1. Remove ACES.** Delete `chunk_tonemap_aces.js` and drop it from the playground. The CPU `tonemap_aces` stays.
-- **F2. Remove AgX.** Delete `chunk_tonemap_agx.js` and the playground's `chunk_tonemap_agx_peak.js`, and drop AgX from
-  the playground.
-- **F3. Add `ShadeToneMappingMode.PBR_NEUTRAL`** with the peak form, moving the paper white out of `gt7/`. Delete
-  `chunk_tonemap_pbr_neutral.js` either way.
-  - If declined, Neutral goes too: delete `chunk_tonemap_khronos_pbr.js` and the playground's
-    `chunk_tonemap_pbr_neutral_peak.js`. The folder is then GT7 alone.
-  - If accepted, it waits on nothing else. The shader-switch proposal can later fold each mode's pair of passes into
-    one, as it would GT7's.
-
-**Landed 2026-10-16:**
-
-- `822dbc789`: the paper white leaves `gt7/`, as `chunk_PAPER_WHITE_NITS`.
-- `1851d9030`, F3: `ShadeToneMappingMode.PBR_NEUTRAL` with `shader_tonemap_LDR_pbr_neutral` and
-  `shader_tonemap_HDR_pbr_neutral`, and `tonemap_khronos_pbr(color, peak)`. The HDR pass floors the peak at the paper
-  white, where the operator is defined. On the RTX 4090 the engine's SDR canvas equals the specification to the code,
-  and its emulated-HDR canvas is within the SDR dither, 1 code, at or under 0.5.
-- `df9eb7694`, F1 and F2: the ACES, AgX and duplicate Neutral chunks are gone, along with `chunk_RRTAndODTFit`, the
-  ACES fit only the ACES chunk used. The playground compares GT7 and PBR Neutral.
-
-## 7. Not in scope, noticed
-
-- `chunk_tonemap_hdr_bt2390.js` and `chunk_tonemap_reinhard_luma.js` in the same folder have no importers either.
-- The doc comment on the playground's `chunk_tonemap_gt7_sdr_reference.js` still lists four departures of the engine's
-  `tonemap_gt7` from the sample code. Since `6ea10df28` only the blend space differs.
-- The playground's environment maps are untracked under `packages/meep-engine/test_assets/`. A worktree has none until
-  they are copied in, and the page then lights the exterior and the product shot with a flat sky.
-
-## Sources
-
-- Academy Software Foundation, ACES 2.0 core library and output transforms:
-  - https://github.com/aces-aswf/aces-core (`lib/Lib.Academy.Tonescale.ctl`, `lib/Lib.Academy.OutputTransform.ctl`,
-    `CHANGELOG.md`)
-  - https://github.com/aces-aswf/aces-output (`d65/displayP3/Output.Academy.P3-D65_1000nit_in_P3-D65_sRGB-Piecewise.ctl`)
-- OpenColorIO 2.6.0 (PyPI `opencolorio`), `FIXED_FUNCTION_ACES_OUTPUT_TRANSFORM_20`.
-- E. Chow:
-  - AgX configuration: https://github.com/EaryChow/AgX
-  - LUT generator: https://github.com/EaryChow/AgX_LUT_Gen (`AgXHLG.py`)
-- Blender, `release/datafiles/colormanagement/config.ocio`, main: https://projects.blender.org/blender/blender
-- A. Pestaluky, "An Adjustable Tonemapping Curve for Variable / Extended Dynamic Range", 2025-05-29:
-  https://allenwp.com/blog/2025/05/29/allenwp-tonemapping-curve/
-- Godot Engine, master and 4.7-stable:
-  - `servers/rendering/renderer_rd/shaders/effects/tonemap.glsl`
-  - `servers/rendering/storage/environment_storage.cpp`
-  - `doc/classes/Environment.xml`
-- Khronos, PBR Neutral: https://github.com/KhronosGroup/ToneMapping/tree/main/PBR_Neutral
-- E. Lalish, "Tone Mapping Considerations for Physically-Based Rendering": https://modelviewer.dev/examples/tone-mapping
-- Polyphony Digital, "Driving Toward Reality", SIGGRAPH 2025 PBS course, slides 113–120 and 154.

package/src/shade/renderer/shader/chunk/color/tonemap/SDR_TONE_MAPPING_BRIEF_2026_10_16.md

@@ -1,247 +0,0 @@
-# SDR tone mapping: a brief (2026-10-16)
-
-**Status: decided and built.** Alex chose GT7 on every output, with no per-output selector (§6). F1 landed first; F2 and
-F3 landed with `ShadeToneMappingMode`, whose modes were then `GT7` and `NONE`. The HDR forms brief beside this one
-then added `PBR_NEUTRAL` and removed the ACES and AgX chunks. The playground `src/shade/playground/tonemap_sdr/`
-compares GT7 and PBR Neutral.
-
-**The paper white is 203 cd/m² since `5549db81f` (2026-10-17),** BT.2408's graphics white, where this brief chose the
-sample code's 250. Every measurement below was taken at 250. At 203 the SDR pass is the sample code's SDR mode with
-`GRAN_TURISMO_SDR_PAPER_WHITE` at 203, under the 250 its parameters were tuned on, so it is no longer the sample code
-exactly. The curve's toe sits at a fixed 53.8 cd/m², so the change is not a scale: an exposed 0.18 comes out 0.176
-(116) instead of 0.179 (117). Against the compiled sample code at 203, over the same 648 inputs, the ICtCp blend differs
-by up to 0.33 codes in the mid-tones and 14.7 in saturated highlights, against 0.30 and 14.4 at 250.
-`shader_tonemap_LDR.spec.js` pins the sample code's output at 203.
-
-## 1. Recommendation
-
-**Make GT7's SDR mode the SDR default, exactly as Polyphony's sample code defines it.** The curve's peak is the
-250 cd/m² SDR paper white, and the result is scaled by 1/2.5. Shade's exposed 1.0 maps to that paper white.
-
-- It is the operator the HDR path already runs, and the source designs it so that SDR and HDR look alike.
-- It keeps the mid-tones linear: an exposed 0.18 comes out at 0.179.
-- Product colours come out within a few codes of their base colour.
-
-**The cost is highlight range.** GT7's SDR shoulder clips at 1.43× paper white, three stops above mid-grey. ACES
-reaches 6.5 stops, AgX 6.4 and Neutral 5.2. Polyphony accept the clip and lean on glare to carry what it removes;
-Shade's bloom, on by default, plays that part.
-
-**What would reverse it:** the clip reading as harsh in your session, in sunlit whites or skies, with bloom on. Neutral
-is then the default, at the price of SDR and HDR looking different.
-
-Four forks needed an answer first (§5). The first, the canvas primaries, was a defect every SDR frame showed, whichever
-operator was chosen.
-
-## 2. What the sources say
-
-### GT7: Polyphony's 2025 talk, sample code, and earlier talks
-
-Sources read:
-
-- "Driving Toward Reality", SIGGRAPH 2025 Physically Based Shading course, with speaker notes. There are no separate
-  course notes for this talk. Four copies were read, and they agree on everything cited here:
-  - slides v1.0 and v1.1 from the course page;
-  - the PDF on Polyphony's publications page;
-  - the PowerPoint there, whose hidden slides show which slides were not presented live.
-- `gt7_tone_mapping.cpp`, the sample code (MIT), from the course page.
-- The 2018 GT Sport talk notes.
-- Polyphony's CEDEC 2026 "Beyond HDR" deck, in Japanese.
-
-The authors do address SDR specifically:
-
-- **SDR is the same curve, with a fixed peak.** The peak is the paper white: 250 cd/m², 2.5 frame-buffer units, because
-  their frame buffer has 1.0 = 100 cd/m². The output is then multiplied by 1/2.5, so the paper white lands at sRGB 1.0.
-  This is on slide 153, which is hidden in the presented deck. It is in every published PDF, and `initializeAsSDR()`
-  in the sample code does the same.
-
-  The code comment in `initializeAsSDR()` says what the scaling is for (MIT, quoted):
-
-  > These adjustments ensure that the visual appearance (in terms of brightness) stays generally consistent across
-  > both HDR and SDR outputs
-
-- **SDR is the baseline the parameters were tuned on.** `initializeAsHDR()` accepts peaks from 250 up, "because the
-  parameters for GTToneMappingCurveV2 were determined based on an SDR paper white assumption of 250 nits" (MIT).
-- **One curve for every display is the design goal.** HDR is "a natural extension of SDR" (slide 27). Changing the peak
-  lets the same curve serve SDR and HDR (slide 135). Consistency across SDR and HDR is listed as a strength (slide 137).
-- **The clip is deliberate.** The v2 shoulder has a sharp clipping point. Polyphony accepted it because TVs tone map
-  as well (slide 147). A desktop sRGB monitor does not, so on one the clip is final.
-- **Glare compensates on SDR.** Glare is drawn wider on SDR than on HDR, which treats the peak-luminance gap as an
-  aperture difference (slide 184).
-- **Their operator comparison was made in SDR**, and they say it carries over to HDR (slide 154). ACES maps 0.18 to
-  about 10 cd/m², roughly 1/1.8 of the 18 cd/m² other operators give (slide 117, hidden in the presented deck). They
-  scaled ACES to match exposure before comparing.
-- **ICtCp builds the "untwisted" colour; the final blend is in RGB.**
-  - Steps 2 and 3 (slides 148–149) work in the UCS, ICtCp in the sample code. The untwisted colour takes its intensity
-    from the per-channel colour and its chroma from the original, faded toward the peak.
-  - Step 4 (slide 150, presented) lerps the per-channel and untwisted colours in linear Rec.2020 RGB. The slide says
-    they tried blending in the UCS and found RGB looked better to them; the speaker note says the same. The code on
-    slides 153 and 243 blends in RGB.
-  - The hidden slide 153 adds that blending in a UCS works as well. The engine's chunk takes that route (§4.2).
-- **The SDR white moved between titles.** The 2018 GT Sport notes define SDR maximum brightness as 100 cd/m² (p. 66).
-  GT7 assumes 250.
-- **CEDEC 2026** repeats the policy of one physically based tone mapping across SDR and HDR (p. 82). It adds nothing
-  on SDR parameters.
-- **Not stated anywhere:** the auto-exposure target. Where mid-grey lands in GT7's own SDR output cannot be known from
-  the talk. Shade's convention decides it (§3).
-
-### Khronos PBR Neutral (Emmett Lalish)
-
-- Built for e-commerce. The Khronos repository (CC-BY 4.0) describes it as "aimed toward product photography use
-  cases, where the scene is well-exposed and HDR color values are mostly restricted to small specular highlights".
-- Below 0.8, base colours are reproduced 1:1, less the 0.04 Fresnel offset. Hue is never shifted, and highlights
-  desaturate smoothly to white.
-- sRGB output only, with no gamut mapping.
-- The model-viewer write-up proposes it as an option where tools offer several operators, and as the default where they
-  offer one. It also says plainly that film and games want something else.
-
-### AgX (Eary Chow's, the one Blender, Godot and three.js use)
-
-- Made to replace Blender's Filmic. It forms a closed-domain image with smooth chromatic attenuation, for wide-gamut
-  and spectral rendering.
-- 16.5 stops of range. It is meant to be used with looks; "Punchy" is the contrast one.
-- Chow's configuration has a 1000 cd/m² HDR view. The LUT everyone ships, and the three.js port Shade's chunk comes
-  from, are SDR only (talk slide 113).
-
-## 3. Measured
-
-The CPU ports are line-for-line from each source. The GT7 port was checked against Polyphony's code compiled with MSVC:
-1.8e-4 over 648 inputs. The WGSL port in the playground was checked against the same outputs on the RTX 4090: 4.4e-4.
-Inputs are exposed linear Rec.709. Outputs are display-linear, with sRGB codes in brackets.
-
-| | 0.18 out | contrast at 0.18 | white reached at | 0.8 grey | canary 231,218,63 | red 203,63,63 |
-|---|---|---|---|---|---|---|
-| ACES (today) | 0.106 (91) | 1.48 | +6.5 EV | 195 | 196,187,67 | 175,29,38 |
-| **GT7 SDR** (reference, 1.0 = paper white) | 0.179 (117) | 1.05 | +3.0 EV | 221 | 224,212,61 | 201,58,58 |
-| GT7 SDR, literal frame buffer (1.0 = 100 cd/m²) | 0.058 (68) | 1.34 | +4.3 EV | 153 | 153,144,31 | 130,28,31 |
-| AgX | 0.215 (128) | 0.80 | +6.4 EV | 194 | 197,185,121 | 204,97,87 |
-| Neutral | 0.140 (105) | 1.29 | +5.2 EV | 226 | 227,213,34 | 198,34,34 |
-
-"Contrast" is d log out / d log in. "White reached at" is the exposure, in stops over 0.18, where output reaches 0.99.
-
-**Saturated emitters, as exposure rises:**
-
-- ACES walks fire orange from 18° to 47° by +4 EV: it turns yellow. It also takes neon blue toward cyan.
-- GT7 holds hue through the mid-tones, then whitens sharply. Fire is pale yellow by +2 EV and white by +4.
-- Neutral never moves hue. Fire whitens through a pinkish white rather than yellow.
-- AgX desaturates even at normal exposure: fire is at saturation 0.76 at +0 EV, where the others are at 0.95–0.97.
-
-**Mapping Shade's exposure onto GT7's frame buffer** is the one free parameter, and it is only an exposure offset of
-1.32 stops. Shade's auto-exposure puts its meter at 0.18, a fraction of paper white. Reading that as GT7's paper white
-(×2.5) lands 0.18 at 0.179, as other operators do. It also matches the HDR path, which normalises by the paper white
-the same way. Reading it literally (1.0 = 100 cd/m²) darkens SDR mid-tones to 0.058.
-
-## 4. Engine findings that bear on the choice (measured)
-
-1. **The SDR path shows Rec.709 values as Display P3.** `Renderer` configures the canvas `colorSpace: 'display-p3'` on
-   both paths. `shader_tonemap_HDR` converts to P3, but `shader_tonemap_LDR` writes Rec.709 values without converting.
-
-   A `display-p3` canvas was cleared to known values and read back through a 2D sRGB canvas:
-
-   | colour | intended | as-is |
-   |---|---|---|
-   | ACES red | 175,29,38 | 191,0,28 |
-   | Neutral red | 198,34,34 | 216,0,16 |
-   | canary yellow | 227,213,34 | 230,212,0 |
-
-   Converted to P3 first, each reproduces exactly. Grey is unaffected.
-
-   In the upstream repository, the commit that tagged the canvas `display-p3` (`105e8eec`, 2025-12-22, "finished HDR
-   mapper") also switched SDR from Khronos PBR Neutral to ACES. Under this mismatch Neutral's saturated output is pushed
-   furthest, so ACES may have been picked against a skewed picture. The commit does not say why it switched.
-2. **The engine's `tonemap_gt7` is not Polyphony's.** It differs from the sample code in four ways:
-
-   | | engine | sample code |
-   |---|---|---|
-   | weight of the per-channel colour | 0.7 | 0.4 (`blendRatio_` 0.6 weights the untwisted one) |
-   | final blend in | ICtCp | linear Rec.2020 RGB; the talk says a UCS also works (§2) |
-   | chroma fade | fixed PQ window 0.7–1.0 | 0.98–1.16 of the target's own intensity |
-   | clamp at the target | no | yes |
-
-   The overshoot comes from the other three differences, not the blend space. Adding them to the engine's chunk one at
-   a time:
-   - **The clamp alone** brings HDR white from 11.85 to 10.00, and blue at +5 EV from 15.2 to 10.5.
-   - **At SDR,** the fade and the weight carry most of the gap. The canary yellow at +1.75 EV goes from 255,255,131 to
-     135 with the clamp, to 186 with the fade, and to 216 with the weight.
-   - **The blend space alone** separates 216 from the sample code's 224. For fire at +2 EV it separates 192 from 197.
-
-   Mid-tones are identical: 0.18 → 0.145 in HDR at 1000/100 for both. Near and above the peak they part:
-   - in HDR at 1000 cd/m², white reaches 11.85 against the target 10.0, 18.5% over the assumed peak;
-   - saturated blue at +5 EV reaches 15.2 in its blue channel, against the sample code's 10.6;
-   - at SDR settings (250/250), the canary yellow at +1.75 EV comes out 255,255,131 against the sample code's
-     255,255,224, a 93-code gap. It holds chroma, then clips per channel.
-3. **Two Neutral chunks.** `chunk_tonemap_khronos_pbr` matches the specification. `chunk_tonemap_pbr_neutral`, taken
-   from Filament, mixes toward 1.0 instead of the compressed peak. Grey 2.0 comes out 0.965 instead of 0.960, and grey
-   32 comes out 1.000 instead of 0.998. No renderer shader imports either; the playground imports the specification one.
-4. **The ACES chunk is the Hill fit without three.js's 1/0.6.** Its comment still describes the 1/0.6 scale, which the
-   code does not apply. It maps 0.18 to 0.106; three.js maps it to 0.213.
-5. **The HDR path's paper white is 100** (`Renderer.js`, `paper_white_nits: 100`). GT7 puts SDR white at 250. With 100,
-   an exposed 0.18 shows at 0.145 of SDR white in HDR and at 0.179 in GT7 SDR.
-
-## 5. Forks to answer before the default changes
-
-- **F1, the SDR primaries (§4.1).** I recommend `shader_tonemap_LDR` convert to Display P3, as the HDR shader does,
-  rather than configuring an SDR canvas `srgb`. Then GT7's Rec.2020 output keeps its P3 gamut on wide-gamut SDR
-  laptops.
-
-  Both paths already assume the `display-p3` configure succeeds. Their shared fallback to `srgb` is untreated, and that
-  is a separate item. F1 changes every SDR frame's saturation, so it is its own commit, pinned before any operator
-  change.
-- **F2, align `tonemap_gt7` with the sample code (§4.2).** I recommend the clamp, the fade and the weight. Keeping
-  the ICtCp blend is a choice the talk allows. It costs up to 0.3 codes in the mid-tones and up to 14 in saturated
-  highlights, over 648 inputs. It changes HDR highlights near the peak and nothing in the mid-tones.
-
-  Declining means GT7 SDR would run the engine's variant, which overshoots and clips per channel at SDR. I would then
-  reconsider GT7 as the default, or add at least the clamp.
-- **F3, the paper white.** I recommend SDR at 250 with exposed 1.0 as the paper white (§3), and the HDR path at 250 as
-  well (§4.5), so both put an exposed 0.18 at the same fraction of SDR white. The HDR change brightens HDR mid-tones by
-  0.3 stops.
-- **F4, the selector (§6).** Superseded: Alex chose one mode for every output instead of an SDR selector.
-
-## 6. What was built
-
-Alex decided against a per-output selector. The tone mapper is one choice for every display, which is the reason the
-GT7 talk gives for its operator. So there is no SDR setting, and the renderer offers two modes:
-
-```js
-renderer.tone_mapping_mode = ShadeToneMappingMode.GT7;   // the default
-renderer.tone_mapping_mode = ShadeToneMappingMode.NONE;  // exposure only; SDR clips at 1.0, HDR at the display
-```
-
-- **Four concrete passes.** The output's dynamic range and the mode pick the pass:
-  - `shader_tonemap_LDR` and `shader_tonemap_HDR` for GT7;
-  - `shader_tonemap_LDR_none` and `shader_tonemap_HDR_none` for NONE.
-
-  Each module lists its own chunks, so a mode's dependencies are visible. No `override`, no runtime branch on a
-  setting. If shader switches land, each pair can become one pass with a choice.
-- **The paper white is a convention, not a setting.** `chunk_GT7_PAPER_WHITE_NITS` (250; since the HDR forms brief
-  `chunk_PAPER_WHITE_NITS`, and 203 since `5549db81f`) is the paper white on both outputs, and SDR also uses it as the
-  peak. Below the SDR shoulder the two outputs therefore write the same colour: pinned in `shader_tonemap_HDR.spec.js`.
-  The HDR pass's only setting is the display's peak.
-- **`tonemap_gt7` follows the sample code** in the curve, the relative chroma fade, the 0.6 untwisted weight and the
-  clamp at the target, and keeps the ICtCp blend (F2). Against the compiled sample code over 648 inputs it differs by up
-  to 0.3 sRGB codes in the mid-tones and up to 14 in saturated highlights, at 250; at 203, against the sample code at
-  203, by 0.33 and 14.7. An earlier draft of this brief said "at most 8", from four hand-picked cases; the full sweep
-  says 14.
-- **ACES, AgX and Neutral were unwired** here, kept for a look at HDR-aware variants of each.
-  `HDR_TONE_MAPPING_FORMS_BRIEF_2026_10_16.md` took that look: ACES and AgX are removed, and Neutral is
-  `ShadeToneMappingMode.PBR_NEUTRAL`, with the display's peak in place of the specification's 1 on HDR.
-
-## 7. Follow-ups this turned up, not done
-
-- The `srgb` fallback in `Renderer`'s canvas configure is untreated by both tonemap shaders (§5, F1).
-- `make_sunlight` hands `kelvin_to_rgb`'s sRGB-encoded triple to `Light.color`, which is documented as linear.
-  Not measured.
-- `chunk_tonemap_pbr_neutral` duplicated the specification chunk with a difference (§4.3). Removed with the HDR forms
-  brief's F3.
-
-## Sources
-
-- Polyphony Digital, "Driving Toward Reality: Physically Based Tone Mapping and Perceptual Fidelity in Gran Turismo 7",
-  SIGGRAPH 2025 PBS course: https://blog.selfshadow.com/publications/s2025-shading-course/ (slides v1.1,
-  `pdi/supplemental/gt7_tone_mapping.cpp`).
-- Uchimura and Suzuki, "Practical HDR and Wide Color Techniques in Gran Turismo SPORT", SIGGRAPH Asia 2018, with notes:
-  https://www.polyphony.co.jp/publications/sa2018/
-- Polyphony Digital and Sony, "Beyond HDR", CEDEC 2026: https://www.polyphony.co.jp/publications/
-- Khronos, PBR Neutral specification: https://github.com/KhronosGroup/ToneMapping/tree/main/PBR_Neutral
-- E. Lalish, "Tone Mapping Considerations for Physically-Based Rendering": https://modelviewer.dev/examples/tone-mapping
-- E. Chow, AgX for Blender: https://github.com/EaryChow/AgX

package/src/shade/renderer/shader/chunk/fsr/NOTES.md

@@ -1,3 +0,0 @@
-see:
-
-* https://github.com/GPUOpen-LibrariesAndSDKs/FidelityFX-SDK

package/src/shade/renderer/shader/chunk/fsr/spd/NOTES.md

@@ -1,4 +0,0 @@
-Single Pass Downsample
-
-* see https://gpuopen.com/fidelityfx-spd/
-* see https://github.com/GPUOpen-LibrariesAndSDKs/FidelityFX-SDK/tree/main/samples/spd

package/src/shade/renderer/shader/chunk/geometry/ray/NOTES.md

@@ -1,4 +0,0 @@
-AMD has a SW implementation of RTX here:
-https://github.com/GPUOpen-Drivers/gpurt/blob/d142df384ebb5ef818e7b001a2d2523633a17cda/src/shaders/RayQuery1_1.hlsl#L128
-
-Would be useful to adopt some of their techniques, specifically APIs and tree structure