@woosh/meep-engine 3.47.0 → 3.50.0

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"}

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

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

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

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

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

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