@woosh/meep-engine 2.165.3 → 2.165.5

package/src/engine/graphics/sh3/lpg/LightProbeGridBaker.d.ts

@@ -1,9 +1,45 @@
 export class LightProbeGridBaker {
+    /**
+     * Directions sampled one hit deep per probe. Direct light and sky converge with this count,
+     * every candidate also feeds the back-face visibility statistic.
+     *
+     * The defaults match the directional noise of the previous 4096-full-path bake at roughly half
+     * the cost (candidates are single-segment); raise both counts together for higher quality.
+     * @type {number}
+     */
+    candidate_count: number;
+    /**
+     * Full multi-bounce path traces per probe, re-sampled from the candidates by first-bounce
+     * importance. Only the indirect part of the estimate rides on these, so far fewer are needed
+     * than candidates.
+     * @type {number}
+     */
+    indirect_sample_count: number;
+    /**
+     * Total path depth including the first hit
+     * @type {number}
+     */
+    max_bounce_count: number;
+    /**
+     * GGX roughness of the prefilter cone applied to the baked radiance SH, in [0, 1].
+     * Attenuates band 1 before the 2-band truncation, suppressing directional overshoot that would
+     * otherwise reconstruct as negative irradiance (light/shadow bleeding) on the far side of a
+     * strong light. Higher values trade directionality for stability.
+     * @type {number}
+     */
+    filter_ggx_alpha: number;
+    /**
+     * A probe whose fraction of candidate rays hitting geometry back-faces exceeds this threshold is
+     * considered to be inside geometry. Such probes are filled from their valid neighbors after the
+     * bake instead of contributing interior darkness to trilinear filtering.
+     * @type {number}
+     */
+    interior_backface_threshold: number;
     /**
      * Renderer used to bake probes. Exposed so callers (and tests) can configure the underlying scene.
-     * @return {ProbeRenderer}
+     * @return {PathTracerProbeRenderer}
      */
-    get renderer(): ProbeRenderer;
+    get renderer(): PathTracerProbeRenderer;
     /**
      * Bake light probes
      * @returns {TaskGroup}
@@ -13,12 +49,15 @@ export class LightProbeGridBaker {
     bake(grid: LightProbeGrid, ecd: EntityComponentDataset): TaskGroup;
     /**
      *
-     * @param {ProbeRenderer} renderer
+     * @param {PathTracerProbeRenderer} renderer
      * @param {LightProbeGrid} grid
      * @param {number} probe_index
+     * @returns {boolean} true if the probe is valid, false if it appears to be inside geometry and
+     * should be filled from its neighbors
      */
-    bake_probe(renderer: ProbeRenderer, grid: LightProbeGrid, probe_index: number): void;
+    bake_probe(renderer: PathTracerProbeRenderer, grid: LightProbeGrid, probe_index: number): boolean;
     #private;
 }
+import { PathTracerProbeRenderer } from "../lpv/PathTracerProbeRenderer.js";
 import TaskGroup from "../../../../core/process/task/TaskGroup.js";
 //# sourceMappingURL=LightProbeGridBaker.d.ts.map

package/src/engine/graphics/sh3/lpg/LightProbeGridBaker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LightProbeGridBaker.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/lpg/LightProbeGridBaker.js"],"names":[],"mappings":"AAWA;IAII;;;OAGG;IACH,8BAEC;IAED;;;;;OAKG;IACH,yDAJa,SAAS,CA2CrB;IAED;;;;;OAKG;IACH,uEAFW,MAAM,QAYhB;;CACJ;sBArFqB,4CAA4C"}
+{"version":3,"file":"LightProbeGridBaker.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/lpg/LightProbeGridBaker.js"],"names":[],"mappings":"AAgBA;IAII;;;;;;;OAOG;IACH,iBAFU,MAAM,CAEO;IAEvB;;;;;OAKG;IACH,uBAFU,MAAM,CAEY;IAE5B;;;OAGG;IACH,kBAFU,MAAM,CAEK;IAErB;;;;;;OAMG;IACH,kBAFU,MAAM,CAEO;IAEvB;;;;;OAKG;IACH,6BAFU,MAAM,CAEmB;IAEnC;;;OAGG;IACH,wCAEC;IAED;;;;;OAKG;IACH,yDAJa,SAAS,CAoDrB;IAED;;;;;;;OAOG;IACH,qBANW,uBAAuB,qCAEvB,MAAM,GACJ,OAAO,CAuBnB;;CACJ;wCAlJuC,mCAAmC;sBAJrD,4CAA4C"}

package/src/engine/graphics/sh3/lpg/LightProbeGridBaker.js

@@ -1,21 +1,67 @@
 import { assert } from "../../../../core/assert.js";
 import { array_copy } from "../../../../core/collection/array/array_copy.js";
+import { sh3_convolve_with_zh } from "../../../../core/geom/3d/sphere/harmonics/sh3_convolve_with_zh.js";
+import { sh3_ggx_zh } from "../../../../core/geom/3d/sphere/harmonics/sh3_ggx_zh.js";
 import TaskGroup from "../../../../core/process/task/TaskGroup.js";
 import { actionTask } from "../../../../core/process/task/util/actionTask.js";
 import { countTask } from "../../../../core/process/task/util/countTask.js";
 import { promiseTask } from "../../../../core/process/task/util/promiseTask.js";
 import { PathTracerProbeRenderer } from "../lpv/PathTracerProbeRenderer.js";
+import { bake_probe_sh3_resampled } from "./bake_probe_sh3_resampled.js";
+import { light_probe_grid_dilate } from "./light_probe_grid_dilate.js";
 
 const __position = new Float32Array(3);
 const __sh3_rgb = new Float64Array(27);
+const __zh = new Float64Array(3);
 
 export class LightProbeGridBaker {
 
     #ren = new PathTracerProbeRenderer();
 
+    /**
+     * Directions sampled one hit deep per probe. Direct light and sky converge with this count,
+     * every candidate also feeds the back-face visibility statistic.
+     *
+     * The defaults match the directional noise of the previous 4096-full-path bake at roughly half
+     * the cost (candidates are single-segment); raise both counts together for higher quality.
+     * @type {number}
+     */
+    candidate_count = 2048;
+
+    /**
+     * Full multi-bounce path traces per probe, re-sampled from the candidates by first-bounce
+     * importance. Only the indirect part of the estimate rides on these, so far fewer are needed
+     * than candidates.
+     * @type {number}
+     */
+    indirect_sample_count = 512;
+
+    /**
+     * Total path depth including the first hit
+     * @type {number}
+     */
+    max_bounce_count = 5;
+
+    /**
+     * GGX roughness of the prefilter cone applied to the baked radiance SH, in [0, 1].
+     * Attenuates band 1 before the 2-band truncation, suppressing directional overshoot that would
+     * otherwise reconstruct as negative irradiance (light/shadow bleeding) on the far side of a
+     * strong light. Higher values trade directionality for stability.
+     * @type {number}
+     */
+    filter_ggx_alpha = 0.5;
+
+    /**
+     * A probe whose fraction of candidate rays hitting geometry back-faces exceeds this threshold is
+     * considered to be inside geometry. Such probes are filled from their valid neighbors after the
+     * bake instead of contributing interior darkness to trilinear filtering.
+     * @type {number}
+     */
+    interior_backface_threshold = 0.25;
+
     /**
      * Renderer used to bake probes. Exposed so callers (and tests) can configure the underlying scene.
-     * @return {ProbeRenderer}
+     * @return {PathTracerProbeRenderer}
      */
     get renderer() {
         return this.#ren;
@@ -40,8 +86,10 @@ export class LightProbeGridBaker {
 
         const probe_count = grid.count;
 
+        const validity = new Uint8Array(probe_count);
+
         const tBakeIrradiance = countTask(0, probe_count, (probe_index) => {
-            this.bake_probe(renderer, grid, probe_index);
+            validity[probe_index] = this.bake_probe(renderer, grid, probe_index) ? 1 : 0;
 
         });
         tBakeIrradiance.estimatedDuration = probe_count;
@@ -57,6 +105,13 @@ export class LightProbeGridBaker {
         const tFinish = actionTask(() => {
             renderer.bake_end();
 
+            // probes inside geometry take on the average of their valid neighbors, so trilinear
+            // sampling near walls does not blend in interior darkness
+            light_probe_grid_dilate(
+                grid.harmonics, validity,
+                grid.resolution_x, grid.resolution_y, grid.resolution_z
+            );
+
             grid.incrementVersion();
         });
 
@@ -70,19 +125,31 @@ export class LightProbeGridBaker {
 
     /**
      *
-     * @param {ProbeRenderer} renderer
+     * @param {PathTracerProbeRenderer} renderer
      * @param {LightProbeGrid} grid
      * @param {number} probe_index
+     * @returns {boolean} true if the probe is valid, false if it appears to be inside geometry and
+     * should be filled from its neighbors
      */
     bake_probe(renderer, grid, probe_index) {
         assert.isNonNegativeInteger(probe_index, 'probe_index');
 
         grid.probe_position(__position, 0, probe_index);
 
-        // render a full SH3 probe with the shared facilities
-        renderer.bake(__position, 0, __sh3_rgb, 0);
+        const backface_fraction = bake_probe_sh3_resampled(
+            __sh3_rgb, 0,
+            renderer.scene, renderer.tracer, renderer.random,
+            __position, 0,
+            this.candidate_count, this.indirect_sample_count, this.max_bounce_count
+        );
+
+        // prefilter the radiance with a GGX cone before truncation, taming band-1 overshoot
+        sh3_ggx_zh(__zh, 0, this.filter_ggx_alpha);
+        sh3_convolve_with_zh(__sh3_rgb, 0, __sh3_rgb, 0, __zh[0], __zh[1], __zh[2], 3);
 
         // keep only bands 0 and 1: the coefficient-major layout puts them in the first 12 values
         array_copy(__sh3_rgb, 0, grid.harmonics, probe_index * 12, 12);
+
+        return backface_fraction <= this.interior_backface_threshold;
     }
 }

package/src/engine/graphics/sh3/lpg/bake_probe_sh3_resampled.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Bake a single SH3 radiance probe with importance re-sampling and back-face visibility rejection.
+ *
+ * Two-phase estimator, split by path length:
+ *
+ * 1. Candidate phase: `candidate_count` uniform sphere directions are traced one hit deep. Misses
+ *    take the background radiance; front-face hits take `emissive + albedo * direct_light`, both of
+ *    which are cheap and low-noise, and every such sample is projected onto the SH. Directions whose
+ *    first hit is a back face see the inside of geometry — they are rejected and the estimate is
+ *    renormalized over the remaining directions, so interior darkness does not bleed into the probe.
+ *
+ * 2. Indirect phase: `indirect_sample_count` continuations are picked from the hit candidates with
+ *    probability proportional to their first-bounce luminance (resampled importance sampling — the
+ *    selection a weighted reservoir would produce, drawn from the materialized candidate table), and
+ *    only these few directions pay for a full multi-bounce path trace. The 1/p_hat re-sampling weight
+ *    keeps the combined estimator unbiased.
+ *
+ * The two phases sum to the same integral as tracing every direction to full depth, but direct light
+ * converges with the full candidate count while the expensive multi-bounce work is spent where the
+ * first bounce found energy.
+ *
+ * @param {number[]|Float32Array|Float64Array} out 27 values: SH3 radiance, coefficient-major RGB triplets
+ * @param {number} out_offset
+ * @param {PathTracedScene} scene
+ * @param {PathTracer} tracer
+ * @param {function():number} random
+ * @param {number[]|Float32Array} position probe position
+ * @param {number} position_offset
+ * @param {number} candidate_count directions sampled one hit deep, at least 1
+ * @param {number} indirect_sample_count full path-traced continuations re-sampled from the candidates
+ * @param {number} max_bounce_count total path depth including the first hit, at least 1
+ * @returns {number} fraction of candidate directions whose first hit was a back face, in [0, 1]
+ */
+export function bake_probe_sh3_resampled(out: number[] | Float32Array | Float64Array, out_offset: number, scene: PathTracedScene, tracer: PathTracer, random: () => number, position: number[] | Float32Array, position_offset: number, candidate_count: number, indirect_sample_count: number, max_bounce_count: number): number;
+import { PathTracedScene } from "../path_tracer/PathTracedScene.js";
+import { PathTracer } from "../path_tracer/PathTracer.js";
+//# sourceMappingURL=bake_probe_sh3_resampled.d.ts.map

package/src/engine/graphics/sh3/lpg/bake_probe_sh3_resampled.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bake_probe_sh3_resampled.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/lpg/bake_probe_sh3_resampled.js"],"names":[],"mappings":"AAyEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,8CAZW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,SACN,eAAe,UACf,UAAU,gBACC,MAAM,YACjB,MAAM,EAAE,GAAC,YAAY,mBACrB,MAAM,mBACN,MAAM,yBACN,MAAM,oBACN,MAAM,GACJ,MAAM,CAiMlB;gCAlS+B,mCAAmC;2BACjB,8BAA8B"}

package/src/engine/graphics/sh3/lpg/bake_probe_sh3_resampled.js

@@ -0,0 +1,298 @@
+import { assert } from "../../../../core/assert.js";
+import { rgb_to_luminance } from "../../../../core/color/rgb_to_luminance.js";
+import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
+import { sh3_basis_at } from "../../../../core/geom/3d/sphere/harmonics/sh3_basis_at.js";
+import { sh3_vector_accumulate } from "../../../../core/geom/3d/sphere/harmonics/sh3_vector_accumulate.js";
+import { random_point_on_sphere } from "../../../../core/geom/random/random_point_on_sphere.js";
+import { v3_dot } from "../../../../core/geom/vec3/v3_dot.js";
+import { PathTracedScene } from "../path_tracer/PathTracedScene.js";
+import { PathTracer, SELF_OCCLUSION_OFFSET } from "../path_tracer/PathTracer.js";
+import { getBiasedNormalSample } from "../path_tracer/sampling/getBiasedNormalSample.js";
+
+/**
+ * Per-candidate record: direction(3), offset surface position(3), shading normal(3), albedo(3)
+ * @type {number}
+ */
+const CANDIDATE_STRIDE = 12;
+
+/**
+ * Fraction of the mean candidate luminance added to every re-sampling weight. Keeps surfaces that
+ * receive no direct light selectable — they may still return indirect radiance — so the estimator
+ * stays unbiased.
+ * @type {number}
+ */
+const RESAMPLING_WEIGHT_FLOOR = 0.1;
+
+const __ray = new Ray3();
+const __hit = [];
+const __surface = new Float32Array(9);
+const __direct = new Float32Array(3);
+const __radiance = new Float32Array(3);
+const __basis = new Float64Array(9);
+const __sh_direct = new Float64Array(27);
+const __sh_indirect = new Float64Array(27);
+
+let __candidates = new Float32Array(0);
+let __p_hat = new Float64Array(0);
+let __cumulative_p_hat = new Float64Array(0);
+
+/**
+ *
+ * @param {number} candidate_count
+ */
+function ensure_pool_capacity(candidate_count) {
+    if (__p_hat.length < candidate_count) {
+        __candidates = new Float32Array(candidate_count * CANDIDATE_STRIDE);
+        __p_hat = new Float64Array(candidate_count);
+        __cumulative_p_hat = new Float64Array(candidate_count);
+    }
+}
+
+/**
+ * Index of the candidate owning the cumulative-weight interval that contains `value`
+ * @param {number} value in [0, cumulative[count - 1])
+ * @param {number} count
+ * @returns {number}
+ */
+function pick_candidate(value, count) {
+    let low = 0;
+    let high = count - 1;
+
+    while (low < high) {
+        const mid = (low + high) >> 1;
+
+        if (__cumulative_p_hat[mid] > value) {
+            high = mid;
+        } else {
+            low = mid + 1;
+        }
+    }
+
+    return low;
+}
+
+/**
+ * Bake a single SH3 radiance probe with importance re-sampling and back-face visibility rejection.
+ *
+ * Two-phase estimator, split by path length:
+ *
+ * 1. Candidate phase: `candidate_count` uniform sphere directions are traced one hit deep. Misses
+ *    take the background radiance; front-face hits take `emissive + albedo * direct_light`, both of
+ *    which are cheap and low-noise, and every such sample is projected onto the SH. Directions whose
+ *    first hit is a back face see the inside of geometry — they are rejected and the estimate is
+ *    renormalized over the remaining directions, so interior darkness does not bleed into the probe.
+ *
+ * 2. Indirect phase: `indirect_sample_count` continuations are picked from the hit candidates with
+ *    probability proportional to their first-bounce luminance (resampled importance sampling — the
+ *    selection a weighted reservoir would produce, drawn from the materialized candidate table), and
+ *    only these few directions pay for a full multi-bounce path trace. The 1/p_hat re-sampling weight
+ *    keeps the combined estimator unbiased.
+ *
+ * The two phases sum to the same integral as tracing every direction to full depth, but direct light
+ * converges with the full candidate count while the expensive multi-bounce work is spent where the
+ * first bounce found energy.
+ *
+ * @param {number[]|Float32Array|Float64Array} out 27 values: SH3 radiance, coefficient-major RGB triplets
+ * @param {number} out_offset
+ * @param {PathTracedScene} scene
+ * @param {PathTracer} tracer
+ * @param {function():number} random
+ * @param {number[]|Float32Array} position probe position
+ * @param {number} position_offset
+ * @param {number} candidate_count directions sampled one hit deep, at least 1
+ * @param {number} indirect_sample_count full path-traced continuations re-sampled from the candidates
+ * @param {number} max_bounce_count total path depth including the first hit, at least 1
+ * @returns {number} fraction of candidate directions whose first hit was a back face, in [0, 1]
+ */
+export function bake_probe_sh3_resampled(
+    out, out_offset,
+    scene, tracer, random,
+    position, position_offset,
+    candidate_count, indirect_sample_count, max_bounce_count
+) {
+    assert.isArrayLike(out, 'out');
+    assert.isNonNegativeInteger(out_offset, 'out_offset');
+    assert.isInstanceOf(scene, PathTracedScene, 'scene');
+    assert.isInstanceOf(tracer, PathTracer, 'tracer');
+    assert.isFunction(random, 'random');
+    assert.isArrayLike(position, 'position');
+    assert.isNonNegativeInteger(position_offset, 'position_offset');
+    assert.isNonNegativeInteger(candidate_count, 'candidate_count');
+    assert.greaterThan(candidate_count, 0, 'candidate_count');
+    assert.isNonNegativeInteger(indirect_sample_count, 'indirect_sample_count');
+    assert.isNonNegativeInteger(max_bounce_count, 'max_bounce_count');
+    assert.greaterThan(max_bounce_count, 0, 'max_bounce_count');
+
+    ensure_pool_capacity(candidate_count);
+
+    __sh_direct.fill(0);
+    __sh_indirect.fill(0);
+
+    const position_x = position[position_offset];
+    const position_y = position[position_offset + 1];
+    const position_z = position[position_offset + 2];
+
+    let hit_count = 0;
+    let valid_count = 0;
+    let backface_count = 0;
+    let luminance_sum = 0;
+
+    for (let i = 0; i < candidate_count; i++) {
+
+        __ray[0] = position_x;
+        __ray[1] = position_y;
+        __ray[2] = position_z;
+
+        random_point_on_sphere(random, __ray, 3);
+
+        __ray.tMax = Infinity;
+
+        const direction_x = __ray[3];
+        const direction_y = __ray[4];
+        const direction_z = __ray[5];
+
+        const hit_distance = scene.trace(__hit, __ray);
+
+        if (hit_distance < 0) {
+            // sky
+            scene.sample_background(__radiance, 0, __ray, 3);
+        } else if (v3_dot(
+            __hit[3], __hit[4], __hit[5],
+            direction_x, direction_y, direction_z
+        ) > 0) {
+            // the first hit is a back face: this direction sees the inside of geometry
+            backface_count++;
+            continue;
+        } else {
+            scene.sample_material(__surface, __hit, __ray);
+
+            // stage the surface state in the ray: origin at the hit, direction holding the shading
+            // normal, then step off the surface along the normal — mirrors PathTracer exactly, so
+            // shadow rays and continuations start from the same offset point the tracer would use
+            __ray[0] = __hit[0];
+            __ray[1] = __hit[1];
+            __ray[2] = __hit[2];
+
+            __ray[3] = __surface[3];
+            __ray[4] = __surface[4];
+            __ray[5] = __surface[5];
+
+            const origin_magnitude = Math.max(Math.abs(__ray[0]), Math.abs(__ray[1]), Math.abs(__ray[2]));
+            __ray.shiftForward(SELF_OCCLUSION_OFFSET * Math.max(1, origin_magnitude));
+
+            scene.sample_lights(__direct, 0, __ray);
+
+            // first-bounce radiance: emission plus albedo-modulated direct light
+            __radiance[0] = __surface[6] + __surface[0] * __direct[0];
+            __radiance[1] = __surface[7] + __surface[1] * __direct[1];
+            __radiance[2] = __surface[8] + __surface[2] * __direct[2];
+
+            // record the candidate for indirect re-sampling
+            const candidate_address = hit_count * CANDIDATE_STRIDE;
+
+            __candidates[candidate_address] = direction_x;
+            __candidates[candidate_address + 1] = direction_y;
+            __candidates[candidate_address + 2] = direction_z;
+
+            __candidates[candidate_address + 3] = __ray[0];
+            __candidates[candidate_address + 4] = __ray[1];
+            __candidates[candidate_address + 5] = __ray[2];
+
+            __candidates[candidate_address + 6] = __surface[3];
+            __candidates[candidate_address + 7] = __surface[4];
+            __candidates[candidate_address + 8] = __surface[5];
+
+            __candidates[candidate_address + 9] = __surface[0];
+            __candidates[candidate_address + 10] = __surface[1];
+            __candidates[candidate_address + 11] = __surface[2];
+
+            const luminance = rgb_to_luminance(__radiance[0], __radiance[1], __radiance[2]);
+
+            __p_hat[hit_count] = luminance;
+            luminance_sum += luminance;
+
+            hit_count++;
+        }
+
+        valid_count++;
+
+        sh3_basis_at(direction_x, direction_y, direction_z, __basis);
+        sh3_vector_accumulate(__sh_direct, 0, __basis, 0, __radiance, 0, 3);
+    }
+
+    const backface_fraction = backface_count / candidate_count;
+
+    if (valid_count === 0) {
+        // probe is fully embedded in geometry, there is no usable radiance
+        for (let i = 0; i < 27; i++) {
+            out[out_offset + i] = 0;
+        }
+
+        return backface_fraction;
+    }
+
+    let total_p_hat = 0;
+
+    if (max_bounce_count > 1 && indirect_sample_count > 0 && hit_count > 0) {
+
+        // floor the weights so indirectly-lit surfaces stay selectable; when nothing received any
+        // direct light the selection degenerates to uniform (selection is scale-invariant in p_hat)
+        const mean_luminance = luminance_sum / hit_count;
+        const weight_floor = mean_luminance > 0 ? mean_luminance * RESAMPLING_WEIGHT_FLOOR : 1;
+
+        for (let i = 0; i < hit_count; i++) {
+            const p_hat = __p_hat[i] + weight_floor;
+
+            __p_hat[i] = p_hat;
+            total_p_hat += p_hat;
+
+            __cumulative_p_hat[i] = total_p_hat;
+        }
+
+        for (let k = 0; k < indirect_sample_count; k++) {
+            const pick = pick_candidate(random() * total_p_hat, hit_count);
+
+            const candidate_address = pick * CANDIDATE_STRIDE;
+
+            __ray[0] = __candidates[candidate_address + 3];
+            __ray[1] = __candidates[candidate_address + 4];
+            __ray[2] = __candidates[candidate_address + 5];
+
+            // cosine-weighted continuation about the shading normal, matching the tracer's own
+            // bounce sampling; the albedo/pi BRDF and the cosine/pi pdf cancel to a bare albedo scale
+            getBiasedNormalSample(__ray, 3, __candidates, candidate_address + 6, 1, random);
+
+            __ray.tMax = Infinity;
+
+            tracer.path_trace(__radiance, __ray, 1, max_bounce_count - 1, random, scene);
+
+            const resampling_weight = 1 / __p_hat[pick];
+
+            __radiance[0] *= __candidates[candidate_address + 9] * resampling_weight;
+            __radiance[1] *= __candidates[candidate_address + 10] * resampling_weight;
+            __radiance[2] *= __candidates[candidate_address + 11] * resampling_weight;
+
+            sh3_basis_at(
+                __candidates[candidate_address],
+                __candidates[candidate_address + 1],
+                __candidates[candidate_address + 2],
+                __basis
+            );
+            sh3_vector_accumulate(__sh_indirect, 0, __basis, 0, __radiance, 0, 3);
+        }
+    }
+
+    // back-face directions are excluded from the domain: normalizing by the valid count spreads the
+    // radiance of the visible directions over the full sphere, so partially embedded probes represent
+    // the open side instead of averaging in interior darkness
+    const direct_scale = (4 * Math.PI) / valid_count;
+    const indirect_scale = indirect_sample_count > 0
+        ? direct_scale * (total_p_hat / indirect_sample_count)
+        : 0;
+
+    for (let i = 0; i < 27; i++) {
+        out[out_offset + i] = __sh_direct[i] * direct_scale + __sh_indirect[i] * indirect_scale;
+    }
+
+    return backface_fraction;
+}

package/src/engine/graphics/sh3/lpg/light_probe_grid_dilate.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Fill invalid probes with the average of their valid 6-connected neighbors, expanding in waves until
+ * every reachable probe is filled.
+ *
+ * Probes marked invalid (typically because they sit inside geometry) would otherwise contribute their
+ * meaningless data to hardware trilinear filtering and bleed darkness across walls. Each pass reads
+ * only probes that were valid before the pass started, so the result is independent of traversal
+ * order. Probes with no valid probe anywhere in their connected region are left untouched.
+ *
+ * @param {Float32Array} harmonics probe data, {@link PROBE_VALUE_COUNT} values per probe; filled probes are written in place
+ * @param {Uint8Array} validity one flag per probe, non-zero = valid; filled probes are marked valid in place
+ * @param {number} resolution_x
+ * @param {number} resolution_y
+ * @param {number} resolution_z
+ * @returns {number} number of probes that remained invalid
+ */
+export function light_probe_grid_dilate(harmonics: Float32Array, validity: Uint8Array, resolution_x: number, resolution_y: number, resolution_z: number): number;
+//# sourceMappingURL=light_probe_grid_dilate.d.ts.map

package/src/engine/graphics/sh3/lpg/light_probe_grid_dilate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"light_probe_grid_dilate.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/lpg/light_probe_grid_dilate.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;GAeG;AACH,mDAPW,YAAY,YACZ,UAAU,gBACV,MAAM,gBACN,MAAM,gBACN,MAAM,GACJ,MAAM,CAsGlB"}