@woosh/meep-engine 3.68.0 → 3.70.0

package/src/engine/physics/fluid/turbulence/fluid_turbulence_tile_generate.js

@@ -0,0 +1,313 @@
+import { assert } from "../../../../core/assert.js";
+import { isPowerOfTwo } from "../../../../core/math/isPowerOfTwo.js";
+import { complex_fft_radix2 } from "../../../../core/math/complex/complex_fft_radix2.js";
+import { seededRandom_Mulberry32 } from "../../../../core/math/random/seededRandom_Mulberry32.js";
+
+/**
+ * A repeating tile of isotropic, divergence-free turbulence with the von Kármán spectrum, unit rms:
+ * the mean over the tile of each component's square, averaged over the three components, is 1.
+ * Level 0 of {@link fluid_turbulence_tile_generate_levels}.
+ *
+ * @param {ArrayLike<number>} resolution texels on x, y and z, each a power of two, 2 or more
+ * @param {number} texels_per_length texels per length scale `L`, > 0
+ * @param {number} seed
+ * @returns {Float32Array} three values a texel, `(u, v, w)`, x fastest, then y, then z
+ */
+export function fluid_turbulence_tile_generate(resolution, texels_per_length, seed) {
+    return fluid_turbulence_tile_generate_levels(resolution, texels_per_length, seed, 1)[0];
+}
+
+/**
+ * Texels of level `level` of a tile on each axis: the tile's halved `level` times, and at least 1.
+ *
+ * @param {number[]} out
+ * @param {ArrayLike<number>} resolution level 0's
+ * @param {number} level
+ * @returns {number[]} `out`
+ */
+export function fluid_turbulence_tile_level_size(out, resolution, level) {
+    for (let axis = 0; axis < 3; axis++) {
+        out[axis] = Math.max(1, resolution[axis] >> level);
+    }
+
+    return out;
+}
+
+/**
+ * A repeating tile of isotropic, divergence-free turbulence with the von Kármán spectrum, and its
+ * levels: level `ℓ` is the same field band-limited to what texels `2^ℓ` times as large can hold.
+ *
+ * The tile is laid out in units of the length scale `L`: `texels_per_length` texels a length. In
+ * those units the von Kármán energy spectrum is
+ *
+ *     E(k) ∝ (kL)⁴ / (1 + (kL)²)^(17/6)
+ *
+ * which rises as k⁴ from the largest scales, peaks at a wavelength of about `4.05·L`, and falls as
+ * the inertial range's k^(−5/3) below it.
+ *
+ * Spectral synthesis, Shinozuka's: each wavenumber of the tile's lattice draws a complex Gaussian
+ * vector, projects it onto the plane normal to the wavenumber, which makes the field divergence-free,
+ * and scales it by `sqrt(E(k) / (4π k²))`, an isotropic field's amplitude at a lattice point; an
+ * inverse FFT then gives the field, of which the real part is kept. The mean (`k = 0`) and the
+ * Nyquist planes are left at zero.
+ *
+ * A level keeps the wavenumbers below its own Nyquist and no others, and is the inverse FFT of those at
+ * its own texel centres: an ideal low-pass of level 0, evaluated where a sampler reads that level, so
+ * a read of level `ℓ` is level 0 with every wavelength shorter than two of its texels taken out, and
+ * nothing aliased in. Every level is scaled as level 0 is to unit rms, so a level holds the energy of
+ * its band and no more.
+ *
+ * Deterministic in `seed`, and the same level 0 whatever the level count. Allocates the levels and
+ * about 13 MB of transforms, once: this is an asset's generation, not a per-frame path.
+ *
+ * @param {ArrayLike<number>} resolution texels on x, y and z, each a power of two, 2 or more
+ * @param {number} texels_per_length texels per length scale `L`, > 0
+ * @param {number} seed
+ * @param {number} [level_count] levels to make, 1 or more; by default down to one texel on the
+ *   longest axis, a full mip chain
+ * @returns {Float32Array[]} per level, three values a texel, `(u, v, w)`, x fastest, then y, then z
+ */
+export function fluid_turbulence_tile_generate_levels(resolution, texels_per_length, seed, level_count = 1 + Math.log2(Math.max(resolution[0], resolution[1], resolution[2]))) {
+    const nx = resolution[0];
+    const ny = resolution[1];
+    const nz = resolution[2];
+
+    for (let axis = 0; axis < 3; axis++) {
+        assert.isPositiveInteger(resolution[axis], 'resolution');
+        assert.ok(isPowerOfTwo(resolution[axis]), 'resolution is a power of two on each axis');
+        assert.greaterThanOrEqual(resolution[axis], 2, 'resolution');
+    }
+
+    assert.isFinite(texels_per_length, 'texels_per_length');
+    assert.greaterThan(texels_per_length, 0, 'texels_per_length');
+    assert.isPositiveInteger(level_count, 'level_count');
+
+    const count = nx * ny * nz;
+
+    const re = [new Float32Array(count), new Float32Array(count), new Float32Array(count)];
+    const im = [new Float32Array(count), new Float32Array(count), new Float32Array(count)];
+
+    const random = seededRandom_Mulberry32(seed);
+
+    // one standard normal draw, Box–Muller; the second of each pair is discarded, so the stream is
+    // one uniform pair a value
+    const normal = () => {
+        const u1 = 1 - random(); // (0, 1]
+        const u2 = random();
+
+        return Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+    };
+
+    // kL of lattice index i on an axis of n texels: 2π·m / (n / texels_per_length), m signed
+    const kl_x = 2 * Math.PI * texels_per_length / nx;
+    const kl_y = 2 * Math.PI * texels_per_length / ny;
+    const kl_z = 2 * Math.PI * texels_per_length / nz;
+
+    const xi_re = new Float64Array(3);
+    const xi_im = new Float64Array(3);
+
+    for (let iz = 0; iz < nz; iz++) {
+        const mz = signed(iz, nz);
+
+        for (let iy = 0; iy < ny; iy++) {
+            const my = signed(iy, ny);
+
+            for (let ix = 0; ix < nx; ix++) {
+                const mx = signed(ix, nx);
+
+                // every lattice point draws, the skipped ones too, so the stream does not depend on
+                // which are kept
+                for (let c = 0; c < 3; c++) {
+                    xi_re[c] = normal();
+                    xi_im[c] = normal();
+                }
+
+                if (mx === -nx / 2 || my === -ny / 2 || mz === -nz / 2) {
+                    continue; // the Nyquist planes
+                }
+
+                const kx = mx * kl_x;
+                const ky = my * kl_y;
+                const kz = mz * kl_z;
+                const k2 = kx * kx + ky * ky + kz * kz;
+
+                if (k2 === 0) {
+                    continue; // the mean
+                }
+
+                const energy = k2 * k2 / Math.pow(1 + k2, 17 / 6);
+                const amplitude = Math.sqrt(energy / (4 * Math.PI * k2));
+
+                const inv_k2 = 1 / k2;
+                const dot_re = (kx * xi_re[0] + ky * xi_re[1] + kz * xi_re[2]) * inv_k2;
+                const dot_im = (kx * xi_im[0] + ky * xi_im[1] + kz * xi_im[2]) * inv_k2;
+
+                const index = ix + nx * (iy + ny * iz);
+
+                re[0][index] = amplitude * (xi_re[0] - kx * dot_re);
+                re[1][index] = amplitude * (xi_re[1] - ky * dot_re);
+                re[2][index] = amplitude * (xi_re[2] - kz * dot_re);
+                im[0][index] = amplitude * (xi_im[0] - kx * dot_im);
+                im[1][index] = amplitude * (xi_im[1] - ky * dot_im);
+                im[2][index] = amplitude * (xi_im[2] - kz * dot_im);
+            }
+        }
+    }
+
+    const longest = Math.max(nx, ny, nz);
+    const line_re = new Float64Array(longest);
+    const line_im = new Float64Array(longest);
+
+    // the coarser levels first, from the spectrum before level 0's transform takes it over
+    const fields = new Array(level_count);
+    const size = [0, 0, 0];
+
+    for (let level = 1; level < level_count; level++) {
+        fluid_turbulence_tile_level_size(size, resolution, level);
+
+        const [lx, ly, lz] = size;
+        const level_count_texels = lx * ly * lz;
+
+        // texel j of the level is centred at (j + ½)·span in level-0 texels, which level 0's own
+        // transform, sampled at its texel i ↦ i + ½, reaches with a phase of m·(span − 1)/2 a component
+        const phase_x = Math.PI * (nx / lx - 1) / nx;
+        const phase_y = Math.PI * (ny / ly - 1) / ny;
+        const phase_z = Math.PI * (nz / lz - 1) / nz;
+
+        const level_re = [new Float32Array(level_count_texels), new Float32Array(level_count_texels), new Float32Array(level_count_texels)];
+        const level_im = [new Float32Array(level_count_texels), new Float32Array(level_count_texels), new Float32Array(level_count_texels)];
+
+        for (let jz = 0; jz < lz; jz++) {
+            const mz = signed(jz, lz);
+
+            if (lz > 1 && mz === -lz / 2) continue;
+
+            for (let jy = 0; jy < ly; jy++) {
+                const my = signed(jy, ly);
+
+                if (ly > 1 && my === -ly / 2) continue;
+
+                for (let jx = 0; jx < lx; jx++) {
+                    const mx = signed(jx, lx);
+
+                    if (lx > 1 && mx === -lx / 2) continue;
+
+                    const source = wrap(mx, nx) + nx * (wrap(my, ny) + ny * wrap(mz, nz));
+                    const target = jx + lx * (jy + ly * jz);
+
+                    const angle = mx * phase_x + my * phase_y + mz * phase_z;
+                    const cos = Math.cos(angle);
+                    const sin = Math.sin(angle);
+
+                    for (let c = 0; c < 3; c++) {
+                        const a = re[c][source];
+                        const b = im[c][source];
+
+                        level_re[c][target] = a * cos - b * sin;
+                        level_im[c][target] = a * sin + b * cos;
+                    }
+                }
+            }
+        }
+
+        for (let c = 0; c < 3; c++) {
+            inverse_3d(level_re[c], level_im[c], lx, ly, lz, line_re, line_im);
+        }
+
+        fields[level] = level_re;
+    }
+
+    for (let c = 0; c < 3; c++) {
+        inverse_3d(re[c], im[c], nx, ny, nz, line_re, line_im);
+    }
+
+    fields[0] = re;
+
+    let square_sum = 0;
+
+    for (let c = 0; c < 3; c++) {
+        const values = re[c];
+
+        for (let i = 0; i < count; i++) {
+            square_sum += values[i] * values[i];
+        }
+    }
+
+    const scale = 1 / Math.sqrt(square_sum / (3 * count));
+
+    const out = new Array(level_count);
+
+    for (let level = 0; level < level_count; level++) {
+        const field = fields[level];
+        const texels = field[0].length;
+        const values = new Float32Array(3 * texels);
+
+        for (let i = 0; i < texels; i++) {
+            values[3 * i] = field[0][i] * scale;
+            values[3 * i + 1] = field[1][i] * scale;
+            values[3 * i + 2] = field[2][i] * scale;
+        }
+
+        out[level] = values;
+    }
+
+    return out;
+}
+
+/**
+ * The signed wavenumber of lattice index `i` on an axis of `n`: `i` below `n/2`, `i − n` from it.
+ */
+function signed(i, n) {
+    return i < n / 2 ? i : i - n;
+}
+
+/**
+ * The lattice index of signed wavenumber `m` on an axis of `n`.
+ */
+function wrap(m, n) {
+    return m < 0 ? m + n : m;
+}
+
+/**
+ * The inverse transform of a 3-D array along every axis of more than one texel.
+ */
+function inverse_3d(re, im, nx, ny, nz, line_re, line_im) {
+    if (nx > 1) inverse_along(re, im, nx, 1, ny, nx, nz, nx * ny, line_re, line_im);
+    if (ny > 1) inverse_along(re, im, ny, nx, nx, 1, nz, nx * ny, line_re, line_im);
+    if (nz > 1) inverse_along(re, im, nz, nx * ny, nx, 1, ny, nx, line_re, line_im);
+}
+
+/**
+ * The inverse transform along one axis of a 3-D array, every line of it: line `(a, b)` starts at
+ * `a·stride_a + b·stride_b` and steps `stride`.
+ *
+ * @param {Float32Array} re
+ * @param {Float32Array} im
+ * @param {number} n texels along the axis
+ * @param {number} stride index step along the axis
+ * @param {number} count_a lines along the first other axis
+ * @param {number} stride_a its index step
+ * @param {number} count_b lines along the second other axis
+ * @param {number} stride_b its index step
+ * @param {Float64Array} line_re scratch, `n` or longer
+ * @param {Float64Array} line_im scratch, likewise
+ */
+function inverse_along(re, im, n, stride, count_a, stride_a, count_b, stride_b, line_re, line_im) {
+    for (let b = 0; b < count_b; b++) {
+        for (let a = 0; a < count_a; a++) {
+            const base = a * stride_a + b * stride_b;
+
+            for (let i = 0; i < n; i++) {
+                line_re[i] = re[base + i * stride];
+                line_im[i] = im[base + i * stride];
+            }
+
+            complex_fft_radix2(line_re, line_im, n, true);
+
+            for (let i = 0; i < n; i++) {
+                re[base + i * stride] = line_re[i];
+                im[base + i * stride] = line_im[i];
+            }
+        }
+    }
+}

package/src/engine/physics/fluid/turbulence/fluid_turbulence_tile_sample.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A trilinear read of a turbulence tile at tile coordinate `q`, repeating, as a device's
+ * linear sampler with `repeat` addressing reads the same texels: one tile is 1 on each axis, and
+ * texel `i` is centred at `(i + ½) / n`.
+ *
+ * The device's filter rounds its weights (to 1/256 of a texel on the GPUs measured), so the two
+ * agree to that, not to the bit. Allocates nothing.
+ *
+ * @param {Float64Array|Float32Array|number[]} out receives `(u, v, w)` at 0..2
+ * @param {Float32Array} values three a texel, x fastest, {@link FLUID_TURBULENCE_TILE_RESOLUTION}
+ * @param {Float64Array|number[]} q the tile coordinate, x, y, z: handed in an array so that a caller
+ *   that does not inline this passes no number across the call, which would box it
+ * @returns {Float64Array|Float32Array|number[]} `out`
+ */
+export function fluid_turbulence_tile_sample(out: Float64Array | Float32Array | number[], values: Float32Array, q: Float64Array | number[]): Float64Array | Float32Array | number[];
+//# sourceMappingURL=fluid_turbulence_tile_sample.d.ts.map

package/src/engine/physics/fluid/turbulence/fluid_turbulence_tile_sample.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fluid_turbulence_tile_sample.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/turbulence/fluid_turbulence_tile_sample.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;GAaG;AACH,kDANW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,UAClC,YAAY,KACZ,YAAY,GAAC,MAAM,EAAE,GAEnB,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,CAkD9C"}

package/src/engine/physics/fluid/turbulence/fluid_turbulence_tile_sample.js

@@ -0,0 +1,69 @@
+import { FLUID_TURBULENCE_TILE_RESOLUTION } from "./FLUID_TURBULENCE_TILE.js";
+
+const NX = FLUID_TURBULENCE_TILE_RESOLUTION[0];
+const NY = FLUID_TURBULENCE_TILE_RESOLUTION[1];
+const NZ = FLUID_TURBULENCE_TILE_RESOLUTION[2];
+
+/**
+ * A trilinear read of a turbulence tile at tile coordinate `q`, repeating, as a device's
+ * linear sampler with `repeat` addressing reads the same texels: one tile is 1 on each axis, and
+ * texel `i` is centred at `(i + ½) / n`.
+ *
+ * The device's filter rounds its weights (to 1/256 of a texel on the GPUs measured), so the two
+ * agree to that, not to the bit. Allocates nothing.
+ *
+ * @param {Float64Array|Float32Array|number[]} out receives `(u, v, w)` at 0..2
+ * @param {Float32Array} values three a texel, x fastest, {@link FLUID_TURBULENCE_TILE_RESOLUTION}
+ * @param {Float64Array|number[]} q the tile coordinate, x, y, z: handed in an array so that a caller
+ *   that does not inline this passes no number across the call, which would box it
+ * @returns {Float64Array|Float32Array|number[]} `out`
+ */
+export function fluid_turbulence_tile_sample(out, values, q) {
+    const px = q[0] * NX - 0.5;
+    const py = q[1] * NY - 0.5;
+    const pz = q[2] * NZ - 0.5;
+
+    const fx = Math.floor(px);
+    const fy = Math.floor(py);
+    const fz = Math.floor(pz);
+
+    const tx = px - fx;
+    const ty = py - fy;
+    const tz = pz - fz;
+
+    // euclidean modulo: a coordinate below 0 wraps from the far side
+    const x0 = ((fx % NX) + NX) % NX;
+    const y0 = ((fy % NY) + NY) % NY;
+    const z0 = ((fz % NZ) + NZ) % NZ;
+    const x1 = x0 + 1 === NX ? 0 : x0 + 1;
+    const y1 = y0 + 1 === NY ? 0 : y0 + 1;
+    const z1 = z0 + 1 === NZ ? 0 : z0 + 1;
+
+    const r00 = NX * (y0 + NY * z0);
+    const r10 = NX * (y1 + NY * z0);
+    const r01 = NX * (y0 + NY * z1);
+    const r11 = NX * (y1 + NY * z1);
+
+    for (let c = 0; c < 3; c++) {
+        const c000 = values[3 * (x0 + r00) + c];
+        const c100 = values[3 * (x1 + r00) + c];
+        const c010 = values[3 * (x0 + r10) + c];
+        const c110 = values[3 * (x1 + r10) + c];
+        const c001 = values[3 * (x0 + r01) + c];
+        const c101 = values[3 * (x1 + r01) + c];
+        const c011 = values[3 * (x0 + r11) + c];
+        const c111 = values[3 * (x1 + r11) + c];
+
+        const a0 = c000 + (c100 - c000) * tx;
+        const a1 = c010 + (c110 - c010) * tx;
+        const a2 = c001 + (c101 - c001) * tx;
+        const a3 = c011 + (c111 - c011) * tx;
+
+        const b0 = a0 + (a1 - a0) * ty;
+        const b1 = a2 + (a3 - a2) * ty;
+
+        out[c] = b0 + (b1 - b0) * tz;
+    }
+
+    return out;
+}

package/src/generation/foliage/mesh/branch_ring_triangulate.d.ts

@@ -6,7 +6,7 @@
  * Guarantees:
  * - Strictly `m0 + m1` triangles emitted.
  * - Zero index-degenerate triangles (`i0 !== i1 && i1 !== i2 && i2 !== i0`), preventing
- *   `MeshoptClusterizer` / `meshlet_batch_to_bvh` from stripping triangles.
+ *   `MeshoptClusterizer` from stripping triangles.
  * - Consistent outward CCW winding for right-handed `(T, R, S = T x R)` rings where `theta`
  *   increases from `0` to `2*PI`.
  *

package/src/generation/foliage/mesh/branch_ring_triangulate.js

@@ -8,7 +8,7 @@ import { assert } from "../../../core/assert.js";
  * Guarantees:
  * - Strictly `m0 + m1` triangles emitted.
  * - Zero index-degenerate triangles (`i0 !== i1 && i1 !== i2 && i2 !== i0`), preventing
- *   `MeshoptClusterizer` / `meshlet_batch_to_bvh` from stripping triangles.
+ *   `MeshoptClusterizer` from stripping triangles.
  * - Consistent outward CCW winding for right-handed `(T, R, S = T x R)` rings where `theta`
  *   increases from `0` to `2*PI`.
  *

package/src/shade/playground/bvh_repro/README.md

@@ -28,7 +28,8 @@ timings simply do not appear without it.
 |---|---|---|
 | **Sort** | `gpu_primitive/sort/verify_radix_sort.js` | 30 cases across tile boundaries and three key distributions: keys ascending, payload a permutation of the input indices, every payload still beside its own key, and equal keys still in input order (stability, which is what each digit pass of an LSD sort rests on). |
 | **BVH build** | `gpu_primitive/bvh/verify_gpu_bvh_build.js` | ~58 leaf sets — coincident, tight-clustered, degenerate zero-volume, mixed — at counts either side of every workgroup and tile boundary up to 100k. Structural validity, payload permutation, parent boxes containing children, **topology matching `ebvh_build_hierarchy_radix` node for node**, refit bounds matching the CPU's, a depth histogram against the 32-entry traversal stack, and SAH against the oracle's. |
-| **TLAS end to end** | `scene/verify_gpu_tlas_build.js` | The shipped path: a real `GPUDatabase` over `SCENE_DATABASE_SPEC`, rows added to `GPUInstancesAccelerationStructure`, `update()` called the way `GPUSceneContext` calls it. This is the only on-device coverage of `shader_bvh_extract_instance_leaves` and of the ±inf seeding of the scene-bounds cell — plus movement, removal, and the emptied-TLAS root word. |
+| **BVH8 encode** | `gpu_primitive/bvh8/verify_gpu_bvh8_encode.js` | The same leaf sets, at counts either side of where the encode changes recording (1,024 leaves) and of its workgroups' edges: the binary tree is built as the scene's is, encoded three levels to a node, and the result held **word for word to `bvh8_encode_from_bvh2`** run over the binary tree the device built — header, nodes, payloads, and the words past them left alone. Each tree's depth against the 16 levels a walk's stack holds, and the per-pass time of build and encode at 1,024 and 100,003 leaves. |
+| **TLAS end to end** | `scene/verify_gpu_tlas_build.js` | The shipped path: a real `GPUDatabase` over `SCENE_DATABASE_SPEC`, rows added to `GPUInstancesAccelerationStructure`, `update()` called the way `GPUSceneContext` calls it. The tree read back is the BVH8 every query walks, held by `check_bvh8_tree`: every row a leaf once, every slot holding the world boxes under it, the header's box the scene's. This is the only on-device coverage of `shader_bvh_extract_instance_leaves` and of the ±inf seeding of the scene-bounds cell — plus movement, removal, and the emptied tree. |
 
 The BVH harness feeds the CPU oracle the GPU's **own** sorted Morton order rather than recomputing
 it. WGSL's `round` breaks halfway cases to even and JavaScript's breaks them upward, so on
@@ -39,10 +40,11 @@ order keeps the comparison about emission rather than about rounding.
 
 `PASS` / `FAIL` per case, in green and red. Below each tree, a depth histogram as `depth:leaves`.
 
-A depth **warning** is not a failure. The 32-entry traversal stack is shared between the TLAS and
-the BLAS within a single query, and the occlusion path truncates silently rather than erroring, so
-depth is a real output-quality constraint on an LBVH — it is reported so it can be watched, and
-phase 2's treelet restructuring is what shortens the chains it measures.
+A depth **warning** is not a failure. A query walks the instances' tree and a mesh's on one stack,
+sixteen entries each, and a walk that runs out of entries drops what it cannot keep rather than
+erroring, so depth is a real output-quality constraint. The BVH8 encode and the TLAS check report
+the wide tree's depth against those sixteen; the BVH build check reports the binary tree's, of
+which the wide tree's is a third.
 
 Uncaptured device errors and device-lost events are surfaced in the log. They matter here more than
 usual: these harnesses check bytes, and a shader that failed to compile has no bytes to check.
@@ -53,5 +55,5 @@ What a tree looks like when something traverses it. That needs the full renderer
 `src/shade/playground/sponza_path_trace/` is where Sponza gets traced, and where a regression in
 the tree would show as something visible rather than as a failed assertion.
 
-All three harnesses are also registered in the main playground's **review checks** folder, for when
+The sort, BVH build and TLAS harnesses are also registered in the main playground's **review checks** folder, for when
 you are already in a scene.