@woosh/meep-engine 3.63.3 → 3.64.1

package/src/shade/renderer/deferred/tonemap/ToneMapOperator.js

@@ -0,0 +1,63 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * @typedef {import("../../shader/compiler/CodeChunk.js").CodeChunk} CodeChunk
+ * @typedef {import("../../shader/resource/ShaderResourceGroupDescriptor.js").ShaderResourceGroupDescriptor} ShaderResourceGroupDescriptor
+ * @typedef {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ */
+
+/**
+ * A tone-mapping function, in WGSL, that {@link ToneMapper} bakes into its LUTs.
+ *
+ * {@link chunk} defines
+ *
+ *     fn tone_map_operator(scene: vec3<f32>, peak_nits: f32) -> vec3<f32>
+ *
+ * - `scene`: exposed linear Rec.709, 1 at the paper white. Not negative; the LUT's encoding clamps at zero.
+ * - `peak_nits`: the display's peak in cd/m². An SDR display is `PAPER_WHITE_NITS`.
+ * - returns linear Rec.2020 display light, 1 at the paper white (`PAPER_WHITE_NITS`).
+ *
+ * An operator whose chunk reads bindings of its own adds them in {@link declare} and supplies them in {@link bind}.
+ * The chunk is linked once into its bake shader, so its text must not change after first use.
+ */
+export class ToneMapOperator {
+    /**
+     * @param {string} label
+     * @param {CodeChunk} chunk defines `tone_map_operator`, see the class
+     */
+    constructor(label, chunk) {
+        assert.isString(label, 'label');
+        assert.defined(chunk, 'chunk');
+        assert.equal(chunk.isCodeChunk, true, 'chunk.isCodeChunk !== true');
+
+        /**
+         * @readonly
+         * @type {string}
+         */
+        this.label = label;
+
+        /**
+         * @readonly
+         * @type {CodeChunk}
+         */
+        this.chunk = chunk;
+    }
+
+    /**
+     * Add the bindings {@link chunk} reads to the bake shader's group. None by default.
+     *
+     * @param {ShaderResourceGroupDescriptor} group
+     */
+    declare(group) {
+    }
+
+    /**
+     * Supply the bindings {@link declare} added, for a bake at `peak_nits`. None by default.
+     *
+     * @param {FrameGraph} graph the frame the bake is recorded into
+     * @param {number} peak_nits
+     * @param {Object} bindings the bake pass's bindings, to add to by name
+     */
+    bind(graph, peak_nits, bindings) {
+    }
+}

package/src/shade/renderer/deferred/tonemap/ToneMapper.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Turns the exposed scene colour into the canvas's colour, through a 3D LUT for each output.
+ *
+ * Each LUT maps exposed scene-linear Rec.709 to linear Rec.2020 display light, both as PQ (ST 2084) signals with 1 at
+ * the paper white, `PAPER_WHITE_NITS`; see `chunk_tonemap_lut`. Texel i of a LUT of N³ holds the scene signal
+ * i / (N - 1) along each axis, red fastest. Scene colour past 10000 cd/m², 49.3 × the paper white, reads the last
+ * texel. The apply passes take the LUT's output to the canvas's primaries and transfer curve.
+ *
+ * A LUT comes from {@link grade} and {@link operator}, baked at {@link lut_resolution} and baked again when any of them
+ * changes or, for the HDR LUT, when the display's peak does; or from the user, by {@link set_lut_sdr} and
+ * {@link set_lut_hdr}, which takes the place of the bake for that output until cleared. A user's LUT is not graded.
+ */
+export class ToneMapper {
+    /**
+     * @param {GPUDevice} device
+     */
+    constructor(device: GPUDevice);
+    /**
+     * The tone-mapping function the LUTs are baked from. Unreal's default look unless set. Read every frame.
+     * @type {ToneMapOperator}
+     */
+    operator: ToneMapOperator;
+    /**
+     * Texels along each edge of a baked LUT. At least 2, and at most the device's `maxTextureDimension3D`. Read every
+     * frame.
+     * @type {number}
+     */
+    lut_resolution: number;
+    /**
+     * The colour grade ahead of {@link operator}, neutral unless changed. Read every frame; a change bakes again.
+     * @readonly
+     * @type {ColorGrade}
+     */
+    readonly grade: ColorGrade;
+    /**
+     * The canvas's primaries and the display's peak, which the Renderer writes.
+     * @readonly
+     * @type {TonemapDisplaySettings}
+     */
+    readonly display: TonemapDisplaySettings;
+    /**
+     * Supply the SDR LUT, in place of the one baked from {@link operator}.
+     *
+     * @param {number} resolution texels along each edge
+     * @param {Float32Array} data resolution³ RGB triples, red fastest, as the class describes
+     */
+    set_lut_sdr(resolution: number, data: Float32Array): void;
+    /**
+     * Supply the HDR LUT, in place of the one baked from {@link operator}. It shows as graded: a display under
+     * `peak_nits` clips what it cannot reach.
+     *
+     * @param {number} resolution texels along each edge
+     * @param {Float32Array} data resolution³ RGB triples, red fastest, as the class describes
+     * @param {number} peak_nits the peak the LUT was graded for, cd/m²
+     */
+    set_lut_hdr(resolution: number, data: Float32Array, peak_nits: number): void;
+    /**
+     * Go back to the SDR LUT baked from {@link operator}.
+     */
+    clear_lut_sdr(): void;
+    /**
+     * Go back to the HDR LUT baked from {@link operator}.
+     */
+    clear_lut_hdr(): void;
+    /**
+     * Make the SDR LUT from the HDR LUT supplied by {@link set_lut_hdr}, at its resolution: each texel through the
+     * BT.2390 EETF from the HDR LUT's graded peak down to the paper white, which keeps the hue and never passes SDR
+     * white. Built on the GPU in the next {@link render}, from the HDR LUT as it is then. Stays until
+     * {@link set_lut_sdr} or {@link clear_lut_sdr}.
+     */
+    build_lut_sdr_from_hdr(): void;
+    /**
+     * Offer the pipelines the next frame on this output needs.
+     *
+     * @param {PipelineEnquiry} enquiry
+     * @param {boolean} hdr
+     * @param {GPUTextureFormat} format the canvas's
+     */
+    enquire_pipelines(enquiry: PipelineEnquiry, hdr: boolean, format: GPUTextureFormat): void;
+    /**
+     * Record the tone mapping of a frame: any LUT work it needs first, then the pass writing `target`.
+     *
+     * @param {Object} options
+     * @param {FrameGraph} options.graph
+     * @param {number} options.input_color the scene colour, linear Rec.709
+     * @param {number} options.exposure the exposure multiplier, a uniform
+     * @param {boolean} options.hdr whether the output is HDR
+     * @param {number} options.target the texture to write
+     * @returns {number} `target`, written
+     */
+    render({ graph, input_color, exposure, hdr, target }: {
+        graph: FrameGraph;
+        input_color: number;
+        exposure: number;
+        hdr: boolean;
+        target: number;
+    }): number;
+    destroy(): void;
+    #private;
+}
+export type ToneMapOperator = import("./ToneMapOperator.js").ToneMapOperator;
+export type PipelineEnquiry = import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry;
+export type FrameGraph = import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+import { ColorGrade } from "./ColorGrade.js";
+import { TonemapDisplaySettings } from "./TonemapDisplaySettings.js";
+//# sourceMappingURL=ToneMapper.d.ts.map

package/src/shade/renderer/deferred/tonemap/ToneMapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToneMapper.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/deferred/tonemap/ToneMapper.js"],"names":[],"mappings":"AA6FA;;;;;;;;;;;GAWG;AACH;IAmEI;;OAEG;IACH,+BAMC;IA3ED;;;OAGG;IACH,UAFU,eAAe,CAES;IAElC;;;;OAIG;IACH,gBAFU,MAAM,CAEI;IAEpB;;;;OAIG;IACH,gBAFU,UAAU,CAEK;IAEzB;;;;OAIG;IACH,kBAFU,sBAAsB,CAEO;IAoDvC;;;;;OAKG;IACH,wBAHW,MAAM,QACN,YAAY,QAKtB;IAED;;;;;;;OAOG;IACH,wBAJW,MAAM,QACN,YAAY,aACZ,MAAM,QAQhB;IAED;;OAEG;IACH,sBAIC;IAED;;OAEG;IACH,sBAGC;IAED;;;;;OAKG;IACH,+BASC;IAED;;;;;;OAMG;IACH,2BAJW,eAAe,OACf,OAAO,kCAMjB;IAED;;;;;;;;;;OAUG;IACH;QAP+B,KAAK,EAAzB,UAAU;QACM,WAAW,EAA3B,MAAM;QACU,QAAQ,EAAxB,MAAM;QACW,GAAG,EAApB,OAAO;QACS,MAAM,EAAtB,MAAM;QACJ,MAAM,CAyElB;IAED,gBAGC;;CAkIJ;8BAzcY,OAAO,sBAAsB,EAAE,eAAe;8BAC9C,OAAO,6CAA6C,EAAE,eAAe;yBACrE,OAAO,8DAA8D,EAAE,UAAU;2BAXxC,iBAAiB;uCAMhC,6BAA6B"}

package/src/shade/renderer/deferred/tonemap/ToneMapper.js

@@ -0,0 +1,474 @@
+import { assert } from "../../../../core/assert.js";
+import { PAPER_WHITE_NITS } from "../../shader/chunk/color/tonemap/chunk_PAPER_WHITE_NITS.js";
+import { graph_compute_pass } from "../../shader/graph/compute/graph_compute_pass.js";
+import { graph_image_pass } from "../../shader/graph/graph_image_pass.js";
+import { graph_import_raw_buffer } from "../../shader/graph/graph_import_raw_buffer.js";
+import { graph_import_texture } from "../../shader/graph/graph_import_texture.js";
+import { GPUTextureContext } from "../../texture/GPUTextureContext.js";
+import { COLOR_GRADE_HEADER_FLOATS, ColorGrade } from "./ColorGrade.js";
+import { shader_tonemap_HDR_lut } from "./shader_tonemap_HDR_lut.js";
+import { shader_tonemap_LDR_lut } from "./shader_tonemap_LDR_lut.js";
+import { shader_tonemap_lut_bake, TONEMAP_LUT_BAKE_GROUP } from "./shader_tonemap_lut_bake.js";
+import { shader_tonemap_lut_sdr_from_hdr } from "./shader_tonemap_lut_sdr_from_hdr.js";
+import { TONE_MAP_OPERATOR_ACES } from "./TONE_MAP_OPERATOR_ACES.js";
+import { TonemapDisplaySettings } from "./TonemapDisplaySettings.js";
+
+/**
+ * @typedef {import("./ToneMapOperator.js").ToneMapOperator} ToneMapOperator
+ * @typedef {import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
+ * @typedef {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ */
+
+/**
+ * The pass that writes the canvas, for an SDR or an HDR output.
+ *
+ * @param {boolean} hdr
+ */
+function apply_shader(hdr) {
+    return hdr ? shader_tonemap_HDR_lut : shader_tonemap_LDR_lut;
+}
+
+/**
+ * One LUT the tone mapper draws with, and what it holds.
+ */
+class ToneMapLut {
+    /**
+     * @param {GPUDevice} device
+     * @param {string} label
+     */
+    constructor(device, label) {
+        /**
+         * @readonly
+         * @type {GPUTextureContext}
+         */
+        this.texture = new GPUTextureContext(device);
+        this.texture.descriptor.label = label;
+        this.texture.descriptor.dimension = "3d";
+        this.texture.descriptor.format = "rgba16float";
+        this.texture.descriptor.usage = GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.STORAGE_BINDING
+            | GPUTextureUsage.COPY_DST | GPUTextureUsage.COPY_SRC;
+
+        /**
+         * Whether the user supplied this LUT, rather than the tone mapper baking it from its operator.
+         * @type {boolean}
+         */
+        this.user = false;
+
+        /**
+         * The operator, resolution and peak this LUT was baked for; `null` operator when it holds no bake.
+         * @type {ToneMapOperator|null}
+         */
+        this.baked_operator = null;
+        this.baked_resolution = 0;
+        this.baked_peak_nits = NaN;
+
+        /**
+         * The packed grade this LUT was baked with, its bits compared with the grade's each frame.
+         * @type {Uint32Array}
+         */
+        this.baked_grade = new Uint32Array(0);
+    }
+}
+
+/**
+ * @param {Uint32Array} a
+ * @param {Uint32Array} b
+ * @returns {boolean} whether the two hold the same bits
+ */
+function same_words(a, b) {
+    const length = a.length;
+
+    if (length !== b.length) {
+        return false;
+    }
+
+    for (let i = 0; i < length; i++) {
+        if (a[i] !== b[i]) {
+            return false;
+        }
+    }
+
+    return true;
+}
+
+/**
+ * Turns the exposed scene colour into the canvas's colour, through a 3D LUT for each output.
+ *
+ * Each LUT maps exposed scene-linear Rec.709 to linear Rec.2020 display light, both as PQ (ST 2084) signals with 1 at
+ * the paper white, `PAPER_WHITE_NITS`; see `chunk_tonemap_lut`. Texel i of a LUT of N³ holds the scene signal
+ * i / (N - 1) along each axis, red fastest. Scene colour past 10000 cd/m², 49.3 × the paper white, reads the last
+ * texel. The apply passes take the LUT's output to the canvas's primaries and transfer curve.
+ *
+ * A LUT comes from {@link grade} and {@link operator}, baked at {@link lut_resolution} and baked again when any of them
+ * changes or, for the HDR LUT, when the display's peak does; or from the user, by {@link set_lut_sdr} and
+ * {@link set_lut_hdr}, which takes the place of the bake for that output until cleared. A user's LUT is not graded.
+ */
+export class ToneMapper {
+    /**
+     * The tone-mapping function the LUTs are baked from. Unreal's default look unless set. Read every frame.
+     * @type {ToneMapOperator}
+     */
+    operator = TONE_MAP_OPERATOR_ACES;
+
+    /**
+     * Texels along each edge of a baked LUT. At least 2, and at most the device's `maxTextureDimension3D`. Read every
+     * frame.
+     * @type {number}
+     */
+    lut_resolution = 32;
+
+    /**
+     * The colour grade ahead of {@link operator}, neutral unless changed. Read every frame; a change bakes again.
+     * @readonly
+     * @type {ColorGrade}
+     */
+    grade = new ColorGrade();
+
+    /**
+     * The canvas's primaries and the display's peak, which the Renderer writes.
+     * @readonly
+     * @type {TonemapDisplaySettings}
+     */
+    display = new TonemapDisplaySettings();
+
+    /**
+     * @type {GPUDevice}
+     */
+    #device;
+
+    /**
+     * @type {ToneMapLut}
+     */
+    #sdr;
+
+    /**
+     * @type {ToneMapLut}
+     */
+    #hdr;
+
+    /**
+     * The peak the user's HDR LUT was graded for, cd/m².
+     * @type {number}
+     */
+    #hdr_graded_peak_nits = NaN;
+
+    /**
+     * Whether the next {@link render} builds the SDR LUT from the HDR one.
+     * @type {boolean}
+     */
+    #sdr_from_hdr_pending = false;
+
+    /**
+     * {@link grade} as this frame packed it.
+     * @type {Float32Array}
+     */
+    #grade_data = new Float32Array(0);
+
+    /**
+     * {@link #grade_data}'s words.
+     * @type {Uint32Array}
+     */
+    #grade_words = new Uint32Array(0);
+
+    /**
+     * @param {GPUDevice} device
+     */
+    constructor(device) {
+        assert.defined(device, 'device');
+
+        this.#device = device;
+        this.#sdr = new ToneMapLut(device, "Tonemap / SDR LUT");
+        this.#hdr = new ToneMapLut(device, "Tonemap / HDR LUT");
+    }
+
+    /**
+     * Supply the SDR LUT, in place of the one baked from {@link operator}.
+     *
+     * @param {number} resolution texels along each edge
+     * @param {Float32Array} data resolution³ RGB triples, red fastest, as the class describes
+     */
+    set_lut_sdr(resolution, data) {
+        this.#upload(this.#sdr, resolution, data);
+        this.#sdr_from_hdr_pending = false;
+    }
+
+    /**
+     * Supply the HDR LUT, in place of the one baked from {@link operator}. It shows as graded: a display under
+     * `peak_nits` clips what it cannot reach.
+     *
+     * @param {number} resolution texels along each edge
+     * @param {Float32Array} data resolution³ RGB triples, red fastest, as the class describes
+     * @param {number} peak_nits the peak the LUT was graded for, cd/m²
+     */
+    set_lut_hdr(resolution, data, peak_nits) {
+        assert.isNumber(peak_nits, 'peak_nits');
+        assert.greaterThan(peak_nits, 0, 'peak_nits');
+
+        this.#upload(this.#hdr, resolution, data);
+        this.#hdr_graded_peak_nits = peak_nits;
+    }
+
+    /**
+     * Go back to the SDR LUT baked from {@link operator}.
+     */
+    clear_lut_sdr() {
+        this.#sdr.user = false;
+        this.#sdr.baked_operator = null;
+        this.#sdr_from_hdr_pending = false;
+    }
+
+    /**
+     * Go back to the HDR LUT baked from {@link operator}.
+     */
+    clear_lut_hdr() {
+        this.#hdr.user = false;
+        this.#hdr.baked_operator = null;
+    }
+
+    /**
+     * Make the SDR LUT from the HDR LUT supplied by {@link set_lut_hdr}, at its resolution: each texel through the
+     * BT.2390 EETF from the HDR LUT's graded peak down to the paper white, which keeps the hue and never passes SDR
+     * white. Built on the GPU in the next {@link render}, from the HDR LUT as it is then. Stays until
+     * {@link set_lut_sdr} or {@link clear_lut_sdr}.
+     */
+    build_lut_sdr_from_hdr() {
+        assert.equal(this.#hdr.user, true, 'build_lut_sdr_from_hdr needs an HDR LUT from set_lut_hdr');
+
+        const resolution = this.#hdr.texture.width;
+
+        this.#sdr.texture.resize(resolution, resolution, resolution);
+        this.#sdr.user = true;
+        this.#sdr.baked_operator = null;
+        this.#sdr_from_hdr_pending = true;
+    }
+
+    /**
+     * Offer the pipelines the next frame on this output needs.
+     *
+     * @param {PipelineEnquiry} enquiry
+     * @param {boolean} hdr
+     * @param {GPUTextureFormat} format the canvas's
+     */
+    enquire_pipelines(enquiry, hdr, format) {
+        enquiry.render.push(apply_shader(hdr).pipeline_for([format]));
+        enquiry.compute.push(shader_tonemap_lut_bake(this.operator).pipeline);
+    }
+
+    /**
+     * Record the tone mapping of a frame: any LUT work it needs first, then the pass writing `target`.
+     *
+     * @param {Object} options
+     * @param {FrameGraph} options.graph
+     * @param {number} options.input_color the scene colour, linear Rec.709
+     * @param {number} options.exposure the exposure multiplier, a uniform
+     * @param {boolean} options.hdr whether the output is HDR
+     * @param {number} options.target the texture to write
+     * @returns {number} `target`, written
+     */
+    render({ graph, input_color, exposure, hdr, target }) {
+        assert.isBoolean(hdr, 'hdr');
+
+        const lut = hdr ? this.#hdr : this.#sdr;
+        const peak_nits = hdr ? this.display.peak_nits : PAPER_WHITE_NITS;
+
+        let bake = false;
+
+        if (!lut.user) {
+            this.#pack_grade();
+            bake = this.#bake_is_stale(lut, peak_nits);
+        }
+
+        if (bake) {
+            // sized before it is imported, so the import describes the texture the bake writes
+            const resolution = this.lut_resolution;
+
+            this.#check_resolution(resolution);
+            lut.texture.resize(resolution, resolution, resolution);
+        }
+
+        const pending = this.#sdr_from_hdr_pending;
+
+        let gr_hdr = -1;
+        let gr_sdr = -1;
+
+        if (hdr || pending) {
+            gr_hdr = graph_import_texture(graph, this.#hdr.texture, "tonemap/HDR LUT");
+        }
+
+        if (!hdr || pending) {
+            gr_sdr = graph_import_texture(graph, this.#sdr.texture, "tonemap/SDR LUT");
+        }
+
+        if (pending) {
+            // a pass writing an imported texture never culls, so this runs whichever output draws
+            const groups = Math.ceil(this.#sdr.texture.width / TONEMAP_LUT_BAKE_GROUP);
+
+            gr_sdr = graph_compute_pass({
+                graph,
+                shader: shader_tonemap_lut_sdr_from_hdr,
+                bindings: {
+                    settings: { source_peak_nits: this.#hdr_graded_peak_nits },
+                    hdr_lut: gr_hdr,
+                    sdr_lut: gr_sdr,
+                },
+                group_count: [groups, groups, groups],
+            }).sdr_lut;
+
+            this.#sdr_from_hdr_pending = false;
+        }
+
+        let gr_lut = hdr ? gr_hdr : gr_sdr;
+
+        if (bake) {
+            gr_lut = this.#bake(graph, lut, peak_nits, gr_lut);
+        }
+
+        const [written] = graph_image_pass({
+            graph,
+            shader: apply_shader(hdr),
+            inputs: {
+                input_color,
+                exposure,
+                settings: this.display,
+                lut: gr_lut,
+            },
+            output: [target]
+        });
+
+        return written;
+    }
+
+    destroy() {
+        this.#sdr.texture.destroy();
+        this.#hdr.texture.destroy();
+    }
+
+    /**
+     * @param {ToneMapLut} lut
+     * @param {number} peak_nits
+     * @returns {boolean}
+     */
+    #bake_is_stale(lut, peak_nits) {
+        return lut.baked_operator !== this.operator
+            || lut.baked_resolution !== this.lut_resolution
+            || lut.baked_peak_nits !== peak_nits
+            || !same_words(lut.baked_grade, this.#grade_words);
+    }
+
+    #pack_grade() {
+        const data = this.grade.pack();
+
+        if (data !== this.#grade_data) {
+            this.#grade_data = data;
+            this.#grade_words = new Uint32Array(data.buffer, data.byteOffset, data.length);
+        }
+    }
+
+    /**
+     * @param {FrameGraph} graph
+     * @param {ToneMapLut} lut
+     * @param {number} peak_nits
+     * @param {number} gr_lut the LUT's texture, sized for {@link lut_resolution} and imported into `graph`
+     * @returns {number} the LUT, written
+     */
+    #bake(graph, lut, peak_nits, gr_lut) {
+        const operator = this.operator;
+        const resolution = this.lut_resolution;
+
+        const grade = this.#grade_data;
+        const header_bytes = COLOR_GRADE_HEADER_FLOATS * 4;
+
+        const bindings = {
+            settings: { peak_nits },
+            lut: gr_lut,
+            grade: graph_import_raw_buffer({
+                graph,
+                value: grade.buffer,
+                offset: grade.byteOffset,
+                size: header_bytes,
+                label: "tonemap/grade",
+                usage: GPUBufferUsage.UNIFORM,
+            }),
+            grade_keys: graph_import_raw_buffer({
+                graph,
+                value: grade.buffer,
+                offset: grade.byteOffset + header_bytes,
+                size: grade.byteLength - header_bytes,
+                label: "tonemap/grade keys",
+                usage: GPUBufferUsage.STORAGE,
+            }),
+        };
+
+        operator.bind(graph, peak_nits, bindings);
+
+        const groups = Math.ceil(resolution / TONEMAP_LUT_BAKE_GROUP);
+
+        const written = graph_compute_pass({
+            graph,
+            shader: shader_tonemap_lut_bake(operator),
+            bindings,
+            group_count: [groups, groups, groups],
+        }).lut;
+
+        lut.baked_operator = operator;
+        lut.baked_resolution = resolution;
+        lut.baked_peak_nits = peak_nits;
+
+        if (lut.baked_grade.length !== this.#grade_words.length) {
+            lut.baked_grade = new Uint32Array(this.#grade_words.length);
+        }
+
+        lut.baked_grade.set(this.#grade_words);
+
+        return written;
+    }
+
+    /**
+     * @param {ToneMapLut} lut
+     * @param {number} resolution
+     * @param {Float32Array} data
+     */
+    #upload(lut, resolution, data) {
+        this.#check_resolution(resolution);
+        assert.isInstanceOf(data, Float32Array, 'data');
+        assert.equal(data.length, resolution * resolution * resolution * 3, 'data.length !== resolution³ × 3');
+
+        const texel_count = resolution * resolution * resolution;
+        const texels = new Float16Array(texel_count * 4);
+
+        for (let i = 0; i < texel_count; i++) {
+            texels[i * 4] = data[i * 3];
+            texels[i * 4 + 1] = data[i * 3 + 1];
+            texels[i * 4 + 2] = data[i * 3 + 2];
+            texels[i * 4 + 3] = 1;
+        }
+
+        const texture = lut.texture;
+
+        texture.resize(resolution, resolution, resolution);
+
+        this.#device.queue.writeTexture(
+            { texture: texture.gpu_texture },
+            texels,
+            { bytesPerRow: resolution * 8, rowsPerImage: resolution },
+            [resolution, resolution, resolution]
+        );
+
+        lut.user = true;
+        lut.baked_operator = null;
+    }
+
+    /**
+     * @param {number} resolution
+     */
+    #check_resolution(resolution) {
+        assert.isNonNegativeInteger(resolution, 'resolution');
+        assert.greaterThanOrEqual(resolution, 2, 'resolution');
+
+        const limit = this.#device.limits.maxTextureDimension3D;
+
+        if (resolution > limit) {
+            throw new Error(`A tone-mapping LUT of ${resolution}³ exceeds the device's maxTextureDimension3D, ${limit}`);
+        }
+    }
+}

package/src/shade/renderer/deferred/tonemap/TonemapAces2Tables.d.ts

@@ -1,16 +1,16 @@
 /**
- * What {@link shader_tonemap_HDR_aces} binds as `aces2_tables`: two ACES 2.0 output transforms, each its parameters and
+ * What the ACES tone-map operator binds as `aces2_tables`: two ACES 2.0 output transforms, each its parameters and
  * gamut tables, both limited to Rec.709, the gamut of the SDR picture they expand.
  *
- * 1. An SDR display, 100 cd/m². The pass runs it backwards, from the SDR picture to the scene.
+ * 1. An SDR display, 100 cd/m². The operator runs it backwards, from the SDR picture to the scene.
  * 2. This display: the peak over the paper white, times 100 cd/m². A display at or under the paper white gets
- *    100 cd/m², which the pass does not read.
+ *    100 cd/m², which the operator does not read.
  *
  * Both take SDR white for 100 cd/m², ACES 2.0's reference, so an SDR picture expanded for a display keeps SDR white
  * where the paper white puts it.
  *
- * Building one transform takes 7 to 13 ms, so the tables are built on the first {@link update} rather than with the
- * renderer, and again only when the display's peak changes.
+ * Building one transform takes 7 to 13 ms, so the tables are built on the first {@link update}, and again only when
+ * the display's peak changes.
  */
 export class TonemapAces2Tables {
     /**
@@ -25,14 +25,6 @@ export class TonemapAces2Tables {
      * @returns {boolean} whether {@link data} changed
      */
     update(peak_nits: number): boolean;
-    /**
-     * The tables on the device, written if they changed since the last call.
-     *
-     * @param {GPUDevice} device
-     * @returns {GPUBuffer}
-     */
-    gpu_buffer(device: GPUDevice): GPUBuffer;
-    destroy(): void;
     #private;
 }
 //# sourceMappingURL=TonemapAces2Tables.d.ts.map

package/src/shade/renderer/deferred/tonemap/TonemapAces2Tables.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TonemapAces2Tables.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/deferred/tonemap/TonemapAces2Tables.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;GAaG;AACH;IACI;;;OAGG;IACH,MAFU,YAAY,CAE0B;IAWhD;;;;;OAKG;IACH,kBAHW,MAAM,GACJ,OAAO,CAsBnB;IAED;;;;;OAKG;IACH,yCAgBC;IAED,gBAKC;;CACJ"}
+{"version":3,"file":"TonemapAces2Tables.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/deferred/tonemap/TonemapAces2Tables.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;GAaG;AACH;IACI;;;OAGG;IACH,MAFU,YAAY,CAE0B;IAIhD;;;;;OAKG;IACH,kBAHW,MAAM,GACJ,OAAO,CAqBnB;;CACJ"}