@woosh/meep-engine 3.63.2 → 3.64.0

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

@@ -0,0 +1,25 @@
+import { chunk_CRM_FROM_REC709_TO_REC2020 } from "../../shader/chunk/color/conversion/chunk_CRM_FROM_REC709_TO_REC2020.js";
+import { chunk_PAPER_WHITE_NITS } from "../../shader/chunk/color/tonemap/chunk_PAPER_WHITE_NITS.js";
+import { chunk_tonemap_gt7 } from "../../shader/chunk/color/tonemap/gt7/chunk_tonemap_gt7.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ToneMapOperator } from "./ToneMapOperator.js";
+
+/**
+ * GT7 tone mapping (Polyphony Digital, SIGGRAPH 2025), in its own Rec.2020. An exposed 1.0 shows at the paper white
+ * on every display. On SDR the peak is the paper white, the curve's SDR mode, which clips there; HDR rolls off to the
+ * display's peak.
+ *
+ * @type {ToneMapOperator}
+ */
+export const TONE_MAP_OPERATOR_GT7 = new ToneMapOperator("gt7", CodeChunk.from(
+    //language=WGSL
+    `
+fn tone_map_operator(scene: vec3<f32>, peak_nits: f32) -> vec3<f32> {
+    return tonemap_gt7_rec2020(CRM_FROM_REC709_TO_REC2020 * scene, peak_nits, PAPER_WHITE_NITS);
+}
+    `, [
+        chunk_tonemap_gt7,
+        chunk_CRM_FROM_REC709_TO_REC2020,
+        chunk_PAPER_WHITE_NITS,
+    ]
+));

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

@@ -0,0 +1,9 @@
+/**
+ * No tone mapping: the exposed colour as it is, with 1.0 at the paper white. An SDR output clips everything above
+ * it, and an HDR output shows it as far as the display reaches.
+ *
+ * @type {ToneMapOperator}
+ */
+export const TONE_MAP_OPERATOR_NONE: ToneMapOperator;
+import { ToneMapOperator } from "./ToneMapOperator.js";
+//# sourceMappingURL=TONE_MAP_OPERATOR_NONE.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TONE_MAP_OPERATOR_NONE.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/deferred/tonemap/TONE_MAP_OPERATOR_NONE.js"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,qCAFU,eAAe,CAWtB;gCAjB6B,sBAAsB"}

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

@@ -0,0 +1,20 @@
+import { chunk_CRM_FROM_REC709_TO_REC2020 } from "../../shader/chunk/color/conversion/chunk_CRM_FROM_REC709_TO_REC2020.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ToneMapOperator } from "./ToneMapOperator.js";
+
+/**
+ * No tone mapping: the exposed colour as it is, with 1.0 at the paper white. An SDR output clips everything above
+ * it, and an HDR output shows it as far as the display reaches.
+ *
+ * @type {ToneMapOperator}
+ */
+export const TONE_MAP_OPERATOR_NONE = new ToneMapOperator("none", CodeChunk.from(
+    //language=WGSL
+    `
+fn tone_map_operator(scene: vec3<f32>, peak_nits: f32) -> vec3<f32> {
+    return CRM_FROM_REC709_TO_REC2020 * scene;
+}
+    `, [
+        chunk_CRM_FROM_REC709_TO_REC2020,
+    ]
+));

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

@@ -0,0 +1,14 @@
+/**
+ * Khronos PBR Neutral (Lalish, 2024). Base colours under 0.8 come out as they are, less a 0.04 Fresnel offset, and
+ * hues never shift: made for showing products. SDR is the specification, which rolls highlights off to SDR white
+ * and toward white. HDR puts the display's peak over the paper white in place of the specification's 1, so
+ * everything below the compression start looks the same on both outputs; a display under the paper white gets the
+ * SDR form.
+ *
+ * An exposed 0.18 shows at 0.14 of SDR white, where GT7 shows it at 0.179.
+ *
+ * @type {ToneMapOperator}
+ */
+export const TONE_MAP_OPERATOR_PBR_NEUTRAL: ToneMapOperator;
+import { ToneMapOperator } from "./ToneMapOperator.js";
+//# sourceMappingURL=TONE_MAP_OPERATOR_PBR_NEUTRAL.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TONE_MAP_OPERATOR_PBR_NEUTRAL.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/deferred/tonemap/TONE_MAP_OPERATOR_PBR_NEUTRAL.js"],"names":[],"mappings":"AAMA;;;;;;;;;;GAUG;AACH,4CAFU,eAAe,CActB;gCAzB6B,sBAAsB"}

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

@@ -0,0 +1,30 @@
+import { chunk_CRM_FROM_REC709_TO_REC2020 } from "../../shader/chunk/color/conversion/chunk_CRM_FROM_REC709_TO_REC2020.js";
+import { chunk_PAPER_WHITE_NITS } from "../../shader/chunk/color/tonemap/chunk_PAPER_WHITE_NITS.js";
+import { chunk_tonemap_khronos_pbr } from "../../shader/chunk/color/tonemap/chunk_tonemap_khronos_pbr.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ToneMapOperator } from "./ToneMapOperator.js";
+
+/**
+ * Khronos PBR Neutral (Lalish, 2024). Base colours under 0.8 come out as they are, less a 0.04 Fresnel offset, and
+ * hues never shift: made for showing products. SDR is the specification, which rolls highlights off to SDR white
+ * and toward white. HDR puts the display's peak over the paper white in place of the specification's 1, so
+ * everything below the compression start looks the same on both outputs; a display under the paper white gets the
+ * SDR form.
+ *
+ * An exposed 0.18 shows at 0.14 of SDR white, where GT7 shows it at 0.179.
+ *
+ * @type {ToneMapOperator}
+ */
+export const TONE_MAP_OPERATOR_PBR_NEUTRAL = new ToneMapOperator("pbr neutral", CodeChunk.from(
+    //language=WGSL
+    `
+fn tone_map_operator(scene: vec3<f32>, peak_nits: f32) -> vec3<f32> {
+    let peak = max(peak_nits / PAPER_WHITE_NITS, 1.0);
+    return CRM_FROM_REC709_TO_REC2020 * tonemap_khronos_pbr(max(scene, vec3<f32>(0.0)), peak);
+}
+    `, [
+        chunk_tonemap_khronos_pbr,
+        chunk_CRM_FROM_REC709_TO_REC2020,
+        chunk_PAPER_WHITE_NITS,
+    ]
+));

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

@@ -0,0 +1,54 @@
+/**
+ * @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: string, chunk: CodeChunk);
+    /**
+     * @readonly
+     * @type {string}
+     */
+    readonly label: string;
+    /**
+     * @readonly
+     * @type {CodeChunk}
+     */
+    readonly chunk: CodeChunk;
+    /**
+     * Add the bindings {@link chunk} reads to the bake shader's group. None by default.
+     *
+     * @param {ShaderResourceGroupDescriptor} group
+     */
+    declare(group: ShaderResourceGroupDescriptor): void;
+    /**
+     * 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: FrameGraph, peak_nits: number, bindings: any): void;
+}
+export type CodeChunk = import("../../shader/compiler/CodeChunk.js").CodeChunk;
+export type ShaderResourceGroupDescriptor = import("../../shader/resource/ShaderResourceGroupDescriptor.js").ShaderResourceGroupDescriptor;
+export type FrameGraph = import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+//# sourceMappingURL=ToneMapOperator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ToneMapOperator.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/deferred/tonemap/ToneMapOperator.js"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH;;;;;;;;;;;;;GAaG;AACH;IACI;;;OAGG;IACH,mBAHW,MAAM,SACN,SAAS,EAkBnB;IAXG;;;OAGG;IACH,gBAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,gBAFU,SAAS,CAED;IAGtB;;;;OAIG;IACH,eAFW,6BAA6B,QAGvC;IAED;;;;;;OAMG;IACH,YAJW,UAAU,aACV,MAAM,uBAIhB;CACJ;wBA3DY,OAAO,oCAAoC,EAAE,SAAS;4CACtD,OAAO,wDAAwD,EAAE,6BAA6B;yBAC9F,OAAO,8DAA8D,EAAE,UAAU"}

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