@woosh/meep-engine 3.47.0 → 3.49.0

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

@@ -0,0 +1,318 @@
+# 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.
+
+## 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
+  250 cd/m² that puts SDR white at the canvas's 1.0. 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

@@ -0,0 +1,237 @@
+# 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.
+
+## 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) 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. 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/color/tonemap/chunk_PAPER_WHITE_NITS.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The luminance an exposed scene value of 1.0 is shown at, in cd/m², on every display and in every tone mapping mode.
+ * It is where the canvas puts SDR white: 1.0 on an SDR output, and 1.0 of extended Display P3 on an HDR one, so an HDR
+ * pass's headroom is the display's peak over this.
+ *
+ * The value is the SDR paper white of GT7's sample code, `GRAN_TURISMO_SDR_PAPER_WHITE`. Polyphony tuned the curve's
+ * parameters under this assumption; their sample code accepts no HDR peak below it. The GT7 passes give it to
+ * `tonemap_gt7` as the paper white, and the SDR pass also as the peak, which is the sample code's SDR mode.
+ *
+ * It is one constant rather than an argument for each pass, so the SDR and HDR outputs cannot drift apart.
+ *
+ * @see "Driving Toward Reality: Physically Based Tone Mapping and Perceptual Fidelity in Gran Turismo 7", slide 153
+ * @type {CodeChunk}
+ */
+export const chunk_PAPER_WHITE_NITS: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_PAPER_WHITE_NITS.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_PAPER_WHITE_NITS.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/color/tonemap/chunk_PAPER_WHITE_NITS.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,qCAFU,SAAS,CAOjB;0BArBwB,gCAAgC"}

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

@@ -0,0 +1,22 @@
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+
+/**
+ * The luminance an exposed scene value of 1.0 is shown at, in cd/m², on every display and in every tone mapping mode.
+ * It is where the canvas puts SDR white: 1.0 on an SDR output, and 1.0 of extended Display P3 on an HDR one, so an HDR
+ * pass's headroom is the display's peak over this.
+ *
+ * The value is the SDR paper white of GT7's sample code, `GRAN_TURISMO_SDR_PAPER_WHITE`. Polyphony tuned the curve's
+ * parameters under this assumption; their sample code accepts no HDR peak below it. The GT7 passes give it to
+ * `tonemap_gt7` as the paper white, and the SDR pass also as the peak, which is the sample code's SDR mode.
+ *
+ * It is one constant rather than an argument for each pass, so the SDR and HDR outputs cannot drift apart.
+ *
+ * @see "Driving Toward Reality: Physically Based Tone Mapping and Perceptual Fidelity in Gran Turismo 7", slide 153
+ * @type {CodeChunk}
+ */
+export const chunk_PAPER_WHITE_NITS = CodeChunk.from(
+    //language=WGSL
+    `
+const PAPER_WHITE_NITS: f32 = 250.0;
+`
+);

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

@@ -1,6 +1,19 @@
 /**
+ * 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}
  */

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

@@ -1 +1 @@
-{"version":3,"file":"chunk_tonemap_khronos_pbr.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/color/tonemap/chunk_tonemap_khronos_pbr.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wCAFU,SAAS,CA4BjB;0BAlCwB,gCAAgC"}
+{"version":3,"file":"chunk_tonemap_khronos_pbr.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/color/tonemap/chunk_tonemap_khronos_pbr.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wCAFU,SAAS,CA4BjB;0BA/CwB,gCAAgC"}