@woosh/meep-engine 3.47.0 → 3.50.0

package/src/shade/renderer/shader/chunk/clipmap/chunk_clipmap_select_finest.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The finest level of a clipmap whose window holds a world point, and how far into that window's
+ * edge band the point is.
+ *
+ * Walks the first `count` levels of the table, finest first, at most {@link CLIPMAP_LEVEL_LIMIT}; the
+ * first whose window holds the cell the point is in answers. Its `edge_weight` is the point's distance
+ * to the window's nearest face, in the level's cells, through a linear ramp: 0 at `band_width` cells
+ * or deeper, 1 on the face. It is how much a reader blends toward the next coarser source — the
+ * parent level, or whatever stands outside the coarsest. `band_width` is positive.
+ *
+ * A point no level holds answers `CLIPMAP_LEVEL_NONE`, with a weight of 0.
+ *
+ * The CPU twin is `clipmap_select_finest` in `core/geom/clipmap/`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_clipmap_select_finest: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_clipmap_select_finest.d.ts.map

package/src/shade/renderer/shader/chunk/clipmap/chunk_clipmap_select_finest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_clipmap_select_finest.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/clipmap/chunk_clipmap_select_finest.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AACH,0CAFU,SAAS,CAoDjB;0BAtEwB,6BAA6B"}

package/src/shade/renderer/shader/chunk/clipmap/chunk_clipmap_select_finest.js

@@ -0,0 +1,71 @@
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+import { CLIPMAP_LEVEL_ARRAY, CLIPMAP_LEVEL_LIMIT, CLIPMAP_LEVEL_STRUCT } from "./CLIPMAP_LEVEL_STRUCT.js";
+import { chunk_clipmap_contains } from "./chunk_clipmap_contains.js";
+
+/**
+ * The finest level of a clipmap whose window holds a world point, and how far into that window's
+ * edge band the point is.
+ *
+ * Walks the first `count` levels of the table, finest first, at most {@link CLIPMAP_LEVEL_LIMIT}; the
+ * first whose window holds the cell the point is in answers. Its `edge_weight` is the point's distance
+ * to the window's nearest face, in the level's cells, through a linear ramp: 0 at `band_width` cells
+ * or deeper, 1 on the face. It is how much a reader blends toward the next coarser source — the
+ * parent level, or whatever stands outside the coarsest. `band_width` is positive.
+ *
+ * A point no level holds answers `CLIPMAP_LEVEL_NONE`, with a weight of 0.
+ *
+ * The CPU twin is `clipmap_select_finest` in `core/geom/clipmap/`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_clipmap_select_finest = CodeChunk.from(
+    //language=WGSL
+    `
+const CLIPMAP_LEVEL_NONE: u32 = 0xFFFFFFFFu;
+
+struct ClipmapSelection {
+    // the finest level holding the point, or CLIPMAP_LEVEL_NONE
+    level: u32,
+    // 0 deeper than the band, rising to 1 on the window's nearest face
+    edge_weight: f32,
+}
+
+fn clipmap_select_finest(
+    levels: ptr<uniform, ${CLIPMAP_LEVEL_ARRAY.wgsl_ref}>,
+    count: u32,
+    position_ws: vec3f,
+    band_width: f32,
+) -> ClipmapSelection {
+
+    for (var i = 0u; i < ${CLIPMAP_LEVEL_LIMIT}u; i++) {
+        if (i >= count) {
+            break;
+        }
+
+        let level = (*levels)[i];
+
+        // the point in the level's cells
+        let position_cells = position_ws / level.cell_size;
+
+        if (!clipmap_contains(vec3<i32>(floor(position_cells)), level.corner, level.size)) {
+            continue;
+        }
+
+        let from_corner = position_cells - vec3f(level.corner);
+        let to_far_corner = vec3f(level.size) - from_corner;
+
+        let edge = min(
+            min(min(from_corner.x, from_corner.y), from_corner.z),
+            min(min(to_far_corner.x, to_far_corner.y), to_far_corner.z)
+        );
+
+        return ClipmapSelection(i, saturate(1.0 - edge / band_width));
+    }
+
+    return ClipmapSelection(CLIPMAP_LEVEL_NONE, 0.0);
+}
+`, [
+        CLIPMAP_LEVEL_STRUCT.declaration_chunk,
+        chunk_clipmap_contains,
+    ]
+);

package/src/shade/renderer/shader/chunk/clipmap/chunk_clipmap_storage_coord.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Where a cell of a clipmap level sits in storage that wraps: `cell mod period` on each axis,
+ * Euclidean, so negative cells wrap too. Anchored to the world, not to the window, so a window that
+ * moves keeps every cell still inside it where it was.
+ *
+ * The period is the storage's extent on each axis — a window's side, or one more than it along the
+ * axis a face-centred component is stored on.
+ *
+ * The CPU twin is `ClipmapWindowSet.storage_cell`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_clipmap_storage_coord: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_clipmap_storage_coord.d.ts.map

package/src/shade/renderer/shader/chunk/clipmap/chunk_clipmap_storage_coord.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_clipmap_storage_coord.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/clipmap/chunk_clipmap_storage_coord.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH,0CAFU,SAAS,CAWjB;0BAxBwB,6BAA6B"}

package/src/shade/renderer/shader/chunk/clipmap/chunk_clipmap_storage_coord.js

@@ -0,0 +1,25 @@
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+import { chunk_mod_v3i } from "../geometry/vec3/chunk_mod_v3i.js";
+
+/**
+ * Where a cell of a clipmap level sits in storage that wraps: `cell mod period` on each axis,
+ * Euclidean, so negative cells wrap too. Anchored to the world, not to the window, so a window that
+ * moves keeps every cell still inside it where it was.
+ *
+ * The period is the storage's extent on each axis — a window's side, or one more than it along the
+ * axis a face-centred component is stored on.
+ *
+ * The CPU twin is `ClipmapWindowSet.storage_cell`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_clipmap_storage_coord = CodeChunk.from(
+    //language=WGSL
+    `
+fn clipmap_storage_coord(cell: vec3<i32>, period: vec3<i32>) -> vec3<i32> {
+    return mod_v3i(cell, period);
+}
+`, [
+        chunk_mod_v3i,
+    ]
+);

package/src/shade/renderer/shader/chunk/color/conversion/chunk_CRM_FROM_REC709_TO_P3.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Color rotation matrix. Linear Rec.709 to linear Display P3, in one step rather than through Rec.2020.
+ *
+ * Derived in double precision from the chromaticities, both with a D65 white, so there is no chromatic adaptation:
+ *
+ * ```
+ *               red            green          blue
+ *  Rec.709      0.640, 0.330   0.300, 0.600   0.150, 0.060
+ *  Display P3   0.680, 0.320   0.265, 0.690   0.150, 0.060
+ * ```
+ *
+ * The two share their blue primary, so Rec.709 blue lands on P3 blue alone and the third column holds exact zeros.
+ * @type {CodeChunk}
+ */
+export const chunk_CRM_FROM_REC709_TO_P3: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_CRM_FROM_REC709_TO_P3.d.ts.map

package/src/shade/renderer/shader/chunk/color/conversion/chunk_CRM_FROM_REC709_TO_P3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_CRM_FROM_REC709_TO_P3.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/color/conversion/chunk_CRM_FROM_REC709_TO_P3.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,0CAFU,SAAS,CAWjB;0BAzBwB,gCAAgC"}

package/src/shade/renderer/shader/chunk/color/conversion/chunk_CRM_FROM_REC709_TO_P3.js

@@ -0,0 +1,26 @@
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+
+/**
+ * Color rotation matrix. Linear Rec.709 to linear Display P3, in one step rather than through Rec.2020.
+ *
+ * Derived in double precision from the chromaticities, both with a D65 white, so there is no chromatic adaptation:
+ *
+ * ```
+ *               red            green          blue
+ *  Rec.709      0.640, 0.330   0.300, 0.600   0.150, 0.060
+ *  Display P3   0.680, 0.320   0.265, 0.690   0.150, 0.060
+ * ```
+ *
+ * The two share their blue primary, so Rec.709 blue lands on P3 blue alone and the third column holds exact zeros.
+ * @type {CodeChunk}
+ */
+export const chunk_CRM_FROM_REC709_TO_P3 = CodeChunk.from(
+    //language=WGSL
+    `
+const CRM_FROM_REC709_TO_P3 = mat3x3<f32>(
+    vec3(0.8224619687, 0.03319419885, 0.01708263072),
+    vec3(0.1775380313, 0.9668058011,  0.07239744066),
+    vec3(0.0,          0.0,           0.9105199286)
+);
+    `
+);

package/src/shade/renderer/shader/chunk/color/iCtCp/chunk_eotf_st2084.d.ts

@@ -5,7 +5,7 @@
  *
  * `REFERENCE_LUMINANCE` is **not** an SDR white point competing with the 203 nits of BT.2408. It is the
  * "Standard 1.0 unit" from the GT7 tone mapping paper, and it is the same 100 that `chunk_tonemap_gt7`
- * uses to normalise its `paper_white_nits` and `peak_nits` uniforms. The two have to stay equal: GT7
+ * uses to normalise its `paper_white_nits` and `peak_nits` arguments. The two have to stay equal: GT7
  * round-trips through this function and its inverse, so changing one alone shifts the whole curve.
  *
  * Three different quantities in this engine are all called a reference white, and they are worth keeping

package/src/shade/renderer/shader/chunk/color/iCtCp/chunk_eotf_st2084.js

@@ -1,63 +1,63 @@
-import { CodeChunk } from "../../../compiler/CodeChunk.js";
-
-/**
- * SMPTE ST 2084 EOTF, decoding a PQ signal to linear light in GT7 units.
- *
- * ## About that 100
- *
- * `REFERENCE_LUMINANCE` is **not** an SDR white point competing with the 203 nits of BT.2408. It is the
- * "Standard 1.0 unit" from the GT7 tone mapping paper, and it is the same 100 that `chunk_tonemap_gt7`
- * uses to normalise its `paper_white_nits` and `peak_nits` uniforms. The two have to stay equal: GT7
- * round-trips through this function and its inverse, so changing one alone shifts the whole curve.
- *
- * Three different quantities in this engine are all called a reference white, and they are worth keeping
- * apart:
- *
- * | Where | Value | What it means |
- * |---|---|---|
- * | here, and `chunk_tonemap_gt7` | 100 nits | GT7's internal unit for a GPU linear `1.0` |
- * | `core/color/PQ/PQ_constants.js` | 203 nits | BT.2408 graphics white, a *renderer* convention |
- * | `format/image/avif/color/transfer_to_linear.js` | 100 nits | the reference display the SDR curves in H.273 are defined against |
- *
- * The CPU's `linear_to_PQ` / `PQ_to_linear` fold in none of these — they are pure ST 2084 in PQ's own
- * normalisation, which is what makes them an exact inverse pair — so the 203 is applied by their callers.
- * This chunk does fold its 100 in, on both sides, so it is an exact inverse pair too, just of a different
- * function.
- *
- * The place the two conventions actually meet is `linear_reference_nits`, which `sampler2d_to_avif` and
- * `avif_to_sampler2d` each name explicitly.
- *
- * @see chunk_inverseEotfSt2084
- * @see chunk_tonemap_gt7 the consumer whose REF_LUMINANCE must match
- * @type {CodeChunk}
- */
-export const chunk_eotfSt2084 = CodeChunk.from(
-    //language=WGSL
-    `
-fn eotfSt2084(n_in: f32) -> f32 {
-    var n = n_in;
-    if (n < 0.0) { n = 0.0; }
-    if (n > 1.0) { n = 1.0; }
-
-    let m1 = 0.1593017578125; 
-    let m2 = 78.84375;      // Scale 1.0 
-    let c1 = 0.8359375; 
-    let c2 = 18.8515625; 
-    let c3 = 18.6875; 
-    let pqC = 10000.0; 
-
-    let np = pow(n, 1.0 / m2);
-    var l = np - c1;
-    if (l < 0.0) { l = 0.0; }
-    
-    l = l / (c2 - c3 * np);
-    l = pow(l, 1.0 / m1);
-
-    let physical = l * pqC;
-
-    const REFERENCE_LUMINANCE = 100.0;
-
-    return physical / REFERENCE_LUMINANCE;
-}
-    `
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+
+/**
+ * SMPTE ST 2084 EOTF, decoding a PQ signal to linear light in GT7 units.
+ *
+ * ## About that 100
+ *
+ * `REFERENCE_LUMINANCE` is **not** an SDR white point competing with the 203 nits of BT.2408. It is the
+ * "Standard 1.0 unit" from the GT7 tone mapping paper, and it is the same 100 that `chunk_tonemap_gt7`
+ * uses to normalise its `paper_white_nits` and `peak_nits` arguments. The two have to stay equal: GT7
+ * round-trips through this function and its inverse, so changing one alone shifts the whole curve.
+ *
+ * Three different quantities in this engine are all called a reference white, and they are worth keeping
+ * apart:
+ *
+ * | Where | Value | What it means |
+ * |---|---|---|
+ * | here, and `chunk_tonemap_gt7` | 100 nits | GT7's internal unit for a GPU linear `1.0` |
+ * | `core/color/PQ/PQ_constants.js` | 203 nits | BT.2408 graphics white, a *renderer* convention |
+ * | `format/image/avif/color/transfer_to_linear.js` | 100 nits | the reference display the SDR curves in H.273 are defined against |
+ *
+ * The CPU's `linear_to_PQ` / `PQ_to_linear` fold in none of these — they are pure ST 2084 in PQ's own
+ * normalisation, which is what makes them an exact inverse pair — so the 203 is applied by their callers.
+ * This chunk does fold its 100 in, on both sides, so it is an exact inverse pair too, just of a different
+ * function.
+ *
+ * The place the two conventions actually meet is `linear_reference_nits`, which `sampler2d_to_avif` and
+ * `avif_to_sampler2d` each name explicitly.
+ *
+ * @see chunk_inverseEotfSt2084
+ * @see chunk_tonemap_gt7 the consumer whose REF_LUMINANCE must match
+ * @type {CodeChunk}
+ */
+export const chunk_eotfSt2084 = CodeChunk.from(
+    //language=WGSL
+    `
+fn eotfSt2084(n_in: f32) -> f32 {
+    var n = n_in;
+    if (n < 0.0) { n = 0.0; }
+    if (n > 1.0) { n = 1.0; }
+
+    let m1 = 0.1593017578125; 
+    let m2 = 78.84375;      // Scale 1.0 
+    let c1 = 0.8359375; 
+    let c2 = 18.8515625; 
+    let c3 = 18.6875; 
+    let pqC = 10000.0; 
+
+    let np = pow(n, 1.0 / m2);
+    var l = np - c1;
+    if (l < 0.0) { l = 0.0; }
+    
+    l = l / (c2 - c3 * np);
+    l = pow(l, 1.0 / m1);
+
+    let physical = l * pqC;
+
+    const REFERENCE_LUMINANCE = 100.0;
+
+    return physical / REFERENCE_LUMINANCE;
+}
+    `
 )

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.