@woosh/meep-engine 3.61.1 → 3.61.2

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/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/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/noise/chunk_sobol_sample_vec2.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Evaluates a 2D shuffled, Owen-scrambled Sobol (0, 2)-sequence point in [0, 1)^2
+ * entirely in registers with zero lookup tables.
+ *
+ * Every power-of-two prefix of 2^m samples forms a fully stratified (0, m, 2)-net
+ * across all elementary dyadic rectangles of area 2^-m, while per-pixel seeding
+ * decorrelates sample sets across pixels and bounce dimensions:
+ *
+ * 1. **Index shuffling (MSB-to-LSB):** `sample_idx` is Owen-scrambled top-down via
+ *    `reverseBits(hash_lk(reverseBits(sample_idx), ...))`. This maps every aligned
+ *    block of 2^m contiguous indices `[k * 2^m, (k + 1) * 2^m)` bijectively onto
+ *    another aligned 2^m block, randomizing traversal order per pixel while keeping
+ *    bits `i_31..i_m` constant across the block so prefix stratification holds.
+ * 2. **Dimension 0 (Van der Corput):** Prior to radical inversion, the base-2
+ *    Van der Corput sequence is the identity on `i`. Because bit 0 of `i` (`i_0`)
+ *    already represents the geometric MSB (2^-1), `hash_lk` is applied directly
+ *    followed by a single `reverseBits`.
+ * 3. **Dimension 1 (Sobol D1):** Computed without direction-number tables by
+ *    multiplying `i` by the 32x32 upper-triangular Pascal matrix over GF(2)
+ *    (`P_{k,j} = C(j, k) mod 2`, the 5-fold Kronecker power of `[1 1; 0 1]`) using
+ *    5 logarithmic butterfly shift-XOR stages before coordinate scrambling.
+ *
+ * For multi-bounce path tracing, pass a combined hash of `(pixel_coord, bounce_dim_pair)`
+ * as `pixel_seed` to construct padded 2D (0, 2)-sequences without high-dimensional
+ * direction tables.
+ *
+ * @see Brent Burley, "Practical Hash-based Owen Scrambling", Journal of Computer
+ *      Graphics Techniques (JCGT), vol. 9, no. 4, pp. 1-20, 2020.
+ *      http://jcgt.org/published/0009/04/01/
+ * @see Nathan Vegdahl, "Building a Better LK Hash", 2021.
+ *      https://psychopath.io/post/2021_01_30_building_a_better_lk_hash
+ * @see Ilya M. Sobol', "On the distribution of points in a cube and the approximate
+ *      evaluation of integrals", USSR Computational Mathematics and Mathematical
+ *      Physics, vol. 7, no. 4, pp. 86-112, 1967.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sobol_sample_vec2: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_sobol_sample_vec2.d.ts.map

package/src/shade/renderer/shader/chunk/noise/chunk_sobol_sample_vec2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_sobol_sample_vec2.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/noise/chunk_sobol_sample_vec2.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,sCAFU,SAAS,CAkClB;0BA1EyB,6BAA6B"}