@woosh/meep-engine 2.164.0 → 2.165.0

package/src/engine/graphics/sh3/lightmap/lightmap_build_geometry.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Build a renderable {@link BufferGeometry} from a mesh's packed lightmap charts.
+ *
+ * The charts are a re-indexed triangle soup: each chart owns its own local
+ * vertices (seam vertices are duplicated between charts, which is exactly what is
+ * needed so each side of a seam carries its own atlas UV). We concatenate every
+ * chart's vertices into one indexed geometry, writing:
+ *  - `position` from {@link Chart#positions} (object-local 3D coordinates),
+ *  - `uv2` from {@link Chart#uv} (atlas-space lightmap coordinates, post-pack),
+ *  - `normal` carried per triangle from the SOURCE mesh's normals when available
+ *    (continuous across chart seams), falling back to a geometric normal only for
+ *    triangles that don't map back cleanly (see {@link accumulate_normals}).
+ *
+ * @param {Chart[]} charts the mesh's charts, already packed (atlas-space `uv`)
+ * @param {Float32Array|number[]} [source_normals] source per-vertex normals (flat xyz)
+ * @param {ArrayLike<number>} [source_indices] source triangle index buffer
+ * @returns {{
+ *   geometry: BufferGeometry,
+ *   positions: Float32Array,
+ *   normals: Float32Array,
+ *   chart_vertex_offset: Uint32Array
+ * }} the geometry plus the backing position/normal arrays and the per-chart
+ *   starting vertex offset (for callers that still need to walk the charts)
+ */
+export function lightmap_build_geometry(charts: Chart[], source_normals?: Float32Array | number[], source_indices?: ArrayLike<number>): {
+    geometry: BufferGeometry;
+    positions: Float32Array;
+    normals: Float32Array;
+    chart_vertex_offset: Uint32Array;
+};
+import { BufferGeometry } from "three";
+//# sourceMappingURL=lightmap_build_geometry.d.ts.map

package/src/engine/graphics/sh3/lightmap/lightmap_build_geometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lightmap_build_geometry.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/lightmap/lightmap_build_geometry.js"],"names":[],"mappings":"AAkEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,gDAXW,OAAO,mBACP,YAAY,GAAC,MAAM,EAAE,mBACrB,UAAU,MAAM,CAAC;cAEb,cAAc;eACb,YAAY;aACd,YAAY;yBACA,WAAW;EAoEpC;+BA1J+C,OAAO"}

package/src/engine/graphics/sh3/lightmap/lightmap_build_geometry.js

@@ -0,0 +1,155 @@
+import { BufferAttribute, BufferGeometry } from "three";
+import { v3_add_array } from "../../../../core/geom/vec3/v3_add_array.js";
+import { geometry_construct_triangle_normal } from "../../geometry/geometry_construct_triangle_normal.js";
+import { v3_array_normalize_many } from "../../geometry/buffered/v3_array_normalize_many.js";
+
+const _tri_normal = new Float64Array(3);
+
+/**
+ * Accumulate per-vertex normals onto the concatenated chart vertices, then the
+ * caller normalizes. Each triangle carries the SOURCE mesh's per-corner normals
+ * (via its source face id) when it maps cleanly back — so a seam vertex gets the
+ * same normal on both sides of a chart boundary (continuous shading) while hard
+ * edges keep their per-face normals. A triangle that does NOT map cleanly (e.g. a
+ * weld T-junction split created a face beyond the source range) falls back to its
+ * own geometric normal — PER TRIANGLE, so one bad face never discards authored
+ * normals for the rest of the mesh. With no source normals at all, every triangle
+ * takes the geometric path (equivalent to recomputing vertex normals).
+ *
+ * @param {Chart[]} charts
+ * @param {Uint32Array} chart_vertex_offset
+ * @param {Float32Array} normals destination (zero-initialised), accumulated then normalized by caller
+ * @param {Float32Array|number[]|null} source_normals source per-vertex normals (flat xyz), or null
+ * @param {ArrayLike<number>|null} source_indices source triangle index buffer, or null
+ */
+function accumulate_normals(charts, chart_vertex_offset, normals, source_normals, source_indices) {
+    const have_source = source_normals != null && source_indices != null;
+    const index_count = have_source ? source_indices.length : 0;
+    const normal_count = have_source ? source_normals.length : 0;
+
+    for (let ci = 0; ci < charts.length; ci++) {
+        const chart = charts[ci];
+        const offset = chart_vertex_offset[ci];
+        const tri_local = chart.tri_local;
+        const tri_face = chart.tri_face;
+        const chart_positions = chart.positions;
+        const triangle_count = chart.triangle_count;
+
+        for (let t = 0; t < triangle_count; t++) {
+            const la = tri_local[t * 3];
+            const lb = tri_local[t * 3 + 1];
+            const lc = tri_local[t * 3 + 2];
+
+            let carried = false;
+            if (have_source) {
+                const fi = tri_face[t] * 3;
+                if (fi + 2 < index_count) {
+                    const o0 = source_indices[fi], o1 = source_indices[fi + 1], o2 = source_indices[fi + 2];
+                    if (o0 * 3 + 2 < normal_count && o1 * 3 + 2 < normal_count && o2 * 3 + 2 < normal_count) {
+                        v3_add_array(normals, (offset + la) * 3, source_normals, o0 * 3);
+                        v3_add_array(normals, (offset + lb) * 3, source_normals, o1 * 3);
+                        v3_add_array(normals, (offset + lc) * 3, source_normals, o2 * 3);
+                        carried = true;
+                    }
+                }
+            }
+
+            if (!carried) {
+                geometry_construct_triangle_normal(_tri_normal, 0, la, lb, lc, chart_positions);
+                v3_add_array(normals, (offset + la) * 3, _tri_normal, 0);
+                v3_add_array(normals, (offset + lb) * 3, _tri_normal, 0);
+                v3_add_array(normals, (offset + lc) * 3, _tri_normal, 0);
+            }
+        }
+    }
+}
+
+/**
+ * Build a renderable {@link BufferGeometry} from a mesh's packed lightmap charts.
+ *
+ * The charts are a re-indexed triangle soup: each chart owns its own local
+ * vertices (seam vertices are duplicated between charts, which is exactly what is
+ * needed so each side of a seam carries its own atlas UV). We concatenate every
+ * chart's vertices into one indexed geometry, writing:
+ *  - `position` from {@link Chart#positions} (object-local 3D coordinates),
+ *  - `uv2` from {@link Chart#uv} (atlas-space lightmap coordinates, post-pack),
+ *  - `normal` carried per triangle from the SOURCE mesh's normals when available
+ *    (continuous across chart seams), falling back to a geometric normal only for
+ *    triangles that don't map back cleanly (see {@link accumulate_normals}).
+ *
+ * @param {Chart[]} charts the mesh's charts, already packed (atlas-space `uv`)
+ * @param {Float32Array|number[]} [source_normals] source per-vertex normals (flat xyz)
+ * @param {ArrayLike<number>} [source_indices] source triangle index buffer
+ * @returns {{
+ *   geometry: BufferGeometry,
+ *   positions: Float32Array,
+ *   normals: Float32Array,
+ *   chart_vertex_offset: Uint32Array
+ * }} the geometry plus the backing position/normal arrays and the per-chart
+ *   starting vertex offset (for callers that still need to walk the charts)
+ */
+export function lightmap_build_geometry(charts, source_normals, source_indices) {
+    let vertex_total = 0;
+    let triangle_total = 0;
+
+    const chart_count = charts.length;
+    const chart_vertex_offset = new Uint32Array(chart_count);
+
+    for (let i = 0; i < chart_count; i++) {
+        chart_vertex_offset[i] = vertex_total;
+        vertex_total += charts[i].vertex_count;
+        triangle_total += charts[i].triangle_count;
+    }
+
+    const positions = new Float32Array(vertex_total * 3);
+    const uv2 = new Float32Array(vertex_total * 2);
+    const normals = new Float32Array(vertex_total * 3);
+    const indices = new Uint32Array(triangle_total * 3);
+
+    let index_cursor = 0;
+
+    for (let i = 0; i < chart_count; i++) {
+        const chart = charts[i];
+        const vertex_offset = chart_vertex_offset[i];
+
+        const chart_positions = chart.positions;
+        const chart_uv = chart.uv;
+        const vertex_count = chart.vertex_count;
+
+        for (let v = 0; v < vertex_count; v++) {
+            const dst3 = (vertex_offset + v) * 3;
+            const src3 = v * 3;
+            positions[dst3] = chart_positions[src3];
+            positions[dst3 + 1] = chart_positions[src3 + 1];
+            positions[dst3 + 2] = chart_positions[src3 + 2];
+
+            const dst2 = (vertex_offset + v) * 2;
+            const src2 = v * 2;
+            uv2[dst2] = chart_uv[src2];
+            uv2[dst2 + 1] = chart_uv[src2 + 1];
+        }
+
+        const tri_local = chart.tri_local;
+        const corner_count = chart.triangle_count * 3;
+        for (let k = 0; k < corner_count; k++) {
+            indices[index_cursor++] = tri_local[k] + vertex_offset;
+        }
+    }
+
+    accumulate_normals(charts, chart_vertex_offset, normals, source_normals, source_indices);
+    v3_array_normalize_many(normals);
+
+    const geometry = new BufferGeometry();
+    geometry.setAttribute('position', new BufferAttribute(positions, 3));
+    geometry.setAttribute('normal', new BufferAttribute(normals, 3));
+    geometry.setAttribute('uv2', new BufferAttribute(uv2, 2));
+    geometry.setIndex(new BufferAttribute(indices, 1));
+
+    // Compute the bounding box up front so the geometry is render-ready: consumers that cull / refit bounds
+    // (e.g. ShadedGeometry.update_bounds → aabb3_from_three_geometry) require boundingBox to be non-null. Without
+    // this, a baked mesh that later moves (its Transform changes) hits a null boundingBox on the bounds refit and
+    // its cull leaf goes stale — the object gets frustum-culled at its new pose.
+    geometry.computeBoundingBox();
+
+    return { geometry, positions, normals, chart_vertex_offset };
+}

package/src/engine/graphics/sh3/lightmap/lightmap_denoise.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Variance-guided, normal-aware, edge-preserving denoise of a baked lightmap —
+ * NOT a blind blur.
+ *
+ * For each covered texel it forms a weighted average of its covered neighbours in
+ * a small window, where each neighbour's weight is the product of three terms:
+ *  - **spatial** — a Gaussian in texel distance (closer counts more);
+ *  - **range** — gated by the Monte-Carlo noise level: the luminance difference is
+ *    measured against the combined per-texel noise stddev
+ *    `sqrt(var_center + var_neighbour)`, so differences consistent with noise blend
+ *    away while real lighting gradients are preserved;
+ *  - **normal** — `pow(max(0, dot(n_center, n_neighbour)), normal_power)`, so the
+ *    filter never blurs across an angular discontinuity. Atlas-adjacency does not
+ *    imply surface-adjacency: a box's two faces, or two unrelated charts packed
+ *    near each other across a thin gutter, must not bleed into one another. A 90°
+ *    crease (`dot = 0`) is fully stopped; smooth curvature (`dot ≈ 1`) blends.
+ *
+ * **Boundary-aware:** a texel at a chart edge (or next to a crease) has a
+ * truncated, one-sided support, whose average is biased. The denoised value is
+ * blended back toward the texel's own value in proportion to how incomplete its
+ * support is (fraction of the window that actually contributed), so edges keep
+ * their unbiased — if noisier — value instead of being pulled toward the
+ * available (darker/brighter) side.
+ *
+ * Writes filtered values for covered texels into `out`; uncovered texels are left
+ * as-is in `out` (the caller dilates them afterwards). `out` must be a distinct
+ * buffer from `data`.
+ *
+ * @param {Float32Array} out destination, same layout as `data` (distinct buffer)
+ * @param {Float32Array} data source pixels, row-major, stride `channels`
+ * @param {Float32Array} variance per-texel luminance variance-of-mean, length width*height
+ * @param {Float32Array} normals per-texel world normal (3 per texel), length width*height*3
+ * @param {Uint8Array} coverage per-texel coverage (1 = valid), length width*height
+ * @param {number} width
+ * @param {number} height
+ * @param {number} channels values per texel (rgb[+a])
+ * @param {object} [options]
+ * @param {number} [options.radius] window half-size in texels (default 2)
+ * @param {number} [options.spatial_sigma] spatial Gaussian sigma in texels (default 1.5)
+ * @param {number} [options.beta] noise tolerance: how many stddevs count as "still noise" (default 3)
+ * @param {number} [options.normal_power] sharpness of the normal-similarity cutoff (default 8)
+ */
+export function lightmap_denoise(out: Float32Array, data: Float32Array, variance: Float32Array, normals: Float32Array, coverage: Uint8Array, width: number, height: number, channels: number, options?: {
+    radius?: number;
+    spatial_sigma?: number;
+    beta?: number;
+    normal_power?: number;
+}): void;
+//# sourceMappingURL=lightmap_denoise.d.ts.map

package/src/engine/graphics/sh3/lightmap/lightmap_denoise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lightmap_denoise.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/lightmap/lightmap_denoise.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,sCAdW,YAAY,QACZ,YAAY,YACZ,YAAY,WACZ,YAAY,YACZ,UAAU,SACV,MAAM,UACN,MAAM,YACN,MAAM;IAEW,MAAM,GAAvB,MAAM;IACW,aAAa,GAA9B,MAAM;IACW,IAAI,GAArB,MAAM;IACW,YAAY,GAA7B,MAAM;SA6FhB"}

package/src/engine/graphics/sh3/lightmap/lightmap_denoise.js

@@ -0,0 +1,136 @@
+import { rgb_to_luminance } from "../../../../core/color/rgb_to_luminance.js";
+
+/**
+ * Variance-guided, normal-aware, edge-preserving denoise of a baked lightmap —
+ * NOT a blind blur.
+ *
+ * For each covered texel it forms a weighted average of its covered neighbours in
+ * a small window, where each neighbour's weight is the product of three terms:
+ *  - **spatial** — a Gaussian in texel distance (closer counts more);
+ *  - **range** — gated by the Monte-Carlo noise level: the luminance difference is
+ *    measured against the combined per-texel noise stddev
+ *    `sqrt(var_center + var_neighbour)`, so differences consistent with noise blend
+ *    away while real lighting gradients are preserved;
+ *  - **normal** — `pow(max(0, dot(n_center, n_neighbour)), normal_power)`, so the
+ *    filter never blurs across an angular discontinuity. Atlas-adjacency does not
+ *    imply surface-adjacency: a box's two faces, or two unrelated charts packed
+ *    near each other across a thin gutter, must not bleed into one another. A 90°
+ *    crease (`dot = 0`) is fully stopped; smooth curvature (`dot ≈ 1`) blends.
+ *
+ * **Boundary-aware:** a texel at a chart edge (or next to a crease) has a
+ * truncated, one-sided support, whose average is biased. The denoised value is
+ * blended back toward the texel's own value in proportion to how incomplete its
+ * support is (fraction of the window that actually contributed), so edges keep
+ * their unbiased — if noisier — value instead of being pulled toward the
+ * available (darker/brighter) side.
+ *
+ * Writes filtered values for covered texels into `out`; uncovered texels are left
+ * as-is in `out` (the caller dilates them afterwards). `out` must be a distinct
+ * buffer from `data`.
+ *
+ * @param {Float32Array} out destination, same layout as `data` (distinct buffer)
+ * @param {Float32Array} data source pixels, row-major, stride `channels`
+ * @param {Float32Array} variance per-texel luminance variance-of-mean, length width*height
+ * @param {Float32Array} normals per-texel world normal (3 per texel), length width*height*3
+ * @param {Uint8Array} coverage per-texel coverage (1 = valid), length width*height
+ * @param {number} width
+ * @param {number} height
+ * @param {number} channels values per texel (rgb[+a])
+ * @param {object} [options]
+ * @param {number} [options.radius] window half-size in texels (default 2)
+ * @param {number} [options.spatial_sigma] spatial Gaussian sigma in texels (default 1.5)
+ * @param {number} [options.beta] noise tolerance: how many stddevs count as "still noise" (default 3)
+ * @param {number} [options.normal_power] sharpness of the normal-similarity cutoff (default 8)
+ */
+export function lightmap_denoise(out, data, variance, normals, coverage, width, height, channels, options = {}) {
+    const radius = options.radius ?? 2;
+    const spatial_sigma = options.spatial_sigma ?? 1.5;
+    const beta = options.beta ?? 3;
+    const normal_power = options.normal_power ?? 8;
+
+    const inv_2_spatial = 1 / (2 * spatial_sigma * spatial_sigma);
+
+    // start as a copy so uncovered texels pass through untouched
+    out.set(data);
+
+    const acc = new Float64Array(channels);
+
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const index = y * width + x;
+
+            if (coverage[index] === 0) {
+                continue;
+            }
+
+            const center_base = index * channels;
+            const center_lum = rgb_to_luminance(data[center_base], data[center_base + 1], data[center_base + 2]);
+            const var_center = variance[index];
+
+            const n3 = index * 3;
+            const cnx = normals[n3];
+            const cny = normals[n3 + 1];
+            const cnz = normals[n3 + 2];
+
+            acc.fill(0);
+            let weight_sum = 0;
+            let contributing = 0; // neighbours that passed coverage + normal
+            let window = 0;       // in-bounds window texels
+
+            const y0 = Math.max(0, y - radius);
+            const y1 = Math.min(height - 1, y + radius);
+            const x0 = Math.max(0, x - radius);
+            const x1 = Math.min(width - 1, x + radius);
+
+            for (let ny = y0; ny <= y1; ny++) {
+                for (let nx = x0; nx <= x1; nx++) {
+                    window++;
+                    const n_index = ny * width + nx;
+                    if (coverage[n_index] === 0) {
+                        continue;
+                    }
+
+                    // normal similarity — never blend across an angular discontinuity
+                    const nn3 = n_index * 3;
+                    const dot = cnx * normals[nn3] + cny * normals[nn3 + 1] + cnz * normals[nn3 + 2];
+                    if (dot <= 0) {
+                        continue;
+                    }
+                    const w_normal = Math.pow(dot, normal_power);
+
+                    const dx = nx - x;
+                    const dy = ny - y;
+                    const w_spatial = Math.exp(-(dx * dx + dy * dy) * inv_2_spatial);
+
+                    const n_base = n_index * channels;
+                    const n_lum = rgb_to_luminance(data[n_base], data[n_base + 1], data[n_base + 2]);
+                    const d_lum = n_lum - center_lum;
+
+                    // noise stddev of the difference; the floor keeps an edge between
+                    // two zero-variance texels sharp (any real difference -> weight ~0)
+                    const sigma = Math.sqrt(var_center + variance[n_index]);
+                    const tol = beta * sigma;
+                    const w_range = Math.exp(-(d_lum * d_lum) / (2 * tol * tol + 1e-12));
+
+                    const w = w_spatial * w_range * w_normal;
+
+                    for (let c = 0; c < channels; c++) {
+                        acc[c] += data[n_base + c] * w;
+                    }
+                    weight_sum += w;
+                    contributing++;
+                }
+            }
+
+            // boundary-aware: a truncated/one-sided window (chart edge, or a crease
+            // that rejected half its neighbours) gives a biased average, so trust the
+            // texel's own value in proportion to how incomplete its support is.
+            const inv = weight_sum > 0 ? 1 / weight_sum : 0;
+            const alpha = window > 0 ? contributing / window : 0;
+            for (let c = 0; c < channels; c++) {
+                const denoised = acc[c] * inv;
+                out[center_base + c] = data[center_base + c] * (1 - alpha) + denoised * alpha;
+            }
+        }
+    }
+}

package/src/engine/graphics/sh3/lightmap/lightmap_dilate.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Grow ("dilate") covered texels outward into their uncovered neighbours, so that
+ * bilinear sampling across a chart boundary blends with valid lighting instead of
+ * the black background. This is the standard lightmap gutter/seam fix.
+ *
+ * Each iteration fills every uncovered texel that has at least one covered
+ * 4-neighbour with the average of those covered neighbours, then marks it covered
+ * for the next iteration. Operates in place on a flat, row-major, `channels`-wide
+ * pixel buffer.
+ *
+ * @param {Float32Array|number[]} data flat row-major pixel data, length width*height*channels
+ * @param {Uint8Array} coverage flat row-major coverage mask (1 = has valid lighting), mutated
+ * @param {number} width
+ * @param {number} height
+ * @param {number} channels values per texel
+ * @param {number} iterations how many texels of border to grow (≈ the atlas padding)
+ */
+export function lightmap_dilate(data: Float32Array | number[], coverage: Uint8Array, width: number, height: number, channels: number, iterations: number): void;
+//# sourceMappingURL=lightmap_dilate.d.ts.map

package/src/engine/graphics/sh3/lightmap/lightmap_dilate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lightmap_dilate.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/lightmap/lightmap_dilate.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,sCAPW,YAAY,GAAC,MAAM,EAAE,YACrB,UAAU,SACV,MAAM,UACN,MAAM,YACN,MAAM,cACN,MAAM,QA6DhB"}

package/src/engine/graphics/sh3/lightmap/lightmap_dilate.js

@@ -0,0 +1,89 @@
+/**
+ * Grow ("dilate") covered texels outward into their uncovered neighbours, so that
+ * bilinear sampling across a chart boundary blends with valid lighting instead of
+ * the black background. This is the standard lightmap gutter/seam fix.
+ *
+ * Each iteration fills every uncovered texel that has at least one covered
+ * 4-neighbour with the average of those covered neighbours, then marks it covered
+ * for the next iteration. Operates in place on a flat, row-major, `channels`-wide
+ * pixel buffer.
+ *
+ * @param {Float32Array|number[]} data flat row-major pixel data, length width*height*channels
+ * @param {Uint8Array} coverage flat row-major coverage mask (1 = has valid lighting), mutated
+ * @param {number} width
+ * @param {number} height
+ * @param {number} channels values per texel
+ * @param {number} iterations how many texels of border to grow (≈ the atlas padding)
+ */
+export function lightmap_dilate(data, coverage, width, height, channels, iterations) {
+    const acc = new Float64Array(channels);
+
+    for (let iter = 0; iter < iterations; iter++) {
+        // texels that become covered this round; deferred so a single pass does not
+        // chain-fill along a row from a texel filled earlier in the same iteration
+        const newly = [];
+
+        for (let y = 0; y < height; y++) {
+            for (let x = 0; x < width; x++) {
+                const index = y * width + x;
+
+                if (coverage[index] !== 0) {
+                    continue;
+                }
+
+                acc.fill(0);
+                let n = 0;
+
+                if (x > 0 && coverage[index - 1] !== 0) {
+                    accumulate(acc, data, (index - 1) * channels, channels);
+                    n++;
+                }
+                if (x < width - 1 && coverage[index + 1] !== 0) {
+                    accumulate(acc, data, (index + 1) * channels, channels);
+                    n++;
+                }
+                if (y > 0 && coverage[index - width] !== 0) {
+                    accumulate(acc, data, (index - width) * channels, channels);
+                    n++;
+                }
+                if (y < height - 1 && coverage[index + width] !== 0) {
+                    accumulate(acc, data, (index + width) * channels, channels);
+                    n++;
+                }
+
+                if (n === 0) {
+                    continue;
+                }
+
+                const base = index * channels;
+                const inv = 1 / n;
+                for (let c = 0; c < channels; c++) {
+                    data[base + c] = acc[c] * inv;
+                }
+
+                newly.push(index);
+            }
+        }
+
+        if (newly.length === 0) {
+            // fully grown, nothing left to reach
+            break;
+        }
+
+        for (let i = 0; i < newly.length; i++) {
+            coverage[newly[i]] = 1;
+        }
+    }
+}
+
+/**
+ * @param {Float64Array} acc
+ * @param {Float32Array|number[]} data
+ * @param {number} offset
+ * @param {number} channels
+ */
+function accumulate(acc, data, offset, channels) {
+    for (let c = 0; c < channels; c++) {
+        acc[c] += data[offset + c];
+    }
+}

package/src/engine/graphics/sh3/lightmap/lightmap_gather.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Estimate the lightmap value at a single surface point in **mixed mode**: the
+ * cosine-weighted average incoming radiance — indirect bounces + sky only (direct
+ * light is supplied at render time by the realtime lights, not baked).
+ *
+ * Reuses {@link PathTracer#path_trace} along cosine-weighted hemisphere directions
+ * ({@link getBiasedNormalSample}, power 1) — bounced light, emissive surfaces, and
+ * the environment. Each texel draws its own independent random directions (no fixed
+ * sample set is shared between texels, which would otherwise show as structured
+ * bias on flat surfaces).
+ *
+ * **Supersampling:** each sample's ray ORIGIN is jittered within the texel's world
+ * footprint (in the surface tangent plane, magnitude `cfg.supersample × texel`), so
+ * a texel straddling a shadow boundary or silhouette averages lit/occluded
+ * sub-positions into a soft gradient instead of a hard one-texel line.
+ *
+ * Also produces two auxiliary signals used by the baker:
+ *  - the **variance of the mean** (luminance), written to `out[3]`, which drives
+ *    the variance-guided denoiser;
+ *  - a **confidence** in [0,1] (the return value): `1 - (fraction of short probes
+ *    that hit a BACK face)`. Flags only buried/wrong-side points; an enclosed-room
+ *    floor (front faces all around) stays confident. `cfg.confidence_probes === 0`
+ *    disables it (confidence 1).
+ *
+ * The stored radiance is `E / π` (cosine-weighted mean); three.js's lightmap path
+ * multiplies it back by `π · albedo / π = albedo`, preserving surface colour.
+ *
+ * @param {Float32Array|number[]} out 4 channels written: linear r, g, b, luminance variance-of-mean
+ * @param {number} px world-space point x (already nudged off the surface)
+ * @param {number} py world-space point y
+ * @param {number} pz world-space point z
+ * @param {number} nx world-space surface normal x (unit)
+ * @param {number} ny world-space surface normal y
+ * @param {number} nz world-space surface normal z
+ * @param {number} texel_world_size world-space size of one lightmap texel at this point
+ * @param {PathTracedScene} scene
+ * @param {PathTracer} path_tracer
+ * @param {{samples:number, max_samples:number, variance_target:number, min_bounce:number, max_bounce:number, confidence_probes:number, inside_probe_texels:number, supersample:number}} cfg
+ *   `samples` is the minimum count; sampling continues up to `max_samples` while the
+ *   relative variance-of-mean exceeds `variance_target` (0 = fixed `samples`).
+ * @param {function():number} random
+ * @returns {number} confidence in [0,1]
+ */
+export function lightmap_gather(out: Float32Array | number[], px: number, py: number, pz: number, nx: number, ny: number, nz: number, texel_world_size: number, scene: PathTracedScene, path_tracer: PathTracer, cfg: {
+    samples: number;
+    max_samples: number;
+    variance_target: number;
+    min_bounce: number;
+    max_bounce: number;
+    confidence_probes: number;
+    inside_probe_texels: number;
+    supersample: number;
+}, random: () => number): number;
+//# sourceMappingURL=lightmap_gather.d.ts.map

package/src/engine/graphics/sh3/lightmap/lightmap_gather.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lightmap_gather.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/lightmap/lightmap_gather.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qCAhBW,YAAY,GAAC,MAAM,EAAE,MACrB,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,oBACN,MAAM;aAGG,MAAM;iBAAc,MAAM;qBAAkB,MAAM;gBAAa,MAAM;gBAAa,MAAM;uBAAoB,MAAM;yBAAsB,MAAM;iBAAc,MAAM;iBAGhK,MAAM,GACf,MAAM,CA6GlB"}