@woosh/meep-engine 3.2.0 → 3.4.0

package/src/shade/playground/add_random_meshes.js

@@ -1,84 +1,132 @@
-import Quaternion from "../../core/geom/Quaternion.js";
-import { v3_distance } from "../../core/geom/vec3/v3_distance.js";
-import Vector3 from "../../core/geom/Vector3.js";
-import { clamp } from "../../core/math/clamp.js";
-import { NumericInterval } from "../../core/math/interval/NumericInterval.js";
-import { randomFloatBetween } from "../../core/math/random/randomFloatBetween.js";
-import { randomFromArray } from "../../core/math/random/randomFromArray.js";
-import { randomIntegerBetween } from "../../core/math/random/randomIntegerBetween.js";
-import { seededRandom } from "../../core/math/random/seededRandom.js";
-import { StandardShadeMaterial } from "../renderer/material/StandardShadeMaterial.js";
-import { Mesh } from "../renderer/scene/Mesh.js";
-
-const default_mat = new StandardShadeMaterial();
-
-/**
- *
- * @param {InstanceBatch} batch
- * @param {Geometry[]} geometries
- * @param {ShadeMaterial[]} [materials]
- * @param {number} [count]
- * @param {NumericInterval} [geometry_scale_range]
- */
-export function add_random_meshes({
-                                      batch,
-                                      geometries,
-                                      materials = [default_mat],
-                                      count = 10000,
-                                      geometry_scale_range = new NumericInterval(1, 15)
-                                  }) {
-
-
-    const geometry_count = geometries.length;
-    const geometry_scales = new Float64Array(geometry_count);
-
-    for (let i = 0; i < geometry_count; i++) {
-
-        const geometry = geometries[i];
-
-        geometry.update();
-
-        const geo_size = v3_distance(
-            geometry.bounding_box[0], geometry.bounding_box[1], geometry.bounding_box[2],
-            geometry.bounding_box[2], geometry.bounding_box[3], geometry.bounding_box[4],
-        );
-
-        const expected_scale = clamp(geo_size, geometry_scale_range.min, geometry_scale_range.max);
-
-        geometry_scales[i] = expected_scale / geo_size;
-    }
-
-    const random = seededRandom();
-
-    const transform_position = new Vector3();
-    const transform_scale = new Vector3();
-    const transform_rotation = new Quaternion();
-
-
-    for (let i = 0; i < count; i++) {
-
-        transform_position.set(
-            randomFloatBetween(random, -200, 200),
-            randomFloatBetween(random, -200, 200),
-            randomFloatBetween(random, -200, 200)
-        );
-        transform_rotation.random(random);
-
-        const geometry_index = randomIntegerBetween(random, 0, geometry_count - 1);
-        const geometry_scale = geometry_scales[geometry_index];
-        const geometry = geometries[geometry_index];
-
-        transform_scale.setScalar(geometry_scale);
-
-        const material = randomFromArray(random, materials)
-
-        const instance = Mesh.from(geometry, material);
-
-        instance.transform_local.setTranslation(transform_position.x, transform_position.y, transform_position.z);
-        instance.transform_local.setRotation(transform_rotation.x, transform_rotation.y, transform_rotation.z, transform_rotation.w);
-        instance.transform_local.setScale(transform_scale.x, transform_scale.y, transform_scale.z);
-        instance.updateMatrices();
-
-        batch.add(instance);
-    }
-}
+import { assert } from "../../core/assert.js";
+import { AABB3 } from "../../core/geom/3d/aabb/AABB3.js";
+import Quaternion from "../../core/geom/Quaternion.js";
+import { v3_distance } from "../../core/geom/vec3/v3_distance.js";
+import Vector3 from "../../core/geom/Vector3.js";
+import { NumericInterval } from "../../core/math/interval/NumericInterval.js";
+import { randomFloatBetween } from "../../core/math/random/randomFloatBetween.js";
+import { randomFromArray } from "../../core/math/random/randomFromArray.js";
+import { randomIntegerBetween } from "../../core/math/random/randomIntegerBetween.js";
+import { seededRandom } from "../../core/math/random/seededRandom.js";
+import { StandardShadeMaterial } from "../renderer/material/StandardShadeMaterial.js";
+import { Mesh } from "../renderer/scene/Mesh.js";
+
+const default_mat = new StandardShadeMaterial();
+
+/**
+ * Where instances land when a caller does not say. Arbitrary, and only sensible for a scene built
+ * around the origin — anything with real bounds should pass its own.
+ *
+ * @type {AABB3}
+ */
+const DEFAULT_REGION = new AABB3(-200, -200, -200, 200, 200, 200);
+
+/**
+ * Scatter `count` instances of `geometries` through `region`, randomly oriented, at sizes spread
+ * across `geometry_scale_range`.
+ *
+ * This exists to build a workload the acceleration structures have to work for. Quantity moves
+ * traversal cost out of the per-mesh BLAS and into the TLAS — at a typical scene's hundred-odd
+ * instances a traced frame is entirely BLAS and shading, and the TLAS's shape is invisible in it.
+ * Size variety is the case a Morton order handles worst, since a Morton code sees a centroid and
+ * nothing about extent.
+ *
+ * Sizes are drawn as a *world-space diagonal* and divided down by each geometry's own, so the
+ * interval means the same thing whatever size the geometries were authored at, and a mixed list
+ * does not scatter one shape at a hundred times the size of another by accident.
+ *
+ * @param {InstanceBatch} batch
+ * @param {MeshletGeometry[]} geometries not plain `Geometry` — see {@link BoxGeometry} and
+ * {@link meshlet_geometry_build_from_geometry}
+ * @param {ShadeMaterial[]} [materials]
+ * @param {number} [count]
+ * @param {NumericInterval} [geometry_scale_range] world-space bounding-box diagonal, in scene units
+ * @param {AABB3} [region] where instance origins land
+ * @param {function():number} [random] pass one shared generator to keep successive calls from
+ * scattering the same instances in the same places
+ */
+export function add_random_meshes({
+                                      batch,
+                                      geometries,
+                                      materials = [default_mat],
+                                      count = 10000,
+                                      geometry_scale_range = new NumericInterval(1, 15),
+                                      region = DEFAULT_REGION,
+                                      random = seededRandom()
+                                  }) {
+
+    assert.defined(batch, 'batch');
+    assert.isArray(geometries, 'geometries');
+    assert.isArray(materials, 'materials');
+
+    const geometry_count = geometries.length;
+
+    assert.greaterThan(geometry_count, 0, 'geometries is empty');
+    assert.greaterThan(materials.length, 0, 'materials is empty');
+
+    const geometry_diagonals = new Float64Array(geometry_count);
+
+    for (let i = 0; i < geometry_count; i++) {
+
+        const geometry = geometries[i];
+
+        // Checked up front and by name, because the failure otherwise happens inside `Mesh.from`
+        // once per instance and says only that a flag was false. A plain `Geometry` is the usual
+        // mistake — `make_box_geometry` and friends return one, and the renderer consumes meshlets.
+        assert.equal(
+            geometry?.isMeshletGeometry, true,
+            `geometries[${i}] is not a MeshletGeometry`
+            + ` — build one with BoxGeometry or meshlet_geometry_build_from_geometry()`
+        );
+
+        const box = geometry.bounding_box;
+
+        const diagonal = v3_distance(
+            box[0], box[1], box[2],
+            box[3], box[4], box[5]
+        );
+
+        assert.greaterThan(diagonal, 0, `geometries[${i}] has an empty bounding box`);
+
+        geometry_diagonals[i] = diagonal;
+    }
+
+    const transform_position = new Vector3();
+    const transform_rotation = new Quaternion();
+
+    const scale_span = geometry_scale_range.max - geometry_scale_range.min;
+
+    for (let i = 0; i < count; i++) {
+
+        transform_position.set(
+            randomFloatBetween(random, region.x0, region.x1),
+            randomFloatBetween(random, region.y0, region.y1),
+            randomFloatBetween(random, region.z0, region.z1)
+        );
+
+        transform_rotation.random(random);
+
+        const geometry_index = randomIntegerBetween(random, 0, geometry_count - 1);
+        const geometry = geometries[geometry_index];
+
+        // squared, so most instances sit near the bottom of the band and a few near the top. A
+        // uniform draw gives a far gentler spread than the one that actually troubles a Morton
+        // order, which is the whole point of scattering these.
+        const target_diagonal = geometry_scale_range.min + scale_span * random() * random();
+
+        const scale = target_diagonal / geometry_diagonals[geometry_index];
+
+        const material = randomFromArray(random, materials);
+
+        const instance = Mesh.from(geometry, material);
+
+        instance.transform_local.setTranslation(transform_position.x, transform_position.y, transform_position.z);
+        instance.transform_local.setRotation(transform_rotation.x, transform_rotation.y, transform_rotation.z, transform_rotation.w);
+        instance.transform_local.setScale(scale, scale, scale);
+
+        // rebuilds the world-space bounds the transform just invalidated
+        instance.updateMatrices();
+
+        batch.add(instance);
+    }
+}

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

@@ -0,0 +1,57 @@
+# GPU BVH build — repro page
+
+A standalone page that runs the phase-1 verify harnesses against a real WebGPU device. No scene, no
+renderer, no assets.
+
+## Running it
+
+```bash
+npm install
+npm run dev
+```
+
+then open <http://localhost:5173/src/shade/playground/bvh_repro/index.html>.
+
+This page imports nothing but meep's own relative ESM, so any static server rooted at the repo would
+also serve it — the dev server is just the one command that works for both prototype pages. It does
+have to be `http://localhost` rather than `file://`: WebGPU needs a secure context, and module
+imports from `file://` are blocked by CORS anyway.
+
+Chrome or Edge 113+. The page refuses to start on an adapter without the `subgroups` feature, which
+is deliberate: the sort's scatter and the TLAS extraction pass both take builtins from it, and
+subgroups are a baseline engine requirement. `timestamp-query` is taken when offered and the build
+timings simply do not appear without it.
+
+## What each button does
+
+| button | harness | what it proves |
+|---|---|---|
+| **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. |
+
+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
+grid-aligned content the two quantisers can disagree by one grid cell; comparing against the GPU's
+order keeps the comparison about emission rather than about rounding.
+
+## Reading the output
+
+`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.
+
+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.
+
+## What this page does not cover
+
+What a tree looks like when something traverses it. That needs the full renderer and a real scene:
+`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
+you are already in a scene.

package/src/shade/playground/bvh_repro/bvh_repro_device.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A device for the GPU BVH repro page.
+ *
+ * Deliberately not {@link gpu_test}'s bootstrap: that one *requires* `timestamp-query` (browsers
+ * withhold it on hardware that is otherwise fine) and does not ask for `subgroups` at all, which is
+ * the one feature everything here needs. This asks for subgroups as a hard requirement, because a
+ * page whose whole job is exercising subgroup kernels should fail loudly on a device that has none
+ * rather than throw halfway through a dispatch.
+ *
+ * Compute only — no `indirect-first-instance`, no `float32-blendable`; nothing here rasterises.
+ *
+ * @returns {Promise<{graphics: GraphicsContext, device: GPUDevice, adapter: GPUAdapter}>}
+ */
+export function bvh_repro_device(): Promise<{
+    graphics: GraphicsContext;
+    device: GPUDevice;
+    adapter: GPUAdapter;
+}>;
+/**
+ * What the page shows about the device it got, since half of what can go wrong here is
+ * device-specific — subgroup width above all, which nothing in this codebase may assume and which
+ * is exactly what a second machine is for.
+ *
+ * @param {GPUAdapter} adapter
+ * @param {GPUDevice} device
+ * @returns {{label: string, value: string}[]}
+ */
+export function describe_device(adapter: GPUAdapter, device: GPUDevice): {
+    label: string;
+    value: string;
+}[];
+import { GraphicsContext } from "../../renderer/GraphicsContext.js";
+//# sourceMappingURL=bvh_repro_device.d.ts.map

package/src/shade/playground/bvh_repro/bvh_repro_device.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bvh_repro_device.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/bvh_repro/bvh_repro_device.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH;cAFgC,eAAe;;;GA0C9C;AAED;;;;;;;;GAQG;AACH,yEAFa;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,EAAE,CAwB5C;gCAxF+B,mCAAmC"}

package/src/shade/playground/bvh_repro/bvh_repro_device.js

@@ -0,0 +1,90 @@
+import { WebGPUExtensionType } from "../../descriptor/WebGPUExtensionType.js";
+import { GraphicsContext } from "../../renderer/GraphicsContext.js";
+
+/**
+ * A device for the GPU BVH repro page.
+ *
+ * Deliberately not {@link gpu_test}'s bootstrap: that one *requires* `timestamp-query` (browsers
+ * withhold it on hardware that is otherwise fine) and does not ask for `subgroups` at all, which is
+ * the one feature everything here needs. This asks for subgroups as a hard requirement, because a
+ * page whose whole job is exercising subgroup kernels should fail loudly on a device that has none
+ * rather than throw halfway through a dispatch.
+ *
+ * Compute only — no `indirect-first-instance`, no `float32-blendable`; nothing here rasterises.
+ *
+ * @returns {Promise<{graphics: GraphicsContext, device: GPUDevice, adapter: GPUAdapter}>}
+ */
+export async function bvh_repro_device() {
+
+    const gpu = navigator.gpu;
+
+    if (gpu === undefined) {
+        throw new Error('navigator.gpu is undefined — this browser has no WebGPU, or the page is not a secure context (use http://localhost, not file://)');
+    }
+
+    const adapter = await gpu.requestAdapter({ powerPreference: "high-performance" });
+
+    if (adapter === null) {
+        throw new Error('failed to acquire a GPUAdapter');
+    }
+
+    if (!adapter.features.has(WebGPUExtensionType.Subgroups)) {
+        throw new Error(
+            'this adapter does not support the `subgroups` feature. Subgroups are a baseline '
+            + 'requirement of the engine — the sort and the extraction pass both take builtins from them.'
+        );
+    }
+
+    const required_features = [WebGPUExtensionType.Subgroups];
+
+    // Profiling only. Taken when offered so the build timings show up, and simply absent otherwise —
+    // GPUTimerArray goes quiet rather than failing.
+    if (adapter.features.has(WebGPUExtensionType.TimestampQuery)) {
+        required_features.push(WebGPUExtensionType.TimestampQuery);
+    }
+
+    const device = await adapter.requestDevice({
+        requiredLimits: {
+            maxBufferSize: adapter.limits.maxBufferSize,
+            maxStorageBufferBindingSize: adapter.limits.maxStorageBufferBindingSize,
+            // the builder's widest pass binds six; the engine's own floor is ten
+            maxStorageBuffersPerShaderStage: Math.min(10, adapter.limits.maxStorageBuffersPerShaderStage),
+        },
+        requiredFeatures: required_features,
+    });
+
+    return { graphics: new GraphicsContext(device), device, adapter };
+}
+
+/**
+ * What the page shows about the device it got, since half of what can go wrong here is
+ * device-specific — subgroup width above all, which nothing in this codebase may assume and which
+ * is exactly what a second machine is for.
+ *
+ * @param {GPUAdapter} adapter
+ * @param {GPUDevice} device
+ * @returns {{label: string, value: string}[]}
+ */
+export function describe_device(adapter, device) {
+    const info = adapter.info ?? {};
+
+    return [
+        { label: 'vendor', value: info.vendor || '(not reported)' },
+        { label: 'architecture', value: info.architecture || '(not reported)' },
+        { label: 'device', value: info.device || '(not reported)' },
+        { label: 'description', value: info.description || '(not reported)' },
+        { label: 'fallback adapter', value: String(adapter.isFallbackAdapter ?? false) },
+        {
+            label: 'subgroup size',
+            value: (info.subgroupMinSize === undefined)
+                ? '(not reported)'
+                : `${info.subgroupMinSize}..${info.subgroupMaxSize}`
+        },
+        { label: 'features', value: [...device.features].sort().join(', ') },
+        { label: 'maxComputeInvocationsPerWorkgroup', value: String(device.limits.maxComputeInvocationsPerWorkgroup) },
+        { label: 'maxComputeWorkgroupStorageSize', value: String(device.limits.maxComputeWorkgroupStorageSize) },
+        { label: 'maxStorageBuffersPerShaderStage', value: String(device.limits.maxStorageBuffersPerShaderStage) },
+        { label: 'maxComputeWorkgroupsPerDimension', value: String(device.limits.maxComputeWorkgroupsPerDimension) },
+        { label: 'maxBufferSize', value: String(device.limits.maxBufferSize) },
+    ];
+}

package/src/shade/playground/bvh_repro/index.html

@@ -0,0 +1,124 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>meep — GPU BVH build repro</title>
+    <style>
+        :root {
+            color-scheme: dark;
+            --bg: #14161a;
+            --panel: #1c1f25;
+            --line: #2b3038;
+            --text: #d6dae0;
+            --muted: #8b939f;
+            --pass: #55c46a;
+            --fail: #ff6b6b;
+            --warn: #e5b54a;
+        }
+
+        * { box-sizing: border-box; }
+
+        body {
+            margin: 0;
+            padding: 24px;
+            background: var(--bg);
+            color: var(--text);
+            font: 14px/1.5 system-ui, -apple-system, Segoe UI, sans-serif;
+        }
+
+        h1 {
+            font-size: 18px;
+            font-weight: 600;
+            margin: 0 0 4px;
+        }
+
+        p.lede {
+            margin: 0 0 20px;
+            color: var(--muted);
+            max-width: 78ch;
+        }
+
+        .controls {
+            display: flex;
+            gap: 8px;
+            flex-wrap: wrap;
+            align-items: center;
+            margin-bottom: 16px;
+        }
+
+        button {
+            font: inherit;
+            padding: 7px 14px;
+            border-radius: 6px;
+            border: 1px solid var(--line);
+            background: var(--panel);
+            color: var(--text);
+            cursor: pointer;
+        }
+
+        button:hover:not(:disabled) { border-color: #3d4552; }
+        button:disabled { opacity: 0.45; cursor: default; }
+
+        button.primary { border-color: #3a5a8c; background: #22303f; }
+
+        #status { color: var(--muted); margin-left: 4px; }
+        #status.pass { color: var(--pass); }
+        #status.fail { color: var(--fail); }
+
+        .panels { display: grid; grid-template-columns: minmax(0, 1fr) 320px; gap: 16px; align-items: start; }
+
+        @media (max-width: 900px) { .panels { grid-template-columns: minmax(0, 1fr); } }
+
+        #log, #device {
+            background: var(--panel);
+            border: 1px solid var(--line);
+            border-radius: 8px;
+            padding: 12px 14px;
+            font-family: ui-monospace, SFMono-Regular, Consolas, monospace;
+            font-size: 12.5px;
+            overflow: auto;
+        }
+
+        #log { height: 62vh; white-space: pre-wrap; }
+        #device div { display: flex; gap: 8px; padding: 2px 0; word-break: break-word; }
+        #device .key { color: var(--muted); flex: 0 0 46%; }
+
+        .line.pass { color: var(--pass); }
+        .line.fail { color: var(--fail); }
+        .line.warn { color: var(--warn); }
+        .line.note { color: var(--muted); }
+
+        aside h2 { font-size: 12px; text-transform: uppercase; letter-spacing: 0.06em; color: var(--muted); margin: 0 0 8px; }
+        aside + aside { margin-top: 16px; }
+    </style>
+</head>
+<body>
+
+<h1>GPU BVH build — repro</h1>
+<p class="lede">
+    Runs the phase-1 verify harnesses against a real device: the CSDLDF radix sort, the LBVH builder
+    against its CPU oracle, and the whole TLAS path against a synthetic scene database. No scene, no
+    renderer, no host repo. Results also go to the browser console.
+</p>
+
+<div class="controls">
+    <button data-run="all" class="primary">Run all</button>
+    <button data-run="sort">Sort</button>
+    <button data-run="bvh">BVH build</button>
+    <button data-run="tlas">TLAS end to end</button>
+    <button id="clear">Clear log</button>
+    <span id="status"></span>
+</div>
+
+<div class="panels">
+    <div id="log"></div>
+    <aside>
+        <h2>device</h2>
+        <div id="device"><div><span class="key">state</span><span>not acquired yet</span></div></div>
+    </aside>
+</div>
+
+<script type="module" src="./main.js"></script>
+
+</body>
+</html>

package/src/shade/playground/bvh_repro/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/bvh_repro/main.js"],"names":[],"mappings":""}