@woosh/meep-engine 3.47.0 → 3.49.0

package/src/shade/renderer/shader/ComputeShader.js

@@ -2,6 +2,10 @@ import { assert } from "../../../core/assert.js";
 import { ComputePipelineDescriptor } from "../../descriptor/pipeline/compute/ComputePipelineDescriptor.js";
 import { ShaderDescriptor } from "./ShaderDescriptor.js";
 
+/**
+ * @typedef {import("./compiler/ShaderSwitchSet.js").ShaderSwitchSet} ShaderSwitchSet
+ */
+
 const VALIDATION_ENABLED = true;
 
 export class ComputeShader {
@@ -82,6 +86,55 @@ export class ComputeShader {
         return this.#descriptor;
     }
 
+    /**
+     * This shader's variants, by every set asked for and by the descriptor each was built from.
+     * @type {Map<ShaderSwitchSet|ShaderDescriptor, ComputeShader>}
+     */
+    #variants = new Map();
+
+    /**
+     * This shader as `set` makes it — see {@link ShaderDescriptor#variant}. Sets that agree on the
+     * descriptor's switches get the one shader, and the set with all of them `0` gets this one.
+     *
+     * Every variant has this shader's `@workgroup_size`: a switch changes what a pass computes, never
+     * how it is dispatched, and a dispatch sized by one variant must fit them all.
+     *
+     * @param {ShaderSwitchSet} set
+     * @returns {ComputeShader}
+     */
+    variant(set) {
+        let r = this.#variants.get(set);
+
+        if (r !== undefined) {
+            return r;
+        }
+
+        const descriptor = this.#descriptor.variant(set);
+
+        if (descriptor === this.#descriptor) {
+            r = this;
+        } else {
+            r = this.#variants.get(descriptor);
+
+            if (r === undefined) {
+                r = new ComputeShader(descriptor);
+
+                const own = this.#group_size;
+                const theirs = r.#group_size;
+
+                if (own[0] !== theirs[0] || own[1] !== theirs[1] || own[2] !== theirs[2]) {
+                    throw new Error(`ComputeShader '${descriptor.label}' has @workgroup_size(${theirs}), and '${this.#descriptor.label}' has (${own}); the variants of a shader dispatch alike`);
+                }
+
+                this.#variants.set(descriptor, r);
+            }
+        }
+
+        this.#variants.set(set, r);
+
+        return r;
+    }
+
     /**
      *
      * @param {ShaderDescriptor} descriptor

package/src/shade/renderer/shader/ImageShader.d.ts

@@ -15,13 +15,11 @@ export class ImageShader {
         targets: ColorTargetState[];
         depthStencil?: DepthStencilState;
     }): ImageShader;
-    /**
-     *
-     * @param {ShaderDescriptor} descriptor
-     * @param {(ColorTargetState|{clearValue?:number[]})[]} [targets]
-     * @param {DepthStencilState} [depthStencil]
-     */
-    constructor({ descriptor, targets, depthStencil, }: ShaderDescriptor);
+    constructor({ descriptor, targets, depthStencil, }: {
+        descriptor: any;
+        targets?: any[];
+        depthStencil: any;
+    });
     /**
      *
      * @returns {ShaderDescriptor}
@@ -36,12 +34,31 @@ export class ImageShader {
      *
      * @returns {RenderPipelineDescriptor}
      */
-    get pipeline(): RenderPipelineDescriptor;
+    get pipeline(): import("../../descriptor/pipeline/render/RenderPipelineDescriptor.js").RenderPipelineDescriptor;
+    /**
+     * The pipeline {@link draw} uses when it draws into attachments of these formats: {@link pipeline}
+     * itself when they are the formats it declares, otherwise a copy rewritten for them
+     * (rgba8unorm -> bgra8unorm, say). Offer this, not {@link pipeline}, for a pass that draws into
+     * a target it was handed — what an offer compiles is otherwise a variant no frame draws with.
+     *
+     * @param {GPUTextureFormat[]} color_formats one per fragment target
+     * @returns {RenderPipelineDescriptor}
+     */
+    pipeline_for(color_formats: GPUTextureFormat[]): RenderPipelineDescriptor;
     /**
      *
      * @returns {boolean}
      */
     get isImageShader(): boolean;
+    /**
+     * This shader as `set` makes it — see {@link ShaderDescriptor#variant}. The same targets and depth
+     * state, the body specialized. Sets that agree on the descriptor's switches get the one shader, and
+     * the set with all of them `0` gets this one.
+     *
+     * @param {ShaderSwitchSet} set
+     * @returns {ImageShader}
+     */
+    variant(set: ShaderSwitchSet): ImageShader;
     /**
      * Note the absence of depth target, image shader is a full-screen pass, so depth is not used.
      *
@@ -55,4 +72,6 @@ export class ImageShader {
     draw({ encoder, bindings, colorAttachments, depthStencilAttachment, color_formats, viewport }: ShadeGPUCommandContext): void;
     #private;
 }
+export type RenderPipelineDescriptor = import("../../descriptor/pipeline/render/RenderPipelineDescriptor.js").RenderPipelineDescriptor;
+export type ShaderSwitchSet = import("./compiler/ShaderSwitchSet.js").ShaderSwitchSet;
 //# sourceMappingURL=ImageShader.d.ts.map

package/src/shade/renderer/shader/ImageShader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ImageShader.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/shader/ImageShader.js"],"names":[],"mappings":"AAQA;;GAEG;AACH;IAiHI;;;;;;;OAOG;IACH;QALqC,UAAU;QACR,OAAO,EAAnC,kBAAkB;QACU,YAAY;QACtC,WAAW,CAavB;IAnFD;;;;;OAKG;IACH,sEAuDC;IAxGD;;;OAGG;IACH,mCAEC;IAED;;;OAGG;IACH,cAFU,MAAM,EAAE,EAAE,CAEF;IAelB;;;OAGG;IACH,yCAEC;IAED;;;OAGG;IACH,6BAEC;IAuFD;;;;;;;;;OASG;IACH,6HA0EC;;CACJ"}
+{"version":3,"file":"ImageShader.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/shader/ImageShader.js"],"names":[],"mappings":"AAaA;;GAEG;AACH;IAiLI;;;;;;;OAOG;IACH;QALqC,UAAU;QACR,OAAO,EAAnC,kBAAkB;QACU,YAAY;QACtC,WAAW,CAavB;IA9ED;;;;OAwDC;IAxKD;;;OAGG;IACH,mCAEC;IAED;;;OAGG;IACH,cAFU,MAAM,EAAE,EAAE,CAEF;IAelB;;;OAGG;IACH,gHAEC;IAED;;;;;;;;OAQG;IACH,4BAHW,kBAAkB,GAChB,wBAAwB,CAIpC;IAED;;;OAGG;IACH,6BAEC;IAoBD;;;;;;;OAOG;IACH,aAHW,eAAe,GACb,WAAW,CA8BvB;IAkFD;;;;;;;;;OASG;IACH,6HA0EC;;CACJ;uCApSY,OAAO,8DAA8D,EAAE,wBAAwB;8BAC/F,OAAO,+BAA+B,EAAE,eAAe"}

package/src/shade/renderer/shader/ImageShader.js

@@ -4,6 +4,11 @@ import {
 } from "../../device/pipeline/rp_validate_and_rewrite_for_color_attachments.js";
 import { create_full_quad_pipeline_descriptor } from "./fullscreen/create_full_quad_pipeline_descriptor.js";
 
+/**
+ * @typedef {import("../../descriptor/pipeline/render/RenderPipelineDescriptor.js").RenderPipelineDescriptor} RenderPipelineDescriptor
+ * @typedef {import("./compiler/ShaderSwitchSet.js").ShaderSwitchSet} ShaderSwitchSet
+ */
+
 const VALIDATION_ENABLED = true;
 
 /**
@@ -50,6 +55,19 @@ export class ImageShader {
         return this.#pipeline
     }
 
+    /**
+     * The pipeline {@link draw} uses when it draws into attachments of these formats: {@link pipeline}
+     * itself when they are the formats it declares, otherwise a copy rewritten for them
+     * (rgba8unorm -> bgra8unorm, say). Offer this, not {@link pipeline}, for a pass that draws into
+     * a target it was handed — what an offer compiles is otherwise a variant no frame draws with.
+     *
+     * @param {GPUTextureFormat[]} color_formats one per fragment target
+     * @returns {RenderPipelineDescriptor}
+     */
+    pipeline_for(color_formats) {
+        return rp_validate_and_rewrite_for_color_attachments(this.#pipeline, color_formats);
+    }
+
     /**
      *
      * @returns {boolean}
@@ -64,6 +82,56 @@ export class ImageShader {
      * @param {(ColorTargetState|{clearValue?:number[]})[]} [targets]
      * @param {DepthStencilState} [depthStencil]
      */
+    /**
+     * What the constructor was given, so that {@link variant} can build its siblings the same way.
+     * @type {{targets: (ColorTargetState|{clearValue?:number[]})[], depthStencil: (DepthStencilState|undefined)}}
+     */
+    #construction;
+
+    /**
+     * This shader's variants, by every set asked for and by the descriptor each was built from.
+     * @type {Map<ShaderSwitchSet|ShaderDescriptor, ImageShader>}
+     */
+    #variants = new Map();
+
+    /**
+     * This shader as `set` makes it — see {@link ShaderDescriptor#variant}. The same targets and depth
+     * state, the body specialized. Sets that agree on the descriptor's switches get the one shader, and
+     * the set with all of them `0` gets this one.
+     *
+     * @param {ShaderSwitchSet} set
+     * @returns {ImageShader}
+     */
+    variant(set) {
+        let r = this.#variants.get(set);
+
+        if (r !== undefined) {
+            return r;
+        }
+
+        const descriptor = this.#descriptor.variant(set);
+
+        if (descriptor === this.#descriptor) {
+            r = this;
+        } else {
+            r = this.#variants.get(descriptor);
+
+            if (r === undefined) {
+                r = new ImageShader({
+                    descriptor,
+                    targets: this.#construction.targets,
+                    depthStencil: this.#construction.depthStencil,
+                });
+
+                this.#variants.set(descriptor, r);
+            }
+        }
+
+        this.#variants.set(set, r);
+
+        return r;
+    }
+
     constructor({
                     descriptor,
                     targets = [],
@@ -71,6 +139,7 @@ export class ImageShader {
                 }) {
 
         this.#descriptor = descriptor;
+        this.#construction = { targets, depthStencil };
 
         // process optional clearValue parameter
         for (let i = 0; i < targets.length; i++) {
@@ -187,7 +256,7 @@ export class ImageShader {
         if (color_formats !== undefined) {
             // potentially rewrite the pipeline to be compatible with output formats
             // example: rgba8unorm -> rgba16float
-            pipeline = rp_validate_and_rewrite_for_color_attachments(pipeline, color_formats);
+            pipeline = this.pipeline_for(color_formats);
         }
 
         const pass = encoder.constructRenderPass({

package/src/shade/renderer/shader/ShaderDescriptor.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @typedef {import("./compiler/ShaderSwitch.js").ShaderSwitch} ShaderSwitch
+ */
 export class ShaderDescriptor {
     /**
      *
@@ -32,7 +35,23 @@ export class ShaderDescriptor {
      */
     get source(): string;
     /**
+     * The switches this shader depends on: every one its body's chunk graph decides somewhere. Empty
+     * for a shader with one variant.
      *
+     * @returns {ShaderSwitch[]}
+     */
+    get switches(): import("./compiler/ShaderSwitch.js").ShaderSwitch[];
+    /**
+     * This shader as `set` makes it: the same resources, and the body specialized to the switches'
+     * values, so it holds no choice. Sets that agree on {@link switches} get the one variant, and the
+     * set with every one of them `0` gets this descriptor, whose {@link source} is that variant's.
+     *
+     * @param {ShaderSwitchSet} set values for the switches; those this shader does not depend on are ignored
+     * @returns {ShaderDescriptor}
+     */
+    variant(set: ShaderSwitchSet): ShaderDescriptor;
+    /**
+     * The source of the variant with every switch `0`; see {@link variant} for the others.
      * @return {string}
      */
     compile(): string;
@@ -50,6 +69,8 @@ export class ShaderDescriptor {
     validate_gpu_features(device: GPUDevice): boolean;
     #private;
 }
+export type ShaderSwitch = import("./compiler/ShaderSwitch.js").ShaderSwitch;
 import { ShaderResourceSetDescriptor } from "./resource/ShaderResourceSetDescriptor.js";
+import { ShaderSwitchSet } from "./compiler/ShaderSwitchSet.js";
 import { CodeChunk } from "./compiler/CodeChunk.js";
 //# sourceMappingURL=ShaderDescriptor.d.ts.map

package/src/shade/renderer/shader/ShaderDescriptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShaderDescriptor.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/shader/ShaderDescriptor.js"],"names":[],"mappings":"AAIA;IA+JI;;;;;;OAMG;IACH;QAJ4B,KAAK,GAAtB,MAAM;QACgC,SAAS,GAA/C,2BAA2B;QACR,IAAI,EAAvB,SAAS;yBAsBnB;IAnLD;;;OAGG;IACH,oBAEC;IAOD;;;OAGG;IACH,6CAEC;IAaD;;;OAGG;IACH,0CAEC;IAQD;;;OAGG;IACH,qBAQC;IAED;;;OAGG;IACH,WAFY,MAAM,CAiCjB;IAED;;;OAGG;IACH,iDA6BC;IAED;;;;;OAKG;IACH,0CAHa,OAAO,CAenB;;CA8BJ;4CA7L2C,2CAA2C;0BAD7D,yBAAyB"}
+{"version":3,"file":"ShaderDescriptor.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/shader/ShaderDescriptor.js"],"names":[],"mappings":"AAKA;;GAEG;AAEH;IA+NI;;;;;;OAMG;IACH;QAJ4B,KAAK,GAAtB,MAAM;QACgC,SAAS,GAA/C,2BAA2B;QACR,IAAI,EAAvB,SAAS;yBAuBnB;IApPD;;;OAGG;IACH,oBAEC;IAOD;;;OAGG;IACH,6CAEC;IAaD;;;OAGG;IACH,0CAEC;IAQD;;;OAGG;IACH,qBAQC;IAOD;;;;;OAKG;IACH,oEAMC;IASD;;;;;;;OAOG;IACH,aAHW,eAAe,GACb,gBAAgB,CA8B5B;IAED;;;OAGG;IACH,WAFY,MAAM,CAiCjB;IAED;;;OAGG;IACH,iDA6BC;IAED;;;;;OAKG;IACH,0CAHa,OAAO,CAenB;;CA+BJ;2BA/PY,OAAO,4BAA4B,EAAE,YAAY;4CAHlB,2CAA2C;gCADvD,+BAA+B;0BADrC,yBAAyB"}

package/src/shade/renderer/shader/ShaderDescriptor.js

@@ -1,7 +1,12 @@
 import { assert } from "../../../core/assert.js";
 import { CodeChunk } from "./compiler/CodeChunk.js";
+import { ShaderSwitchSet } from "./compiler/ShaderSwitchSet.js";
 import { ShaderResourceSetDescriptor } from "./resource/ShaderResourceSetDescriptor.js";
 
+/**
+ * @typedef {import("./compiler/ShaderSwitch.js").ShaderSwitch} ShaderSwitch
+ */
+
 export class ShaderDescriptor {
     /**
      * Human-readable label
@@ -70,12 +75,76 @@ export class ShaderDescriptor {
     }
 
     /**
+     * @type {ShaderSwitch[]|undefined}
+     */
+    #switches = undefined;
+
+    /**
+     * The switches this shader depends on: every one its body's chunk graph decides somewhere. Empty
+     * for a shader with one variant.
      *
+     * @returns {ShaderSwitch[]}
+     */
+    get switches() {
+        if (this.#switches === undefined) {
+            this.#switches = Object.freeze(this.#body.collectSwitches());
+        }
+
+        return this.#switches;
+    }
+
+    /**
+     * Variants made so far, by every set asked for. Sets are interned, so a frame asking again with
+     * the same one finds its variant with one lookup and allocates nothing.
+     * @type {Map<ShaderSwitchSet, ShaderDescriptor>}
+     */
+    #variants = new Map();
+
+    /**
+     * This shader as `set` makes it: the same resources, and the body specialized to the switches'
+     * values, so it holds no choice. Sets that agree on {@link switches} get the one variant, and the
+     * set with every one of them `0` gets this descriptor, whose {@link source} is that variant's.
+     *
+     * @param {ShaderSwitchSet} set values for the switches; those this shader does not depend on are ignored
+     * @returns {ShaderDescriptor}
+     */
+    variant(set) {
+        let r = this.#variants.get(set);
+
+        if (r !== undefined) {
+            return r;
+        }
+
+        const own = set.restricted_to(this.switches);
+
+        if (own === ShaderSwitchSet.EMPTY) {
+            r = this;
+        } else {
+            r = this.#variants.get(own);
+
+            if (r === undefined) {
+                r = ShaderDescriptor.from({
+                    label: `${this.#label} [${own}]`,
+                    resources: this.#resources,
+                    body: this.#body.specialize(own),
+                });
+
+                this.#variants.set(own, r);
+            }
+        }
+
+        this.#variants.set(set, r);
+
+        return r;
+    }
+
+    /**
+     * The source of the variant with every switch `0`; see {@link variant} for the others.
      * @return {string}
      */
     compile() {
 
-        const chunk = this.#body.clone();
+        const chunk = this.#body.specialize(ShaderSwitchSet.EMPTY).clone();
         chunk.addDependency(this.#resources.generateCodeChunk())
 
         const compiled = chunk.compile();
@@ -178,6 +247,7 @@ export class ShaderDescriptor {
 
         assert.defined(body, 'body');
         assert.equal(body.isCodeChunk, true, 'body.isCodeChunk !== true');
+        assert.notEqual(body.isCodeChunkChoice, true, 'body is a CodeChunkChoice; make it a dependency of the body instead');
 
         assert.isString(label, 'label');
 

package/src/shade/renderer/shader/chunk/camera/chunk_project_view_position_from_depth.d.ts

@@ -0,0 +1,17 @@
+/**
+ * View-space position of a depth-buffer texel: {@link chunk_project_position_from_depth} with the camera's
+ * `projection_matrix_inverse`, at a quarter of the multiply-adds.
+ *
+ * The inverse of a perspective projection maps NDC x only to view x, NDC y only to view y, and depth only to
+ * z and w. The other eight entries are zero, so this reads the eight that are not, and the TAA jitter, which
+ * the projection carries as an off-axis shift, is in two of them. An orthographic projection's inverse has
+ * the same shape, its jitter in the translation column, so this covers both.
+ *
+ * Why it exists: a screen-space march reconstructs every sample it fetches, and a full mat4 multiply per
+ * sample is what that costs otherwise. See `fragment_shader_gtao.js` for the measurement.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_project_view_position_from_depth: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_project_view_position_from_depth.d.ts.map

package/src/shade/renderer/shader/chunk/camera/chunk_project_view_position_from_depth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_project_view_position_from_depth.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/camera/chunk_project_view_position_from_depth.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AACH,qDAFU,SAAS,CA6BjB;0BA5CwB,6BAA6B"}

package/src/shade/renderer/shader/chunk/camera/chunk_project_view_position_from_depth.js

@@ -0,0 +1,45 @@
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+import { chunk_uv_to_ndc } from "../texture/chunk_uv_to_ndc.js";
+
+/**
+ * View-space position of a depth-buffer texel: {@link chunk_project_position_from_depth} with the camera's
+ * `projection_matrix_inverse`, at a quarter of the multiply-adds.
+ *
+ * The inverse of a perspective projection maps NDC x only to view x, NDC y only to view y, and depth only to
+ * z and w. The other eight entries are zero, so this reads the eight that are not, and the TAA jitter, which
+ * the projection carries as an off-axis shift, is in two of them. An orthographic projection's inverse has
+ * the same shape, its jitter in the translation column, so this covers both.
+ *
+ * Why it exists: a screen-space march reconstructs every sample it fetches, and a full mat4 multiply per
+ * sample is what that costs otherwise. See `fragment_shader_gtao.js` for the measurement.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_project_view_position_from_depth = CodeChunk.from(
+    //language=WGSL
+    `
+fn project_view_position_from_depth(
+    uv: vec2<f32>,
+    ndc_depth: f32,
+    projection_inverse: mat4x4<f32>
+) -> vec3<f32> {
+
+    let ndc = uv_to_ndc(uv);
+
+    let m = projection_inverse;
+
+    let projected = vec4<f32>(
+        fma(ndc.x, m[0][0], m[3][0]),
+        fma(ndc.y, m[1][1], m[3][1]),
+        fma(ndc_depth, m[2][2], m[3][2]),
+        fma(ndc_depth, m[2][3], m[3][3]),
+    );
+
+    // undo projection
+    return projected.xyz / projected.w;
+}
+`,
+    [
+        chunk_uv_to_ndc
+    ]
+);

package/src/shade/renderer/shader/chunk/camera/chunk_screen_coordinate_to_view.js

@@ -1,7 +1,7 @@
 import { CAMERA_UNIFORM_STRUCT } from "../../../camera/CAMERA_UNIFORM_STRUCT.js";
 import { CodeChunk } from "../../compiler/CodeChunk.js";
 import { chunk_texel_coordinate_to_uv } from "../texture/chunk_texel_coordinate_to_uv.js";
-import { chunk_project_position_from_depth } from "./chunk_project_position_from_depth.js";
+import { chunk_project_view_position_from_depth } from "./chunk_project_view_position_from_depth.js";
 
 export const chunk_screen_coordinate_to_view = CodeChunk.from(
     //language=WGSL
@@ -20,13 +20,13 @@ fn screen_coordinate_to_view(
     
     let uv = texel_coordinate_to_uv(vec2f(coord), textureDimensions(tDepth).xy);
     
-    let position_vs = project_position_from_depth(uv, texel_depth, camera.projection_matrix_inverse );
+    let position_vs = project_view_position_from_depth(uv, texel_depth, camera.projection_matrix_inverse );
            
     return position_vs;
 }
     `, [
         chunk_texel_coordinate_to_uv,
         CAMERA_UNIFORM_STRUCT.declaration_chunk,
-        chunk_project_position_from_depth,
+        chunk_project_view_position_from_depth,
     ]
 );

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;
+}
+    `
 )