@woosh/meep-engine 3.58.0 → 3.60.0

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

@@ -0,0 +1,43 @@
+/**
+ * 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
+ * deviation explains. Barré-Brisebois et al., *Hybrid Rendering for Real-Time Ray Tracing*, Ray Tracing Gems
+ * (2019) ch. 25; Enshrouded's probes (Kolesik, GPC 2024) keep it a texel.
+ *
+ * ```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
+ * ```
+ *
+ * `MultiscaleMean` is {@link MULTISCALE_MEAN_STRUCT}.
+ *
+ * - **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.
+ * - **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
+ *   [1/256, 1], times the blend reduction, and at least `mean_blend_min`. `relative` is the luminance of the
+ *   means' gap over the deviation; the inconsistency its smoothed history; the reduction the luminance of half
+ *   the short mean over the deviation, held to [1/32, 1], a noisy stream's longer window. The inconsistency
+ *   follows by `short_blend`, where the reference's 0.08 a sample stands at its default short blend of 0.08.
+ * - **The reduction follows by the reference's 0.1 a sample**, whatever the short blend. The catch-up takes the
+ *   last sample's reduction, so following by a large short blend (rare samples) it would track each one: the
+ *   long mean's weight would rise after the bright samples it is about to fall back from, and it settles low.
+ *   Measured through the probe accumulate pass (2026-10-29, the emulator, samples of mean 1 and deviation 1,
+ *   four streams averaged): 7, 18, 28 and 39% low at short blends of 0.55, 0.63, 0.78 and 0.9 that way; 2, 3,
+ *   7 and 15% at 0.1 a sample, with the same step response.
+ *
+ * Measured on a CPU model (2026-10-29, 200 runs averaged), against an exponential mean of the short blend, over
+ * samples that are 0 or twice the mean, a ray of two lit: at a short blend of 1/4 the long mean wanders 0.19 of
+ * the mean against 0.38, and reaches 90% of a tripling in 14 samples against 9; at 1/8, 0.077 against 0.25, in
+ * 88 against 18. An exponential mean as steady takes 35 and 197. Over a noiseless stream it takes a step about
+ * twice as slowly as the short blend, the clip holding the first samples past the step.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_multiscale_mean: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_multiscale_mean.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,87 @@
+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";
+
+/**
+ * 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
+ * deviation explains. Barré-Brisebois et al., *Hybrid Rendering for Real-Time Ray Tracing*, Ray Tracing Gems
+ * (2019) ch. 25; Enshrouded's probes (Kolesik, GPC 2024) keep it a texel.
+ *
+ * ```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
+ * ```
+ *
+ * `MultiscaleMean` is {@link MULTISCALE_MEAN_STRUCT}.
+ *
+ * - **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.
+ * - **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
+ *   [1/256, 1], times the blend reduction, and at least `mean_blend_min`. `relative` is the luminance of the
+ *   means' gap over the deviation; the inconsistency its smoothed history; the reduction the luminance of half
+ *   the short mean over the deviation, held to [1/32, 1], a noisy stream's longer window. The inconsistency
+ *   follows by `short_blend`, where the reference's 0.08 a sample stands at its default short blend of 0.08.
+ * - **The reduction follows by the reference's 0.1 a sample**, whatever the short blend. The catch-up takes the
+ *   last sample's reduction, so following by a large short blend (rare samples) it would track each one: the
+ *   long mean's weight would rise after the bright samples it is about to fall back from, and it settles low.
+ *   Measured through the probe accumulate pass (2026-10-29, the emulator, samples of mean 1 and deviation 1,
+ *   four streams averaged): 7, 18, 28 and 39% low at short blends of 0.55, 0.63, 0.78 and 0.9 that way; 2, 3,
+ *   7 and 15% at 0.1 a sample, with the same step response.
+ *
+ * Measured on a CPU model (2026-10-29, 200 runs averaged), against an exponential mean of the short blend, over
+ * samples that are 0 or twice the mean, a ray of two lit: at a short blend of 1/4 the long mean wanders 0.19 of
+ * the mean against 0.38, and reaches 90% of a tripling in 14 samples against 9; at 1/8, 0.077 against 0.25, in
+ * 88 against 18. An exponential mean as steady takes 35 and 197. Over a noiseless stream it takes a step about
+ * twice as slowly as the short blend, the clip holding the first samples past the step.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_multiscale_mean = CodeChunk.from(
+    //language=WGSL
+    `
+fn multiscale_mean_seed(sample: vec3f) -> ${MULTISCALE_MEAN_STRUCT.wgsl_ref} {
+    return ${MULTISCALE_MEAN_STRUCT.make({
+        mean: 'sample',
+        short_mean: 'sample',
+        variance: 'vec3f(0.0)',
+        reduction: '0.0',
+        inconsistency: '1.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) -> ${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 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 relative = rgb_to_luminance(abs(e.mean - short_mean) / deviation);
+    let inconsistency = mix(e.inconsistency, relative, short_blend);
+    let reduction = clamp(rgb_to_luminance(0.5 * short_mean / deviation), 1.0 / 32.0, 1.0);
+
+    let catch_up = clamp(smoothstep(0.0, 1.0, relative * max(0.02, inconsistency - 0.2)), 1.0 / 256.0, 1.0) * e.reduction;
+
+    return ${MULTISCALE_MEAN_STRUCT.make({
+        mean: 'mix(e.mean, y, max(saturate(catch_up), mean_blend_min))',
+        short_mean: 'short_mean',
+        variance: 'variance',
+        reduction: 'mix(e.reduction, reduction, 0.1)',
+        inconsistency: 'inconsistency',
+    })};
+}
+`, [
+        chunk_rgb_to_luminance,
+        MULTISCALE_MEAN_STRUCT.declaration_chunk,
+    ]);

package/src/shade/renderer/shader/chunk/geometry/meshlet/chunk_read_meshlet_triangle_bounds.d.ts

@@ -1,12 +1,6 @@
 /**
- * The AABB of one triangle of a meshlet, from positions alone.
- *
- * {@link chunk_read_meshlet_triangle_vertices} answers the same addressing question and then decodes
- * every attribute a shaded hit needs — normal, tangent, two UV sets, colour. A bounds pass wants
- * none of that, and runs over every triangle of a deformed mesh every frame, so it reads the three
- * positions and stops. The index addressing, the attribute-section offset and the vertex clamp are
- * the shared chunks either way, which is where a disagreement between the two would actually hurt:
- * bounds that do not contain the triangle the ray query goes on to intersect.
+ * The AABB of one triangle of a meshlet, from positions alone ({@link chunk_read_meshlet_triangle_positions}): a
+ * bounds pass runs over every triangle of a deformed mesh every frame, and decodes no other attribute.
  *
  * @type {CodeChunk}
  */

package/src/shade/renderer/shader/chunk/geometry/meshlet/chunk_read_meshlet_triangle_bounds.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_read_meshlet_triangle_bounds.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/meshlet/chunk_read_meshlet_triangle_bounds.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;GAWG;AACH,iDAFU,SAAS,CAkChB;0BAjDuB,gCAAgC"}
+{"version":3,"file":"chunk_read_meshlet_triangle_bounds.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/meshlet/chunk_read_meshlet_triangle_bounds.js"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,iDAFU,SAAS,CAgBhB;0BAvBuB,gCAAgC"}

package/src/shade/renderer/shader/chunk/geometry/meshlet/chunk_read_meshlet_triangle_bounds.js

@@ -1,52 +1,25 @@
-import { AABB3_STRUCT } from "../aabb3/AABB3_STRUCT.js";
-import { MESHLET_METADATA_STRUCT } from "../../../../geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
-import { CodeChunk } from "../../../compiler/CodeChunk.js";
-import { chunk_meshlet_compute_attribute_section_offset } from "./chunk_meshlet_compute_attribute_section_offset.js";
-import { chunk_read_meshlet_attribute_vec3f } from "./chunk_read_meshlet_attribute_vec3f.js";
-import { chunk_read_meshlet_resolved_index } from "./chunk_read_meshlet_resolved_index.js";
-
-/**
- * The AABB of one triangle of a meshlet, from positions alone.
- *
- * {@link chunk_read_meshlet_triangle_vertices} answers the same addressing question and then decodes
- * every attribute a shaded hit needs — normal, tangent, two UV sets, colour. A bounds pass wants
- * none of that, and runs over every triangle of a deformed mesh every frame, so it reads the three
- * positions and stops. The index addressing, the attribute-section offset and the vertex clamp are
- * the shared chunks either way, which is where a disagreement between the two would actually hurt:
- * bounds that do not contain the triangle the ray query goes on to intersect.
- *
- * @type {CodeChunk}
- */
-export const chunk_read_meshlet_triangle_bounds = CodeChunk.from(
-    //language=WGSL
-    `
-fn read_meshlet_triangle_bounds(
-    meshlet_id: u32,
-    triangle_id: u32
-) -> ${AABB3_STRUCT.wgsl_ref} {
-    let header = meshlet_metadata[meshlet_id];
-
-    let attribute_offset = meshlet_compute_attribute_section_offset(header);
-
-    let index_offset = triangle_id * 3u;
-
-    // position is the first attribute of the section, three floats per vertex
-    let a = read_meshlet_attribute_vec3f(
-        attribute_offset + min(read_meshlet_resolved_index(header, index_offset), header.vertex_count - 1u) * 3u
-    );
-    let b = read_meshlet_attribute_vec3f(
-        attribute_offset + min(read_meshlet_resolved_index(header, index_offset + 1u), header.vertex_count - 1u) * 3u
-    );
-    let c = read_meshlet_attribute_vec3f(
-        attribute_offset + min(read_meshlet_resolved_index(header, index_offset + 2u), header.vertex_count - 1u) * 3u
-    );
-
-    return ${AABB3_STRUCT.wgsl_ref}(min(min(a, b), c), max(max(a, b), c));
-}
-`, [
-    AABB3_STRUCT.declaration_chunk,
-    MESHLET_METADATA_STRUCT.declaration_chunk,
-    chunk_meshlet_compute_attribute_section_offset,
-    chunk_read_meshlet_attribute_vec3f,
-    chunk_read_meshlet_resolved_index,
-]);
+import { AABB3_STRUCT } from "../aabb3/AABB3_STRUCT.js";
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+import { chunk_read_meshlet_triangle_positions } from "./chunk_read_meshlet_triangle_positions.js";
+
+/**
+ * The AABB of one triangle of a meshlet, from positions alone ({@link chunk_read_meshlet_triangle_positions}): a
+ * bounds pass runs over every triangle of a deformed mesh every frame, and decodes no other attribute.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_read_meshlet_triangle_bounds = CodeChunk.from(
+    //language=WGSL
+    `
+fn read_meshlet_triangle_bounds(
+    meshlet_id: u32,
+    triangle_id: u32
+) -> ${AABB3_STRUCT.wgsl_ref} {
+    let t = read_meshlet_triangle_positions(meshlet_id, triangle_id);
+
+    return ${AABB3_STRUCT.wgsl_ref}(min(min(t.a, t.b), t.c), max(max(t.a, t.b), t.c));
+}
+`, [
+    AABB3_STRUCT.declaration_chunk,
+    chunk_read_meshlet_triangle_positions,
+]);

package/src/shade/renderer/shader/chunk/geometry/meshlet/chunk_read_meshlet_triangle_positions.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The three positions of one triangle of a meshlet, and nothing else.
+ *
+ * {@link chunk_read_meshlet_triangle_vertices} answers the same addressing question and then decodes
+ * every attribute a shaded hit needs — normal, tangent, two UV sets, colour. A pass that wants the
+ * shape alone (a triangle's bounds, its distance from a point) reads the three positions and stops.
+ * The index addressing, the attribute-section offset and the vertex clamp are the shared chunks either
+ * way, which is where a disagreement between the two would actually hurt: a shape that is not the
+ * triangle a ray query goes on to intersect.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_read_meshlet_triangle_positions: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_read_meshlet_triangle_positions.d.ts.map

package/src/shade/renderer/shader/chunk/geometry/meshlet/chunk_read_meshlet_triangle_positions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_read_meshlet_triangle_positions.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/meshlet/chunk_read_meshlet_triangle_positions.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;GAWG;AACH,oDAFU,SAAS,CAkChB;0BAlDuB,gCAAgC"}

package/src/shade/renderer/shader/chunk/geometry/meshlet/chunk_read_meshlet_triangle_positions.js

@@ -0,0 +1,52 @@
+import { MESHLET_METADATA_STRUCT } from "../../../../geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+import { TRIANGLE_POSITIONS_STRUCT } from "../triangle/TRIANGLE_POSITIONS_STRUCT.js";
+import { chunk_meshlet_compute_attribute_section_offset } from "./chunk_meshlet_compute_attribute_section_offset.js";
+import { chunk_read_meshlet_attribute_vec3f } from "./chunk_read_meshlet_attribute_vec3f.js";
+import { chunk_read_meshlet_resolved_index } from "./chunk_read_meshlet_resolved_index.js";
+
+/**
+ * The three positions of one triangle of a meshlet, and nothing else.
+ *
+ * {@link chunk_read_meshlet_triangle_vertices} answers the same addressing question and then decodes
+ * every attribute a shaded hit needs — normal, tangent, two UV sets, colour. A pass that wants the
+ * shape alone (a triangle's bounds, its distance from a point) reads the three positions and stops.
+ * The index addressing, the attribute-section offset and the vertex clamp are the shared chunks either
+ * way, which is where a disagreement between the two would actually hurt: a shape that is not the
+ * triangle a ray query goes on to intersect.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_read_meshlet_triangle_positions = CodeChunk.from(
+    //language=WGSL
+    `
+fn read_meshlet_triangle_positions(
+    meshlet_id: u32,
+    triangle_id: u32
+) -> ${TRIANGLE_POSITIONS_STRUCT.wgsl_ref} {
+    let header = meshlet_metadata[meshlet_id];
+
+    let attribute_offset = meshlet_compute_attribute_section_offset(header);
+
+    let index_offset = triangle_id * 3u;
+
+    // position is the first attribute of the section, three floats per vertex
+    return ${TRIANGLE_POSITIONS_STRUCT.wgsl_ref}(
+        read_meshlet_attribute_vec3f(
+            attribute_offset + min(read_meshlet_resolved_index(header, index_offset), header.vertex_count - 1u) * 3u
+        ),
+        read_meshlet_attribute_vec3f(
+            attribute_offset + min(read_meshlet_resolved_index(header, index_offset + 1u), header.vertex_count - 1u) * 3u
+        ),
+        read_meshlet_attribute_vec3f(
+            attribute_offset + min(read_meshlet_resolved_index(header, index_offset + 2u), header.vertex_count - 1u) * 3u
+        ),
+    );
+}
+`, [
+    TRIANGLE_POSITIONS_STRUCT.declaration_chunk,
+    MESHLET_METADATA_STRUCT.declaration_chunk,
+    chunk_meshlet_compute_attribute_section_offset,
+    chunk_read_meshlet_attribute_vec3f,
+    chunk_read_meshlet_resolved_index,
+]);

package/src/shade/renderer/shader/chunk/geometry/triangle/TRIANGLE_POSITIONS_STRUCT.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A triangle's three corners, positions alone.
+ * @type {WebGPUStruct}
+ */
+export const TRIANGLE_POSITIONS_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../../type/WebGPUStruct.js";
+//# sourceMappingURL=TRIANGLE_POSITIONS_STRUCT.d.ts.map

package/src/shade/renderer/shader/chunk/geometry/triangle/TRIANGLE_POSITIONS_STRUCT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TRIANGLE_POSITIONS_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/triangle/TRIANGLE_POSITIONS_STRUCT.js"],"names":[],"mappings":"AAGA;;;GAGG;AACH,wCAFU,YAAY,CAME;6BAVK,+BAA+B"}

package/src/shade/renderer/shader/chunk/geometry/triangle/TRIANGLE_POSITIONS_STRUCT.js

@@ -0,0 +1,12 @@
+import { vec3f } from "../../../type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../../type/WebGPUStruct.js";
+
+/**
+ * A triangle's three corners, positions alone.
+ * @type {WebGPUStruct}
+ */
+export const TRIANGLE_POSITIONS_STRUCT = WebGPUStruct.from({
+    a: vec3f,
+    b: vec3f,
+    c: vec3f,
+}, 'TrianglePositions');

package/src/shade/renderer/shader/chunk/grid/chunk_index_to_grid2d_reciprocal.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `index_to_grid2d` without an integer division or remainder: the row from the index times the width's
+ * reciprocal, put right by the remainder where it is one off.
+ *
+ * ```wgsl
+ * fn index_to_grid2d_reciprocal(index: u32, width: u32, reciprocal: f32) -> vec2<u32>
+ * ```
+ *
+ * `reciprocal` is 1/width rounded to f32, as `Math.fround(1 / width)` makes it on the host. The product is then
+ * the same on every device, since WGSL rounds an f32 multiplication correctly, and within one of the row for every
+ * index below 2^24. It is one under at exact multiples where the reciprocal rounds down (41 in a row of 41) and
+ * one over near the top of the range (12,583,937 in a row of 3), and the remainder's sign and size say which.
+ *
+ * Integer division and remainder by a value the compiler cannot see are emulated on AMD's RDNA2, about 12 times
+ * a float operation (measured 2026-10-17). The probe clipmap's pick addresses a depth tile a corner this way: 7%
+ * off the pass on the RDNA2 iGPU and 5.6% on an RTX 4090, the image the same to the bit.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_index_to_grid2d_reciprocal: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_index_to_grid2d_reciprocal.d.ts.map

package/src/shade/renderer/shader/chunk/grid/chunk_index_to_grid2d_reciprocal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_index_to_grid2d_reciprocal.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/grid/chunk_index_to_grid2d_reciprocal.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,+CAFU,SAAS,CAiBhB;0BApCuB,6BAA6B"}

package/src/shade/renderer/shader/chunk/grid/chunk_index_to_grid2d_reciprocal.js

@@ -0,0 +1,37 @@
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+
+/**
+ * `index_to_grid2d` without an integer division or remainder: the row from the index times the width's
+ * reciprocal, put right by the remainder where it is one off.
+ *
+ * ```wgsl
+ * fn index_to_grid2d_reciprocal(index: u32, width: u32, reciprocal: f32) -> vec2<u32>
+ * ```
+ *
+ * `reciprocal` is 1/width rounded to f32, as `Math.fround(1 / width)` makes it on the host. The product is then
+ * the same on every device, since WGSL rounds an f32 multiplication correctly, and within one of the row for every
+ * index below 2^24. It is one under at exact multiples where the reciprocal rounds down (41 in a row of 41) and
+ * one over near the top of the range (12,583,937 in a row of 3), and the remainder's sign and size say which.
+ *
+ * Integer division and remainder by a value the compiler cannot see are emulated on AMD's RDNA2, about 12 times
+ * a float operation (measured 2026-10-17). The probe clipmap's pick addresses a depth tile a corner this way: 7%
+ * off the pass on the RDNA2 iGPU and 5.6% on an RTX 4090, the image the same to the bit.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_index_to_grid2d_reciprocal = CodeChunk.from(
+    //language=WGSL
+    `
+fn index_to_grid2d_reciprocal(index: u32, width: u32, reciprocal: f32) -> vec2<u32> {
+    let estimate = u32(f32(index) * reciprocal);
+    let rest = i32(index) - i32(estimate * width);
+
+    let under = rest >= i32(width);
+    let over = rest < 0;
+
+    let x = rest - select(0, i32(width), under) + select(0, i32(width), over);
+    let y = estimate + select(0u, 1u, under) - select(0u, 1u, over);
+
+    return vec2<u32>(u32(x), y);
+}
+`);

package/src/shade/renderer/shader/chunk/light/lpv/depth/chunk_lpv_mask_weights_by_visibility.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_lpv_mask_weights_by_visibility.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/shade/renderer/shader/chunk/light/lpv/depth/chunk_lpv_mask_weights_by_visibility.js"],"names":[],"mappings":"AAOA,6DAqGO;AAKP,sEA+EO;0BA7LmB,mCAAmC"}
+{"version":3,"file":"chunk_lpv_mask_weights_by_visibility.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/shade/renderer/shader/chunk/light/lpv/depth/chunk_lpv_mask_weights_by_visibility.js"],"names":[],"mappings":"AAQA,6DAkEO;AAKP,sEA+EO;0BA3JmB,mCAAmC"}

package/src/shade/renderer/shader/chunk/light/lpv/depth/chunk_lpv_mask_weights_by_visibility.js

@@ -2,6 +2,7 @@ import {
     chunk_lpv_get_visibility_mask
 } from "../../../../../global_illumination/lpv/deprecated/chunk_lpv_get_visibility_mask.js";
 import { CodeChunk } from "../../../../compiler/CodeChunk.js";
+import { chunk_probe_visibility_weight } from "../../probe/chunk_probe_visibility_weight.js";
 import { chunk_lpv_mesh_get_vertices } from "../chunk_lpv_mesh_get_vertices.js";
 import { LPV_PROBES_RESOURCE } from "../../../../../global_illumination/probe/octahedral/LPV_SHADER_RESOURCE_GROUP.js";
 
@@ -23,70 +24,34 @@ fn lpv_mask_weights_by_visibility(
 
     for (var i = 0u; i < 4u; i++) {
 
-        var weight = 1.0;
-
         let probe_index = vertices[i];
 
         let probe = lpv_probes[probe_index];
-        
-        let probe_position = lpv_probe_get_position(probe_index);
-
-        // Smooth backface test
-        {
-
-            // Computed without the biasing applied to the "dir" variable.
-            // This test can cause reflection-map looking errors in the image
-            // (stuff looks shiny) if the transition is poor.
-            let direction_to_probe = normalize(probe_position - position);
-
-            // The naive soft backface weight would ignore a probe when
-            // it is behind the surface. That's good for walls. But for small details inside of a
-            // room, the normals on the details might rule out all of the probes that have mutual
-            // visibility to the point. So, we instead use a "wrap shading" test below inspired by
-            // NPR work.
-//            let backface_term = max(0.0001, dot(direction_to_probe, normal));
-
-            // The small offset at the end reduces the "going to zero" impact
-            // where this is really close to exactly opposite
-            let backface_term = max(0.0001, (dot(direction_to_probe, normal) + 1.0) * 0.5);
-            weight *= backface_term * backface_term + 0.2;
-
-        }
-
-        // Moment visibility test (depth)
-        {
-            // Bias the position at which visibility is computed; this
-            // avoids performing a shadow test *at* a surface, which is a
-            // dangerous location because that is exactly the line between
-            // shadowed and unshadowed. If the normal bias is too small,
-            // there will be light and dark leaks. If it is too large,
-            // then samples can pass through thin occluders to the other
-            // side (this can only happen if there are MULTIPLE occluders
-            // near each other, a wall surface won't pass through itself.)
-            
-            // see "Scaling Probe-Based Real-Time Dynamic Global Illumunation for Production" by Zander Majercik et al 
-            const TUNABLE_BIAS = 0.05;
-            let bias_scale = max(probe.distance_max * TUNABLE_BIAS, 1e-7);
-            let bias_vector = mix(normal, view_direction, 0.2) * bias_scale;
-                
-            let lookup_position = position + bias_vector;
-            
-            weight *= lpv_get_visibility_mask(lookup_position, probe_index);
-
-        }
-
-        // Avoid zero weight
-        weight = max(1e-6, weight);
 
+        let probe_position = lpv_probe_get_position(probe_index);
 
-        // A tiny bit of light is really visible due to log perception, so
-        // crush tiny weights but keep the curve continuous. This must be done
-        // before the trilinear weights, because those should be preserved.
-        const crushThreshold = 0.2;
-
-        if (weight < crushThreshold) {
-            weight *= weight * weight * (1.0 / (crushThreshold * crushThreshold));
-        }
+        // Bias the position at which visibility is computed; this
+        // avoids performing a shadow test *at* a surface, which is a
+        // dangerous location because that is exactly the line between
+        // shadowed and unshadowed. If the normal bias is too small,
+        // there will be light and dark leaks. If it is too large,
+        // then samples can pass through thin occluders to the other
+        // side (this can only happen if there are MULTIPLE occluders
+        // near each other, a wall surface won't pass through itself.)
+
+        // see "Scaling Probe-Based Real-Time Dynamic Global Illumunation for Production" by Zander Majercik et al
+        const TUNABLE_BIAS = 0.05;
+        let bias_scale = max(probe.distance_max * TUNABLE_BIAS, 1e-7);
+        let bias_vector = mix(normal, view_direction, 0.2) * bias_scale;
+
+        let lookup_position = position + bias_vector;
+
+        // the back-face term from the point itself, without the bias; the trilinear weight after the crush
+        var weight = probe_visibility_weight(
+            normalize(probe_position - position),
+            normal,
+            lpv_get_visibility_mask(lookup_position, probe_index),
+        );
 
         weight *= barycentric[i];
 
@@ -105,7 +70,8 @@ fn lpv_mask_weights_by_visibility(
 }
 `, [
         chunk_lpv_mesh_get_vertices,
-        chunk_lpv_get_visibility_mask
+        chunk_lpv_get_visibility_mask,
+        chunk_probe_visibility_weight,
     ]);
 
 chunk_lpv_mask_weights_by_visibility.requireResource(LPV_PROBES_RESOURCE);

package/src/shade/renderer/shader/chunk/light/probe/chunk_probe_visibility_weight.d.ts

@@ -0,0 +1,23 @@
+/**
+ * How much a probe's light reaches a receiving point, past the trilinear weight: the visibility terms
+ * of DDGI 2021 (Majercik et al., "Scaling Probe-Based Real-Time Dynamic Global Illumination for
+ * Production"), as LPV weighs its probes and the probe clipmap's pick weighs its corners.
+ *
+ * ```wgsl
+ * fn probe_visibility_chebyshev(moments: vec2<f32>, distance: f32) -> f32
+ * fn probe_visibility_weight(direction_to_probe: vec3<f32>, normal: vec3<f32>, visibility: f32) -> f32
+ * ```
+ *
+ * - `probe_visibility_chebyshev`: the chance the point is not occluded from the probe, by Chebyshev's
+ *   inequality over the probe's depth moments (mean, mean of squares) toward it, the distance in the
+ *   moments' own units; 1 nearer than the mean. The variance is held off zero.
+ * - `probe_visibility_weight`: a smooth back-face term, a "wrap shading" ((n·d + 1)/2)² + 0.2 that keeps
+ *   probes behind small details in play, times the visibility; then held off zero, and crushed below
+ *   0.2 along a continuous cubic, since a little light reads as more than it is. The trilinear weight
+ *   is the caller's, after the crush.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_probe_visibility_weight: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_probe_visibility_weight.d.ts.map

package/src/shade/renderer/shader/chunk/light/probe/chunk_probe_visibility_weight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_probe_visibility_weight.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/light/probe/chunk_probe_visibility_weight.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,4CAFU,SAAS,CAiChB;0BArDuB,gCAAgC"}

package/src/shade/renderer/shader/chunk/light/probe/chunk_probe_visibility_weight.js

@@ -0,0 +1,54 @@
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+
+/**
+ * How much a probe's light reaches a receiving point, past the trilinear weight: the visibility terms
+ * of DDGI 2021 (Majercik et al., "Scaling Probe-Based Real-Time Dynamic Global Illumination for
+ * Production"), as LPV weighs its probes and the probe clipmap's pick weighs its corners.
+ *
+ * ```wgsl
+ * fn probe_visibility_chebyshev(moments: vec2<f32>, distance: f32) -> f32
+ * fn probe_visibility_weight(direction_to_probe: vec3<f32>, normal: vec3<f32>, visibility: f32) -> f32
+ * ```
+ *
+ * - `probe_visibility_chebyshev`: the chance the point is not occluded from the probe, by Chebyshev's
+ *   inequality over the probe's depth moments (mean, mean of squares) toward it, the distance in the
+ *   moments' own units; 1 nearer than the mean. The variance is held off zero.
+ * - `probe_visibility_weight`: a smooth back-face term, a "wrap shading" ((n·d + 1)/2)² + 0.2 that keeps
+ *   probes behind small details in play, times the visibility; then held off zero, and crushed below
+ *   0.2 along a continuous cubic, since a little light reads as more than it is. The trilinear weight
+ *   is the caller's, after the crush.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_probe_visibility_weight = CodeChunk.from(
+    //language=WGSL
+    `
+fn probe_visibility_chebyshev(moments: vec2<f32>, distance: f32) -> f32 {
+    // http://www.punkuser.net/vsm/vsm_paper.pdf, equation 5
+    let variance = max(1e-6, abs(moments.y - moments.x * moments.x));
+    let d = distance - moments.x;
+
+    if (d <= 0.0) {
+        return 1.0;
+    }
+
+    return variance / (variance + d * d);
+}
+
+fn probe_visibility_weight(direction_to_probe: vec3<f32>, normal: vec3<f32>, visibility: f32) -> f32 {
+    // the small offset keeps a probe exactly behind the surface from going to zero
+    let backface = max(0.0001, (dot(direction_to_probe, normal) + 1.0) * 0.5);
+
+    var weight = (backface * backface + 0.2) * visibility;
+
+    weight = max(1e-6, weight);
+
+    const CRUSH = 0.2;
+
+    if (weight < CRUSH) {
+        weight *= weight * weight * (1.0 / (CRUSH * CRUSH));
+    }
+
+    return weight;
+}
+`);

package/src/shade/renderer/shader/chunk/math/chunk_f16_round_stochastic.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Each component onto a value a half float holds exactly: the half above it with the probability of how far
+ * past the half below it the component lies, else the half below. Stochastic rounding.
+ *
+ * ```wgsl
+ * fn f16_round_stochastic(v: vec4<f32>, u: vec4<f32>) -> vec4<f32>
+ * ```
+ *
+ * `u` is uniform noise in [0, 1), a component each. A component a half holds is kept whatever its noise, and
+ * the result is `v` in expectation.
+ *
+ * Stored through halves, a blend `mix(history, x, α)` then moves in expectation however small its step. Rounded,
+ * it stops short of `x` by up to a ULP/α: half of that rounded to nearest, a whole one rounded toward zero, and
+ * one-sided. WGSL leaves rounding an f32 to a half to the implementation. An RTX 4090 and an RDNA2 iGPU were
+ * measured to round toward zero on every path: `pack2x16float`, `textureStore` and a render target's write. The
+ * result here is a half already, which any store keeps exactly. UE 5.4's TSR stores its history through
+ * `QuantizeForFloatRenderTarget` for the same reason.
+ *
+ * Within the half's finite range: past 65504 the half above is not finite.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_f16_round_stochastic: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_f16_round_stochastic.d.ts.map

package/src/shade/renderer/shader/chunk/math/chunk_f16_round_stochastic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_f16_round_stochastic.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/math/chunk_f16_round_stochastic.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,yCAFU,SAAS,CAoBhB;0BA1CuB,6BAA6B"}