@woosh/meep-engine 3.61.1 → 3.61.3

package/src/shade/renderer/postprocess/eye/GPUCameraExposureManager.js

@@ -12,11 +12,28 @@ import { shader_autoexposure_read_histogram } from "./shader_autoexposure_read_h
  * @typedef {import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
  */
 
+const HISTOGRAM_DESCRIPTOR = BufferResourceDescriptor.empty(
+    AUTOEXPOSURE_WRITE_HISTOGRAM_STRUCT.aligned_size,
+    GPUBufferUsage.STORAGE,
+);
+
+const TARGET_LUMINANCE_DESCRIPTOR = BufferResourceDescriptor.from(
+    F32_CONTAINER_STRUCT.size,
+    GPUBufferUsage.STORAGE | GPUBufferUsage.UNIFORM,
+);
+
 /**
- * Calculates exposure for eye adaptation
+ * The exposure: the factor the tonemapper multiplies the scene's linear radiance by ahead of its curve, metered from
+ * the frame and adapted to it ({@link update}), or set by {@link exposure_compensation} alone ({@link unadapted}).
+ *
+ * The factor lives in one buffer for the manager's life, {@link multiplier}, which a frame's {@link update} or
+ * {@link unadapted} writes over. A pass recorded ahead of that write in the frame reads the factor the last frame was
+ * shown with: the exposure of the image on screen, Unreal Engine's `View.PreExposure`.
  */
 export class GPUCameraExposureManager {
     /**
+     * The adapted luminance: last frame's, which this frame's adaptation reads, and this frame's, which it writes.
+     * They swap every {@link update}.
      *
      * @type {GPUTypedBuffer[]}
      */
@@ -24,6 +41,12 @@ export class GPUCameraExposureManager {
 
     #frame_index = 0;
 
+    /**
+     * {@link F32_CONTAINER_STRUCT}: the factor the last {@link update} or {@link unadapted} wrote.
+     * @type {GPUTypedBuffer}
+     */
+    #multiplier;
+
     /**
      * How fast do we adapt to brighter environments?
      * in f-stops per second.
@@ -54,6 +77,17 @@ export class GPUCameraExposureManager {
      */
     exposure_compensation = 0.0;
 
+    // what each pass's execution reads, kept across frames: a frame records them and runs them before the next does
+    #unadapted_data = { output: -1 };
+    #unadapted_value = { value: 1.0 };
+    #build_data = { input_color: -1, output: -1 };
+    #parse_data = { input_histogram: -1, output: -1 };
+    #adapt_data = { goal: -1, previous: -1, adapted: -1, out_multiplier: -1 };
+    #adapt_settings = { speed_up: 0, speed_down: 0, time_delta: 0, exp_transition_distance: 0, compensation: 0 };
+    #build_bindings = { tInput: null, histogram: null };
+    #parse_bindings = { histogram: null, output: null };
+    #adapt_bindings = { goal: null, previous: null, settings: this.#adapt_settings, adapted: null, out_multiplier: null };
+
     /**
      *
      * @param {GPUDevice} device
@@ -72,12 +106,36 @@ export class GPUCameraExposureManager {
             });
         }
 
+        // a factor of one until the first frame writes its own
+        this.#multiplier = GPUTypedBuffer.create({
+            label: 'exposure multiplier',
+            device,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+            type: F32_CONTAINER_STRUCT,
+            initial_value: {
+                value: 1.0
+            }
+        });
+
     }
 
     destroy() {
         for (const buffer of this.#exposure_buffers) {
             buffer.destroy();
         }
+
+        this.#multiplier.destroy();
+    }
+
+    /**
+     * The factor, {@link F32_CONTAINER_STRUCT}, as the last {@link update} or {@link unadapted} wrote it. A frame
+     * imports it into its graph once, and hands the handle both to the passes that read it ahead of the exposure,
+     * which take the last frame's factor, and to {@link update} or {@link unadapted}, which write this frame's.
+     *
+     * @returns {GPUBuffer} usable as a uniform or read-only storage
+     */
+    get multiplier() {
+        return this.#multiplier.buffer;
     }
 
     /**
@@ -93,62 +151,61 @@ export class GPUCameraExposureManager {
     }
 
     /**
+     * This frame's factor from {@link exposure_compensation} alone: 2^compensation.
      *
      * @param {Object} options
      * @param {FrameGraph} options.graph
-     * @return {number}
+     * @param {number} options.multiplier the graph handle of {@link multiplier}, imported into `graph`
+     * @return {number} the handle of {@link multiplier} with this frame's factor written
      */
     unadapted({
                   graph,
+                  multiplier,
               }) {
+        assert.defined(graph, 'graph');
+        assert.isNonNegativeInteger(multiplier, 'multiplier');
 
-        const data = {};
-
-        const pass = graph.add("unadapted", data,
-
-            /**
-             *
-             * @param data
-             * @param {FramePassResources} resources
-             * @param {GraphicsExecutionContext} context
-             */
-            (data, resources, context) => {
+        const data = this.#unadapted_data;
+        const pass = graph.add("unadapted", data, this.#execute_unadapted);
 
-                const output = resources.get(data.output);
+        data.output = pass.write(multiplier);
 
+        return data.output;
+    }
 
-                /**
-                 *
-                 * @type {ShadeGPUCommandContext}
-                 */
-                const encoder = context.encoder;
-
-                encoder.writeValueBuffer(output, 0, F32_CONTAINER_STRUCT, {
-                    // compensation is in f-stops: each stop doubles/halves brightness
-                    value: Math.pow(2, this.exposure_compensation),
-                });
-
-            });
-
-        data.output = pass.create("final", BufferResourceDescriptor.from(
-            F32_CONTAINER_STRUCT.size,
-            GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
-        ));
+    /**
+     * @param data
+     * @param {FramePassResources} resources
+     * @param {GraphicsExecutionContext} context
+     */
+    #execute_unadapted = (data, resources, context) => {
+        /**
+         * @type {ShadeGPUCommandContext}
+         */
+        const encoder = context.encoder;
 
-        return data.output;
+        // compensation is in f-stops: each stop doubles/halves brightness
+        this.#unadapted_value.value = Math.pow(2, this.exposure_compensation);
 
+        // in the command stream, so a pass recorded ahead of this one still reads the last frame's factor
+        encoder.writeValueBuffer(resources.get(data.output), 0, F32_CONTAINER_STRUCT, this.#unadapted_value);
     }
 
     /**
+     * This frame's factor metered from `input_color`: the luminance adapted toward the frame's, from the last
+     * frame's, by the adaptation speeds; its factor is middle grey over it, times 2^{@link exposure_compensation}.
      *
      * @param {Object} options
      * @param {FrameGraph} options.graph
      * @param {number} options.input_color
+     * @param {number} options.multiplier the graph handle of {@link multiplier}, imported into `graph`
      * @param {number} [options.time_delta_seconds]
+     * @return {number} the handle of {@link multiplier} with this frame's factor written
      */
     update({
                input_color,
                graph,
+               multiplier,
                time_delta_seconds = 0.01666,
            }) {
 
@@ -160,142 +217,113 @@ export class GPUCameraExposureManager {
          this used to be given, is Karis-averaged for precisely that purpose.
         */
 
+        assert.defined(graph, 'graph');
+        assert.isNonNegativeInteger(multiplier, 'multiplier');
         assert.isNumber(time_delta_seconds, 'time_delta_seconds');
         assert.greaterThanOrEqual(time_delta_seconds, 0, 'time_delta_seconds');
 
         this.#frame_index++;
 
-        const build_data = {};
+        const build_data = this.#build_data;
+        const build_pass = graph.add("build histogram", build_data, this.#execute_build_histogram);
 
-        /**
-         *
-         * @param data
-         * @param {FramePassResources} resources
-         * @param {GraphicsExecutionContext} context
-         */
-        function build_histogram(data, resources, context) {
-            const input_color = resources.get(data.input_color);
-            const output = resources.get(data.output);
+        build_data.input_color = build_pass.read(input_color);
+        build_data.output = build_pass.create("histogram", HISTOGRAM_DESCRIPTOR);
 
-            const gx = Math.ceil(input_color.width / 16);
-            const gy = Math.ceil(input_color.height / 16);
+        const parse_data = this.#parse_data;
+        const parse_pass = graph.add("parse histogram", parse_data, this.#execute_parse_histogram);
 
-            if (gx <= 0 || gy <= 0) {
-                // nothing to dispatch
-                return;
-            }
+        parse_data.input_histogram = parse_pass.read(build_data.output);
+        parse_data.output = parse_pass.create("target luminance", TARGET_LUMINANCE_DESCRIPTOR);
 
-            shader_autoexposure_build_histogram.dispatch({
-                encoder: context.encoder,
-                group_count_x: gx,
-                group_count_y: gy,
-                bindings: {
-                    tInput: input_color.obtainView(),
-                    histogram: output,
-                },
-            });
+        const exposure_buffer_previous = this.#exposure_buffers[this.#frame_index % 2];
+        const exposure_buffer_current = this.#exposure_buffers[(this.#frame_index + 1) % 2];
 
-        }
+        // the frame's step; the rest of the settings are read as the pass runs
+        this.#adapt_settings.time_delta = time_delta_seconds;
 
-        const build_pass = graph.add("build histogram", build_data, build_histogram);
+        const adapt_data = this.#adapt_data;
+        const adapt_pass = graph.add("adaptation", adapt_data, this.#execute_adapt);
 
-        build_data.input_color = build_pass.read(input_color);
-        build_data.output = build_pass.create("histogram", BufferResourceDescriptor.empty(
-            AUTOEXPOSURE_WRITE_HISTOGRAM_STRUCT.aligned_size,
-            GPUBufferUsage.STORAGE,
-        ));
+        adapt_data.goal = adapt_pass.read(parse_data.output);
+        adapt_data.previous = adapt_pass.read(graph_import_buffer(graph, exposure_buffer_previous.buffer, "previous adapted luminance"));
+        adapt_data.adapted = adapt_pass.write(graph_import_buffer(graph, exposure_buffer_current.buffer, "adapted luminance"));
+        adapt_data.out_multiplier = adapt_pass.write(multiplier);
+
+        return adapt_data.out_multiplier;
+    }
 
-        //
+    /**
+     * @param data
+     * @param {FramePassResources} resources
+     * @param {GraphicsExecutionContext} context
+     */
+    #execute_build_histogram = (data, resources, context) => {
+        const input_color = resources.get(data.input_color);
+        const output = resources.get(data.output);
 
-        const parse_data = {};
+        const gx = Math.ceil(input_color.width / 16);
+        const gy = Math.ceil(input_color.height / 16);
 
-        /**
-         *
-         * @param data
-         * @param {FramePassResources} resources
-         * @param {GraphicsExecutionContext} context
-         */
-        function parse_histogram(data, resources, context) {
-            const input_histogram = resources.get(data.input_histogram);
-            const output = resources.get(data.output);
-
-            shader_autoexposure_read_histogram.dispatch({
-                encoder: context.encoder,
-                bindings: {
-                    histogram: input_histogram,
-                    output: output,
-                },
-            });
+        if (gx <= 0 || gy <= 0) {
+            // nothing to dispatch
+            return;
         }
 
-        // ---------
+        const bindings = this.#build_bindings;
 
-        const exposure_buffer_previous = this.#exposure_buffers[this.#frame_index % 2];
-        const exposure_buffer_current = this.#exposure_buffers[(this.#frame_index + 1) % 2];
+        bindings.tInput = input_color.obtainView();
+        bindings.histogram = output;
 
-        const gr_exposure_data_previous = graph_import_buffer(graph, exposure_buffer_previous.buffer, "previous exposure");
-        const gr_exposure_data_current = graph_import_buffer(graph, exposure_buffer_current.buffer, "previous exposure");
+        shader_autoexposure_build_histogram.dispatch({
+            encoder: context.encoder,
+            group_count_x: gx,
+            group_count_y: gy,
+            bindings,
+        });
+    }
 
-        const parse_pass = graph.add("parse histogram", parse_data, parse_histogram);
+    /**
+     * @param data
+     * @param {FramePassResources} resources
+     * @param {GraphicsExecutionContext} context
+     */
+    #execute_parse_histogram = (data, resources, context) => {
+        const bindings = this.#parse_bindings;
 
-        parse_data.input_histogram = parse_pass.read(build_data.output);
-        parse_data.output = parse_pass.create("target luminance", BufferResourceDescriptor.from(
-            F32_CONTAINER_STRUCT.size,
-            GPUBufferUsage.STORAGE | GPUBufferUsage.UNIFORM,
-        ));
+        bindings.histogram = resources.get(data.input_histogram);
+        bindings.output = resources.get(data.output);
 
+        shader_autoexposure_read_histogram.dispatch({
+            encoder: context.encoder,
+            bindings,
+        });
+    }
 
-        // ---------
+    /**
+     * @param data
+     * @param {FramePassResources} resources
+     * @param {GraphicsExecutionContext} context
+     */
+    #execute_adapt = (data, resources, context) => {
+        const settings = this.#adapt_settings;
 
-        const adapt_data = {};
+        settings.speed_up = this.adaptation_speed_up;
+        settings.speed_down = this.adaptation_speed_down;
+        settings.exp_transition_distance = this.exp_transition_distance;
+        settings.compensation = this.exposure_compensation;
 
-        /**
-         *
-         * @param data
-         * @param {FramePassResources} resources
-         * @param {GraphicsExecutionContext} context
-         */
-        const adapt = (data, resources, context) => {
-
-            const encoder = context.encoder;
-
-            const settings = {
-                speed_up: this.adaptation_speed_up,
-                speed_down: this.adaptation_speed_down,
-                time_delta: time_delta_seconds,
-                exp_transition_distance: this.exp_transition_distance,
-                compensation: this.exposure_compensation,
-            };
-
-
-            const goal = resources.get(data.goal);
-            const previous = resources.get(data.previous);
-            const adapted = resources.get(data.adapted);
-            const out_multiplier = resources.get(data.out_multiplier);
-
-            shader_autoexposure_adapt.dispatch({
-                encoder,
-                bindings: {
-                    goal,
-                    previous,
-                    settings,
-                    adapted,
-                    out_multiplier,
-                }
-            });
-        }
+        const bindings = this.#adapt_bindings;
 
-        const adapt_pass = graph.add("adaptation", adapt_data, adapt);
+        bindings.goal = resources.get(data.goal);
+        bindings.previous = resources.get(data.previous);
+        bindings.adapted = resources.get(data.adapted);
+        bindings.out_multiplier = resources.get(data.out_multiplier);
 
-        adapt_data.goal = adapt_pass.read(parse_data.output);
-        adapt_data.previous = adapt_pass.read(gr_exposure_data_previous);
-        adapt_data.adapted = adapt_pass.write(gr_exposure_data_current);
-        adapt_data.out_multiplier = adapt_pass.create("final", BufferResourceDescriptor.from(
-            F32_CONTAINER_STRUCT.size,
-            GPUBufferUsage.STORAGE | GPUBufferUsage.UNIFORM,
-        ));
-
-        return adapt_data.out_multiplier;
+        shader_autoexposure_adapt.dispatch({
+            encoder: context.encoder,
+            bindings,
+        });
     }
 
-}
+}

package/src/shade/renderer/postprocess/nss/NSS.d.ts

@@ -51,7 +51,7 @@ export class NSS {
      * @returns {number}
      */
     static recommended_jitter_sequence_size(upscale_ratio: number): number;
-    static "__#214@#preprocess_tensor_descriptor"(render_w: any, render_h: any): TextureResourceDescriptor;
+    static "__#216@#preprocess_tensor_descriptor"(render_w: any, render_h: any): TextureResourceDescriptor;
     /**
      * @param {GraphicsContext} graphics
      */

package/src/shade/renderer/rasterize/forward/chunk_forward_sample_indirect_probe_clipmap.d.ts

@@ -1,7 +1,7 @@
 /**
  * {@link chunk_forward_sample_indirect} from the probe clipmap (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §9.5): one
  * pick at the fragment by its shading normal and view, jittered by a hash of its position and normal that
- * changes every frame, as Brick4's is, for both lobes. The irradiance is π × the picked SH resolved at the normal,
+ * changes every frame, as Brick4's is, for both lobes. The irradiance is the picked SH resolved at the normal,
  * the specular the pick's radiance at the fragment's roughness (§9.3); where no probe weighs anything, both are
  * the environment's. Reads the probes' group, `view` and `tEnvironment`.
  *

package/src/shade/renderer/rasterize/forward/chunk_forward_sample_indirect_probe_clipmap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_forward_sample_indirect_probe_clipmap.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/forward/chunk_forward_sample_indirect_probe_clipmap.js"],"names":[],"mappings":"AAaA;;;;;;;;GAQG;AACH,0DAFU,SAAS,CAoCjB;0BA7CwB,oCAAoC"}
+{"version":3,"file":"chunk_forward_sample_indirect_probe_clipmap.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/forward/chunk_forward_sample_indirect_probe_clipmap.js"],"names":[],"mappings":"AAYA;;;;;;;;GAQG;AACH,0DAFU,SAAS,CAkCjB;0BA3CwB,oCAAoC"}

package/src/shade/renderer/rasterize/forward/chunk_forward_sample_indirect_probe_clipmap.js

@@ -4,17 +4,16 @@ import { chunk_probe_clipmap_pick } from "../../global_illumination/probe_clipma
 import {
     chunk_probe_clipmap_sample_radiance
 } from "../../global_illumination/probe_clipmap/probe/chunk_probe_clipmap_sample_radiance.js";
-import { PI_DECLARATION } from "../../shader/chunk/math/PI_DECLARATION.js";
 import { chunk_jitter_from_vectors } from "../../shader/chunk/random/chunk_jitter_from_vectors.js";
 import {
-    chunk_resolve_irradiance_sh_to_diffuse
-} from "../../shader/chunk/spherical_harmonics/l1i/chunk_resolve_irradiance_sh_to_diffuse.js";
+    chunk_sh3_color_get_irradiance_at
+} from "../../shader/chunk/spherical_harmonics/chunk_sh3_color_get_irradiance_at.js";
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 
 /**
  * {@link chunk_forward_sample_indirect} from the probe clipmap (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §9.5): one
  * pick at the fragment by its shading normal and view, jittered by a hash of its position and normal that
- * changes every frame, as Brick4's is, for both lobes. The irradiance is π × the picked SH resolved at the normal,
+ * changes every frame, as Brick4's is, for both lobes. The irradiance is the picked SH resolved at the normal,
  * the specular the pick's radiance at the fragment's roughness (§9.3); where no probe weighs anything, both are
  * the environment's. Reads the probes' group, `view` and `tEnvironment`.
  *
@@ -37,8 +36,7 @@ fn forward_sample_indirect(
     let probes = probe_clipmap_sh_of(pick);
 
     if (probes.found) {
-        // the resolve gives E/π
-        *irradiance = PI * resolve_irradiance_sh_to_diffuse(probes.sh.Y, probes.sh.CoCg, normal);
+        *irradiance = sh3_color_get_irradiance_at(normal, probes.sh);
         *radiance = probe_clipmap_radiance_of(pick, position_ws, normal, view_direction, roughness).radiance;
     } else {
         *irradiance = get_ibl_irradiance(normal);
@@ -50,8 +48,7 @@ fn forward_sample_indirect(
         chunk_get_ibl_irradiance,
         chunk_probe_clipmap_pick,
         chunk_probe_clipmap_sample_radiance,
-        chunk_resolve_irradiance_sh_to_diffuse,
+        chunk_sh3_color_get_irradiance_at,
         chunk_jitter_from_vectors,
-        PI_DECLARATION,
     ]
 );

package/src/shade/renderer/scene/GPUSceneContext.d.ts

@@ -105,7 +105,7 @@ export class GPUSceneContext {
      * (REVIEW_LEDGER U1): `register` a container with {@link virtual_geometry_residency}, and every
      * page after the root arrives because a cut asked for it. The renderer opens and closes each
      * frame and schedules each reading, and {@link destroy} releases all of it; a host touches none
-     * of it. With them, the source of its geometries' caches and cards ({@link VGeoSDFProxies}): a virtual
+     * of it. With them, the source of its geometries' caches and surface caches ({@link VGeoSDFProxies}): a virtual
      * geometry whose cache is asked for stands in through its proxy.
      *
      * @param {Object} [options] passed to {@link GPUVirtualGeometryPool} and

package/src/shade/renderer/scene/GPUSceneContext.js

@@ -400,7 +400,7 @@ export class GPUSceneContext {
      * (REVIEW_LEDGER U1): `register` a container with {@link virtual_geometry_residency}, and every
      * page after the root arrives because a cut asked for it. The renderer opens and closes each
      * frame and schedules each reading, and {@link destroy} releases all of it; a host touches none
-     * of it. With them, the source of its geometries' caches and cards ({@link VGeoSDFProxies}): a virtual
+     * of it. With them, the source of its geometries' caches and surface caches ({@link VGeoSDFProxies}): a virtual
      * geometry whose cache is asked for stands in through its proxy.
      *
      * @param {Object} [options] passed to {@link GPUVirtualGeometryPool} and

package/src/shade/renderer/shader/chunk/filter/chunk_multiscale_mean.d.ts

@@ -6,16 +6,27 @@
  *
  * ```wgsl
  * fn multiscale_mean_seed(sample: vec3f) -> MultiscaleMean
- * fn multiscale_mean_add(e: MultiscaleMean, sample: vec3f, short_blend: f32, variance_blend: f32, mean_blend_min: f32, clip: bool) -> MultiscaleMean
+ * fn multiscale_mean_add(e: MultiscaleMean, sample: vec3f, short_blend: f32, variance_blend: f32, mean_blend_min: f32, clip: bool, exposure: f32) -> MultiscaleMean
+ * fn multiscale_mean_deviation_floor(short_mean: vec3f, exposure: f32) -> vec3f
  * ```
  *
  * `MultiscaleMean` is {@link MULTISCALE_MEAN_STRUCT}.
  *
+ * - **Exposure**: the factor the display multiplies the samples by ahead of its tone curve, Unreal Engine's
+ *   `View.PreExposure`. The reference's two absolute constants, its variance floor of 1e-5 and its firefly offset
+ *   of 0.1, are in exposed units, as Unreal states its world caches' thresholds (`MaxRayIntensity ·
+ *   OneOverPreExposure`): over a stream scaled by 1/E at an exposure of E the estimator does what it does over
+ *   the stream at an exposure of one, so it tells a change from noise as far as the display shows it. Held to the
+ *   positive normal f32 range, where neither constant overflows or vanishes.
+ * - **Deviation floor**: the least deviation the estimator divides by, √1e-5 / exposure, and never under one
+ *   half-float step of the short mean, `max(|short_mean|·2⁻¹⁰, 2⁻²⁴)`: the state is stored in halves, so a
+ *   smaller gap between the means is their rounding, and the floor stays above zero at any exposure. Taken as
+ *   `max(floor, √variance)`, the reference's `√max(floor², variance)` without squaring the floor.
  * - **Seed**: both means at the first sample, nothing of variance, no blend reduction, an inconsistency of one,
  *   as WickedEngine's surfels seed it.
- * - **Clip**: a sample past `0.1 + short_mean + 8·deviation` a channel is held there, a firefly. The 0.1 is
- *   the reference's, in the radiance's own units. A caller whose variance does not yet rest on a window of
- *   samples passes `clip` false: there is no spread to clip to.
+ * - **Clip**: a sample past `0.1 / exposure + short_mean + 8·deviation` a channel is held there, a firefly. A
+ *   caller whose variance does not yet rest on a window of samples passes `clip` false: there is no spread to clip
+ *   to.
  * - **Short mean**: blended by `short_blend`; the variance by `variance_blend`, the reference's half of it, so
  *   that its window outlasts the short mean's.
  * - **Long mean**: blended by the catch-up, `smoothstep(relative · max(0.02, inconsistency − 0.2))` held to

package/src/shade/renderer/shader/chunk/filter/chunk_multiscale_mean.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_multiscale_mean.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/filter/chunk_multiscale_mean.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,oCAFU,SAAS,CA4CZ;0BAtFmB,6BAA6B"}
+{"version":3,"file":"chunk_multiscale_mean.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/filter/chunk_multiscale_mean.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,oCAFU,SAAS,CAuDZ;0BAhHmB,6BAA6B"}

package/src/shade/renderer/shader/chunk/filter/chunk_multiscale_mean.js

@@ -2,6 +2,10 @@ import { CodeChunk } from "../../compiler/CodeChunk.js";
 import { chunk_rgb_to_luminance } from "../color/chunk_rgb_to_luminance.js";
 import { MULTISCALE_MEAN_STRUCT } from "./MULTISCALE_MEAN_STRUCT.js";
 
+/** 2⁻¹²⁶ and 2¹²⁷, the positive normal f32 range's ends */
+const EXPOSURE_MIN = '1.17549435e-38';
+const EXPOSURE_MAX = '1.70141183e38';
+
 /**
  * The multi-scale mean estimator (MSME) of a stream of RGB samples: a long mean that blends slowly while the
  * stream is steady and noisy, and catches up with a short mean once the two disagree by more than the stream's
@@ -10,16 +14,27 @@ import { MULTISCALE_MEAN_STRUCT } from "./MULTISCALE_MEAN_STRUCT.js";
  *
  * ```wgsl
  * fn multiscale_mean_seed(sample: vec3f) -> MultiscaleMean
- * fn multiscale_mean_add(e: MultiscaleMean, sample: vec3f, short_blend: f32, variance_blend: f32, mean_blend_min: f32, clip: bool) -> MultiscaleMean
+ * fn multiscale_mean_add(e: MultiscaleMean, sample: vec3f, short_blend: f32, variance_blend: f32, mean_blend_min: f32, clip: bool, exposure: f32) -> MultiscaleMean
+ * fn multiscale_mean_deviation_floor(short_mean: vec3f, exposure: f32) -> vec3f
  * ```
  *
  * `MultiscaleMean` is {@link MULTISCALE_MEAN_STRUCT}.
  *
+ * - **Exposure**: the factor the display multiplies the samples by ahead of its tone curve, Unreal Engine's
+ *   `View.PreExposure`. The reference's two absolute constants, its variance floor of 1e-5 and its firefly offset
+ *   of 0.1, are in exposed units, as Unreal states its world caches' thresholds (`MaxRayIntensity ·
+ *   OneOverPreExposure`): over a stream scaled by 1/E at an exposure of E the estimator does what it does over
+ *   the stream at an exposure of one, so it tells a change from noise as far as the display shows it. Held to the
+ *   positive normal f32 range, where neither constant overflows or vanishes.
+ * - **Deviation floor**: the least deviation the estimator divides by, √1e-5 / exposure, and never under one
+ *   half-float step of the short mean, `max(|short_mean|·2⁻¹⁰, 2⁻²⁴)`: the state is stored in halves, so a
+ *   smaller gap between the means is their rounding, and the floor stays above zero at any exposure. Taken as
+ *   `max(floor, √variance)`, the reference's `√max(floor², variance)` without squaring the floor.
  * - **Seed**: both means at the first sample, nothing of variance, no blend reduction, an inconsistency of one,
  *   as WickedEngine's surfels seed it.
- * - **Clip**: a sample past `0.1 + short_mean + 8·deviation` a channel is held there, a firefly. The 0.1 is
- *   the reference's, in the radiance's own units. A caller whose variance does not yet rest on a window of
- *   samples passes `clip` false: there is no spread to clip to.
+ * - **Clip**: a sample past `0.1 / exposure + short_mean + 8·deviation` a channel is held there, a firefly. A
+ *   caller whose variance does not yet rest on a window of samples passes `clip` false: there is no spread to clip
+ *   to.
  * - **Short mean**: blended by `short_blend`; the variance by `variance_blend`, the reference's half of it, so
  *   that its window outlasts the short mean's.
  * - **Long mean**: blended by the catch-up, `smoothstep(relative · max(0.02, inconsistency − 0.2))` held to
@@ -55,17 +70,28 @@ fn multiscale_mean_seed(sample: vec3f) -> ${MULTISCALE_MEAN_STRUCT.wgsl_ref} {
     })};
 }
 
-fn multiscale_mean_add(e: ${MULTISCALE_MEAN_STRUCT.wgsl_ref}, sample: vec3f, short_blend: f32, variance_blend: f32, mean_blend_min: f32, clip: bool) -> ${MULTISCALE_MEAN_STRUCT.wgsl_ref} {
+// the exposure, held to the positive normal f32 range
+fn multiscale_mean_exposure(exposure: f32) -> f32 {
+    return clamp(exposure, ${EXPOSURE_MIN}, ${EXPOSURE_MAX});
+}
+
+fn multiscale_mean_deviation_floor(short_mean: vec3f, exposure: f32) -> vec3f {
+    return max(vec3f(sqrt(1e-5) / multiscale_mean_exposure(exposure)), max(abs(short_mean) * exp2(-10.0), vec3f(exp2(-24.0))));
+}
+
+fn multiscale_mean_add(e: ${MULTISCALE_MEAN_STRUCT.wgsl_ref}, sample: vec3f, short_blend: f32, variance_blend: f32, mean_blend_min: f32, clip: bool, exposure: f32) -> ${MULTISCALE_MEAN_STRUCT.wgsl_ref} {
     var y = sample;
 
     if (clip) {
-        y = min(y, 0.1 + e.short_mean + 8.0 * sqrt(max(vec3f(1e-5), e.variance)));
+        let spread = max(multiscale_mean_deviation_floor(e.short_mean, exposure), sqrt(max(vec3f(0.0), e.variance)));
+
+        y = min(y, 0.1 / multiscale_mean_exposure(exposure) + e.short_mean + 8.0 * spread);
     }
 
     let delta = y - e.short_mean;
     let short_mean = mix(e.short_mean, y, short_blend);
     let variance = mix(e.variance, delta * (y - short_mean), variance_blend);
-    let deviation = sqrt(max(vec3f(1e-5), variance));
+    let deviation = max(multiscale_mean_deviation_floor(short_mean, exposure), sqrt(max(vec3f(0.0), variance)));
 
     let relative = rgb_to_luminance(abs(e.mean - short_mean) / deviation);
     let inconsistency = mix(e.inconsistency, relative, short_blend);

package/src/shade/renderer/shader/chunk/material/albedo_compress.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The code `albedo_compress` (`chunk_albedo_compress.js`) gives an albedo, on the host: each channel
+ * clamped to [0, 1], its square root rounded to f32 and then to unorm8, as `pack4x8unorm` rounds, the
+ * top byte 255.
+ *
+ * @param {number} r linear
+ * @param {number} g linear
+ * @param {number} b linear
+ * @returns {number} u32
+ */
+export function albedo_compress(r: number, g: number, b: number): number;
+//# sourceMappingURL=albedo_compress.d.ts.map

package/src/shade/renderer/shader/chunk/material/albedo_compress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"albedo_compress.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/material/albedo_compress.js"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,mCALW,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CAIlB"}