@woosh/meep-engine 3.14.2 → 3.14.4

package/src/shade/playground/skinned_blas_refit/verify_leaf_triangles.js

@@ -3,9 +3,6 @@ import {
     BVH_NODE_BOUNDS_WORD,
     BVH_NODE_STRIDE_WORDS
 } from "../../renderer/gpu_primitive/bvh/BVH_BUFFER_LAYOUT.js";
-import {
-    BLAS_LEAF_BOUNDS_SETTINGS_STRUCT
-} from "../../renderer/geometry/bvh/shader_blas_refit_leaf_bounds.js";
 import { BVH2_NODE_STRUCT } from "../../renderer/shader/chunk/bvh/BVH2_NODE_STRUCT.js";
 import { shader_blas_audit_leaf_triangles } from "./shader_blas_audit_leaf_triangles.js";
 
@@ -149,6 +146,7 @@ export async function verify_leaf_triangles({
     let worst = 0;
 
     const examples = [];
+    const escaped_leaves = [];
 
     for (let i = 0; i < leaf_count; i++) {
         const base = leaves[i] * BVH_NODE_STRIDE_WORDS + BVH_NODE_BOUNDS_WORD;
@@ -169,6 +167,7 @@ export async function verify_leaf_triangles({
 
         if (error > tolerance) {
             escaped += 1;
+            escaped_leaves.push(i);
 
             if (examples.length < 5) {
                 examples.push({
@@ -187,6 +186,7 @@ export async function verify_leaf_triangles({
     const result = {
         leaf_count,
         escaped,
+        escaped_leaves,
         worst: +worst.toFixed(5),
         examples,
         verdict: escaped === 0

package/src/shade/playground/skinned_blas_refit/verify_skinned_blas_refit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify_skinned_blas_refit.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/verify_skinned_blas_refit.js"],"names":[],"mappings":"AA2JA;;;;;;;;;;;;;;;GAeG;AACH;IAP6B,QAAQ;IACC,MAAM;IAClB,KAAK;IACC,IAAI;IACR,SAAS,GAA1B,MAAM;IACJ,QAAQ,MAAM,CAAC,CAkF3B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAJ6B,QAAQ;IACD,QAAQ;IAC/B,QAAQ,MAAM,CAAC,CA4F3B"}
+{"version":3,"file":"verify_skinned_blas_refit.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/verify_skinned_blas_refit.js"],"names":[],"mappings":"AA2JA;;;;;;;;;;;;;;;GAeG;AACH;IAP6B,QAAQ;IACC,MAAM;IAClB,KAAK;IACC,IAAI;IACR,SAAS,GAA1B,MAAM;IACJ,QAAQ,MAAM,CAAC,CAkF3B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAJ6B,QAAQ;IACD,QAAQ;IAC/B,QAAQ,MAAM,CAAC,CA8F3B"}

package/src/shade/playground/skinned_blas_refit/verify_skinned_blas_refit.js

@@ -6,7 +6,7 @@ import {
     BVH_NODE_STRIDE_WORDS
 } from "../../renderer/gpu_primitive/bvh/BVH_BUFFER_LAYOUT.js";
 import { bvh2_check_containment } from "../../renderer/geometry/bvh/bvh2_check_bounds.js";
-import { record_blas_refit } from "../../renderer/geometry/bvh/record_blas_refit.js";
+import { GPUBLASRefitBatch } from "../../renderer/geometry/bvh/GPUBLASRefitBatch.js";
 import { BVH2_NODE_STRUCT } from "../../renderer/shader/chunk/bvh/BVH2_NODE_STRUCT.js";
 import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
 
@@ -26,7 +26,7 @@ const BVH_NULL_NODE = 0xffffffff;
  *   - `shader_meshlet_bounds_reduce` atomically merges every deformed vertex into the clone's
  *     geometry-metadata bounding box. It exists for the rasterizer's culling and knows nothing
  *     about trees.
- *   - {@link record_blas_refit} takes each leaf triangle's box and climbs the tree. The root node
+ *   - {@link GPUBLASRefitBatch} takes each leaf triangle's box and climbs the tree. The root node
  *     ends up bounding every triangle.
  *
  * Same vertices, same frame, two paths that share no code. They have to agree, and a stale BLAS
@@ -296,17 +296,19 @@ export async function verify_leaf_correspondence({ renderer, geometry }) {
 
     const cmd = ShadeGPUCommandContext.create(graphics, 'verify/leaf correspondence');
 
-    record_blas_refit(cmd, {
-        blas: geometries.blas,
-        geometries,
-        owner: metadata,
-        geometry_index: metadata.index,
-    });
+    // a batch of one: the source geometry, refitted from its own undeformed vertices
+    const batch = new GPUBLASRefitBatch(device);
+
+    batch.set_entries([{ owner: metadata, geometry_index: metadata.index }]);
+
+    batch.record(cmd, { blas: geometries.blas, geometries });
 
     cmd.finish();
 
     await device.queue.onSubmittedWorkDone();
 
+    batch.destroy();
+
     const region = new Float32Array(await read_back(
         device,
         geometries.blas.buffer_data,

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

@@ -0,0 +1,122 @@
+# skinned mesh soup — repro
+
+The character from `skinned_blas_refit`, loaded the way the game loads one, with the pieces that
+could be making soup on switches.
+
+```bash
+npm run dev
+```
+
+then open `/src/shade/playground/skinned_mesh_soup/index.html`.
+
+`?count=N` for N characters, `?skin=off|bind|animated`, `?trace=1` for the path tracer. Every switch
+is in the url so a state worth showing someone can be sent as a link.
+
+## What it turned out to be
+
+**`chunk_skin_blend_mesh_local` requires `inverse(mesh.global) × joint.global × inverse_bind` to be
+rigid. For `Michelle.glb` it carries a uniform scale of exactly 100, and a dual quaternion cannot
+carry a scale.**
+
+The chunk's own doc comment states the precondition — *"the four products must be rigid, which holds
+whenever the joints and the mesh node share the scaling ancestors"* — and names the shape it was
+written for: an FBX-derived glTF that puts its unit conversion on a root node and authors the
+inverse-bind matrices in **pre-scale** mesh space, so `joint.global × inverse_bind` carries the same
+scale `mesh.global` does and the fold cancels it.
+
+Michelle is the other legal shape. Her POSITION data and her inverse-bind matrices are authored in
+the **already-scaled** space — 1.66 m tall, Y-up, as they stand — so
+
+```
+joint.global × inverse_bind = I          for every one of her 65 joints
+mesh.global                 = 0.01 scale × the up-axis rotation, from her "Character" root
+```
+
+and the fold is `inverse(mesh.global) × I`, a bare **100×**. Measured, at bind and under the dance:
+every folded matrix's column length is `100.0000`, where rigid is 1.
+
+`dual_quat_from_m4` builds its quaternion from `sqrt(max(0, 1 ± m00 ± m11 ± m22))`. Those terms are
+`1 + 100·(…)`, so the `1` is swamped and every component whose sum goes negative is **clamped to
+zero** by the `max`. The rotation it extracts is not the matrix's rotation, and how wrong it is
+depends on the matrix — so it is wrong differently for every joint. That is the soup: not one
+transform applied badly, but sixty-five of them disagreeing.
+
+The two modes make the mechanism visible:
+
+| `?skin=` | what you see | why |
+| --- | --- | --- |
+| `bind` | the right character, exactly 1/100 the size | every joint folds to the *same* matrix, `100·Rx(90°)`. Its `w` and `x` terms are both `1 + 100`, its `y` and `z` both clamp to zero, and the normalize recovers `Rx(90°)` — by luck. Only the scale is lost. Sampled output is `expected / 100` to the digit. |
+| `animated` | soup | the joints' matrices differ, each loses a different amount, and the mesh comes apart. Mean error 121 in a mesh-local space where the body is 224 across; worst 165, on vertices bound to **a single joint at weight 1** — so the blend is not even involved. |
+
+`__soup_blend_probe.spec.js` is that measurement: the WGSL of `dual_quat_from_m4`,
+`dual_quat_blend4` and `dual_quat_transform_point` ported to JS, run over the character's own
+matrices at bind and at `t = 0.5 s` of `SambaDance`, against the position the glTF formula puts each
+vertex at. No device.
+
+### What it is not
+
+`__soup_probe.spec.js` is the ruling-out, and every one of these passes on the parsed asset before a
+GPU is involved:
+
+- the geometry is a surface, not a soup — 28 106 triangles, no degenerates, longest edge 0.093
+  against a 2.24 diagonal, every meshlet index in range;
+- the skinning attributes are sound — all 19 106 vertices land back on their rest position under
+  `joint.global × inverse_bind`, no zero-weight vertices, no out-of-range joint;
+- the source BLAS is exact — 56 211 nodes all reachable, 28 106 leaves each naming a distinct
+  triangle whose box matches to the bit, all 28 105 internal nodes exactly their children's union.
+
+So it is not the loader, not the meshlet build, not the tree, and not the refit. `skinned_blas_refit`'s
+`verify()` cannot see this at all, and that is worth saying plainly: it holds the tree's root box
+against the bounds chain's box, and **both are derived from the clone's vertex region**. Vertices
+that are wrong in the same way agree with each other perfectly. A green `verify()` and a soup
+picture are consistent.
+
+## The fix, and why it is a choice
+
+The scale is uniform, so it factors: `M = s · Rigid` means `M · p = s · (Rigid · p)`. Dividing the
+folded matrix's 3×3 and its translation by `s = length(column 0)` before the conversion, and scaling
+the transformed position by `s` after, is exact for any uniform scale and costs a length and three
+multiplies per joint. It does not help a *non-uniform* one, which a dual quaternion cannot carry
+either — that would want the linear-blend path the DQ one replaced.
+
+The other end is the loader: normalise a skin on load so `joint.global × inverse_bind` and
+`mesh.global` always agree about the scale, and the shader's precondition becomes true by
+construction rather than by the exporter's habits. That is a bigger change and it touches every
+asset, not just this one.
+
+Not taken here — this page is the repro and the measurement. Whichever end it is fixed at,
+`chunk_skin_blend_mesh_local.spec.js` is where the red test belongs: a folded matrix carrying a
+uniform scale, and the position it must still produce.
+
+## The switches
+
+- **`?skin=off`** — no skin registered. A `SkinnedMesh` still gets a vertex clone
+  (`GPUMeshSkinningContext#obtain_geometry_index` allocates one for every skinned mesh), but nothing
+  deforms it, so what is drawn is the memcpy of the source: the rest pose under the mesh node's own
+  transform. For Michelle a *correct* result is a 1.7 cm figure on her side. Soup here would be the
+  geometry upload — the meshlet copy or its address patch — and nothing to do with skinning.
+- **`?skin=bind`** — the skin registered, no clip. `await diagnose()` in the console reads the
+  clone's vertices back off the GPU and holds them against `inverse(mesh.global) × rest`, which is
+  what the bind pose must produce. It reports which vertices are wrong and in what shape: a
+  vertex-slot range says the workgroup stride loop, whole meshlets say addressing, and a uniform
+  factor says this bug. It checks the clone's meshlet records address a region of their own first —
+  a clone still pointing at the source's vertex data would be deforming the shared rest pose in
+  place.
+- **`?skin=animated`** — the file's dance, as `skinned_blas_refit` runs it.
+- **Path tracer** — off by default. The rasterizer reads the deformed vertices directly, with no
+  tree in the way, so it is the reading to establish the answer on: soup in *both* is the vertices,
+  soup in the tracer alone is the tree.
+
+## Why through `GLTFSceneBundleAssetLoader`
+
+`skinned_blas_refit` calls `load_gltf` directly and parses the file once per character. The asset
+loader is what the game and the editor register, and it hands out **the same bundle** to every
+caller — so a second character is not a second parse, it is `instantiate_scene_bundle`: its own node
+tree, its own skins bound to that tree's joints, its own clips retargeted onto it, sharing the
+geometry and the inverse-bind matrices. Running the repro on that path is what makes a fix found
+here a fix for the engine rather than for one prototype page.
+
+## Assets
+
+`/test_assets/Michelle.glb`, gitignored and unpublished — see `test_assets/README.md`. The two
+probes skip themselves when it is absent.

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

@@ -0,0 +1,199 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>meep — skinned mesh soup</title>
+    <style>
+        :root {
+            color-scheme: dark;
+            --panel: rgba(20, 22, 26, 0.88);
+            --line: #2b3038;
+            --text: #d6dae0;
+            --muted: #8b939f;
+            --pass: #55c46a;
+            --fail: #ff6b6b;
+            --warn: #e5b54a;
+        }
+
+        * { box-sizing: border-box; }
+
+        html, body { margin: 0; height: 100%; overflow: hidden; background: #0d0f12; }
+
+        /* body carries tabindex so the camera controller's keyboard device has something focusable
+           to listen on; the focus ring around the whole viewport is not wanted */
+        body:focus { outline: none; }
+
+        #view { display: block; width: 100vw; height: 100vh; }
+
+        #panel {
+            position: fixed;
+            top: 12px;
+            left: 12px;
+            width: 340px;
+            padding: 12px 14px;
+            background: var(--panel);
+            border: 1px solid var(--line);
+            border-radius: 8px;
+            backdrop-filter: blur(6px);
+            color: var(--text);
+            font: 13px/1.5 system-ui, -apple-system, Segoe UI, sans-serif;
+        }
+
+        #panel h1 { font-size: 13px; font-weight: 600; margin: 0 0 8px; }
+
+        label { display: flex; align-items: center; gap: 8px; padding: 3px 0; cursor: pointer; }
+        label input { margin: 0; }
+        label .hint { color: var(--muted); font-size: 11.5px; }
+
+        hr { border: 0; border-top: 1px solid var(--line); margin: 10px 0; }
+
+        button, select, input[type=number] {
+            font: inherit;
+            padding: 5px 9px;
+            border-radius: 6px;
+            border: 1px solid var(--line);
+            background: #1c1f25;
+            color: var(--text);
+        }
+
+        button { cursor: pointer; }
+        button:hover:not(:disabled) { border-color: #3d4552; }
+        button:disabled { opacity: 0.45; cursor: default; }
+
+        select { width: 100%; cursor: pointer; }
+
+        .row { display: flex; gap: 6px; align-items: center; margin-top: 6px; }
+        .row button { flex: 0 0 auto; }
+
+        #character_count {
+            flex: 1 1 auto;
+            min-width: 0;
+            font: 12px ui-monospace, SFMono-Regular, Consolas, monospace;
+            background: #14161a;
+        }
+
+        #status { font-size: 12px; color: var(--muted); word-break: break-word; }
+        #status.pass { color: var(--pass); }
+        #status.fail { color: var(--fail); }
+        #status.warn { color: var(--warn); }
+
+        #stats {
+            margin-top: 6px;
+            font: 12px ui-monospace, SFMono-Regular, Consolas, monospace;
+            color: var(--text);
+        }
+
+        p.note { margin: 8px 0 0; font-size: 11.5px; color: var(--muted); }
+
+        code { font: 11.5px ui-monospace, SFMono-Regular, Consolas, monospace; color: var(--text); }
+
+        dl { margin: 6px 0 0; font-size: 11.5px; color: var(--muted); }
+        dt { color: var(--text); font-weight: 600; margin-top: 6px; }
+        dd { margin: 0; }
+    </style>
+</head>
+<body tabindex="0">
+
+<canvas id="view"></canvas>
+
+<div id="panel">
+    <h1>Skinned mesh soup</h1>
+
+    <p class="note">
+        The same character <code>skinned_blas_refit</code> draws, loaded through
+        <code>GLTFSceneBundleAssetLoader</code> — one bundle, one instance per placement — with the
+        pieces that could be making soup on switches.
+    </p>
+    <p class="note">
+        <strong>The answer, for the record.</strong> <code>chunk_skin_blend_mesh_local</code> needs
+        <code>inverse(mesh.global) × joint.global × inverse_bind</code> to be rigid; for this file
+        it carries a uniform <strong>100×</strong>, and a dual quaternion cannot carry a scale. So
+        <code>bind</code> below is the right character at 1/100 size — one shared matrix, one shared
+        error — and <code>animated</code> is soup, sixty-five matrices each losing a different
+        amount. The README has the measurement.
+    </p>
+
+    <hr>
+
+    <label for="skin_mode"><span>How the skin is driven</span></label>
+    <select id="skin_mode">
+        <option value="off">off — no skin registered, nothing deforms the clone</option>
+        <option value="bind">bind — skin registered, no clip</option>
+        <option value="animated">animated — the file's dance, playing</option>
+    </select>
+
+    <dl>
+        <dt>off</dt>
+        <dd>
+            What is drawn is the clone's memcpy of the source: the rest pose under the mesh node's
+            own transform. Michelle's carries the file's centimetre scale and its up-axis rotation,
+            so <em>correct</em> here is a 1.7 cm figure on her side. Soup here is the geometry
+            upload, not skinning.
+        </dd>
+        <dt>bind</dt>
+        <dd>
+            The skinning pass runs every frame over a pose that never moves — and that pose has an
+            answer the CPU knows exactly. <code>await diagnose()</code> reads the clone's vertices
+            back and says which are wrong, and whether the wrong ones are a vertex-slot range (the
+            workgroup stride loop) or whole meshlets (addressing).
+        </dd>
+        <dt>animated</dt>
+        <dd>
+            Soup only in this mode is the pose: the joint matrices, their range, or the order the
+            skin's joints resolved in.
+        </dd>
+    </dl>
+
+    <hr>
+
+    <label>
+        <input type="checkbox" id="path_tracing">
+        <span>Path tracer <span class="hint">— traverses the BLAS</span></span>
+    </label>
+    <p class="note">
+        Off by default. The rasterizer reads the deformed vertices directly, with no tree in the
+        way, so it is the reading to establish the answer on first: soup in <em>both</em> is the
+        vertices, soup in the tracer alone is the tree.
+    </p>
+
+    <div class="row">
+        <button id="animation">Freeze pose</button>
+    </div>
+
+    <hr>
+
+    <div class="row">
+        <input type="number" id="character_count" value="1" min="1" max="64" step="1">
+        <button id="respawn">Characters</button>
+    </div>
+    <p class="note">
+        One parse whatever the count — the asset hands out the model itself, and each placement gets
+        its own node tree, skins and clips from <code>instantiate_scene_bundle</code>.
+    </p>
+
+    <hr>
+
+    <div id="status"></div>
+    <div id="stats"></div>
+
+    <p class="note">
+        Every switch is in the url — <code>?count=1&amp;skin=bind&amp;trace=1</code> — so a state
+        worth showing someone can be sent as a link.
+    </p>
+</div>
+
+<script type="module">
+    import { start } from './main.js';
+
+    start().catch(error => {
+        const status = document.getElementById('status');
+
+        status.className = 'fail';
+        status.textContent = String(error?.message ?? error);
+
+        console.error(error);
+    });
+</script>
+
+</body>
+</html>

package/src/shade/playground/skinned_mesh_soup/main.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Stand the page up.
+ *
+ * @returns {Promise<void>}
+ */
+export function start(): Promise<void>;
+//# sourceMappingURL=main.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_mesh_soup/main.js"],"names":[],"mappings":"AA8PA;;;;GAIG;AACH,yBAFa,QAAQ,IAAI,CAAC,CAkTzB"}