@woosh/meep-engine 3.69.0 → 3.70.0

package/src/shade/renderer/geometry/MeshletGeometrySerializationAdapter.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Opens the tree section of a payload whose tree is a BVH8: the ASCII bytes "BVH8" read as a
+ * little-endian u32.
+ *
+ * Most payloads carry no version of their own — a scene file, a geometry pack and a transfer between
+ * threads all call the adapter directly — so the section says what it is. Before the tag existed the
+ * section opened with the byte length of BVH2 nodes, a multiple of 32, which this value is not: a
+ * reader can always tell the two apart.
+ *
+ * @type {number}
+ */
+export const MESHLET_GEOMETRY_TREE_TAG_BVH8: number;
 /**
  * Round-trips a {@link MeshletGeometry} through a `BinaryBuffer`.
  *
@@ -10,6 +22,14 @@
  * The pipeline this supports: build the meshlets once in the asset build, serialize here, ship the
  * bytes, and let the runtime deserialize and upload. `serialize_bvh` decides whether the BLAS
  * travels with them or is rebuilt on load — carrying it costs bytes and saves the rebuild.
+ *
+ * A tree and its meshlets belong together: building the tree re-orders the triangles inside each
+ * meshlet ({@link blas_from_meshlets}), so a payload read without its tree comes back with its
+ * triangles in the rebuilt tree's order, which need not be the order they were written in.
+ *
+ * Payloads written before the tree was a BVH8 are read: their tree is skipped and rebuilt. That is
+ * why {@link version} has not moved — the tree section tells the two apart on every route, and the
+ * routes that carry a version are the fewest.
  */
 export class MeshletGeometrySerializationAdapter extends BinaryClassSerializationAdapter<any> {
     constructor();

package/src/shade/renderer/geometry/MeshletGeometrySerializationAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MeshletGeometrySerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/MeshletGeometrySerializationAdapter.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;GAYG;AACH;;IAGI,8BAAwB;IAGxB,uBAAqB;IAErB;;;OAGG;IACH,8BAFW,eAAe,QA6BzB;IAED;;;OAGG;IACH,gCAFW,eAAe,QAyCzB;CACJ;gDAtGM,uEAAuE;gCAE9C,sBAAsB"}
+{"version":3,"file":"MeshletGeometrySerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/MeshletGeometrySerializationAdapter.js"],"names":[],"mappings":"AAMA;;;;;;;;;;GAUG;AACH,6CAFU,MAAM,CAEyC;AAEzD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;;IAGI,8BAAwB;IAGxB,uBAAqB;IAErB;;;OAGG;IACH,8BAFW,eAAe,QA+BzB;IAED;;;OAGG;IACH,gCAFW,eAAe,QAkDzB;CACJ;gDAtIM,uEAAuE;gCAE9C,sBAAsB"}

package/src/shade/renderer/geometry/MeshletGeometrySerializationAdapter.js

@@ -4,6 +4,19 @@ import {
 import { blas_from_meshlets } from "./blas_from_meshlets.js";
 import { MeshletGeometry } from "./MeshletGeometry.js";
 
+/**
+ * Opens the tree section of a payload whose tree is a BVH8: the ASCII bytes "BVH8" read as a
+ * little-endian u32.
+ *
+ * Most payloads carry no version of their own — a scene file, a geometry pack and a transfer between
+ * threads all call the adapter directly — so the section says what it is. Before the tag existed the
+ * section opened with the byte length of BVH2 nodes, a multiple of 32, which this value is not: a
+ * reader can always tell the two apart.
+ *
+ * @type {number}
+ */
+export const MESHLET_GEOMETRY_TREE_TAG_BVH8 = 0x38485642;
+
 /**
  * Round-trips a {@link MeshletGeometry} through a `BinaryBuffer`.
  *
@@ -16,6 +29,14 @@ import { MeshletGeometry } from "./MeshletGeometry.js";
  * The pipeline this supports: build the meshlets once in the asset build, serialize here, ship the
  * bytes, and let the runtime deserialize and upload. `serialize_bvh` decides whether the BLAS
  * travels with them or is rebuilt on load — carrying it costs bytes and saves the rebuild.
+ *
+ * A tree and its meshlets belong together: building the tree re-orders the triangles inside each
+ * meshlet ({@link blas_from_meshlets}), so a payload read without its tree comes back with its
+ * triangles in the rebuilt tree's order, which need not be the order they were written in.
+ *
+ * Payloads written before the tree was a BVH8 are read: their tree is skipped and rebuilt. That is
+ * why {@link version} has not moved — the tree section tells the two apart on every route, and the
+ * routes that carry a version are the fewest.
  */
 export class MeshletGeometrySerializationAdapter extends BinaryClassSerializationAdapter {
 
@@ -49,6 +70,8 @@ export class MeshletGeometrySerializationAdapter extends BinaryClassSerializatio
         buffer.writeBytes(new Uint8Array(meshlets.data_buffer), 0, meshlets.data_buffer.byteLength);
 
         // serialize bvh
+        buffer.writeUint32(MESHLET_GEOMETRY_TREE_TAG_BVH8);
+
         if (this.serialize_bvh) {
             buffer.writeUint32(value.bvh.byteLength);
             buffer.writeBytes(new Uint8Array(value.bvh), 0, value.bvh.byteLength);
@@ -84,10 +107,19 @@ export class MeshletGeometrySerializationAdapter extends BinaryClassSerializatio
 
         // BVH
 
-        const bvh_buffer_size = buffer.readUint32();
+        const tree_tag = buffer.readUint32();
+
+        let bvh_buffer_size = 0;
+
+        if (tree_tag === MESHLET_GEOMETRY_TREE_TAG_BVH8) {
+            bvh_buffer_size = buffer.readUint32();
+        } else {
+            // no tag: what was read is the length of a BVH2, which nothing walks any more
+            buffer.skip(tree_tag);
+        }
 
-        if (bvh_buffer_size === 0 && value.primitive_count > 0) {
-            // BVH was not serialized, rebuild
+        if (bvh_buffer_size === 0) {
+            // no tree to take, build one
             value.bvh = blas_from_meshlets(
                 value.meshlets,
                 value.primitive_count,

package/src/shade/renderer/geometry/blas_from_meshlets.d.ts

@@ -1,9 +1,15 @@
 /**
+ * The bottom-level tree of a meshlet batch: the nodes of a BVH8 whose leaves name the batch's own
+ * triangles as `(meshlet << 8) | triangle`, root first, {@link BVH8_INODE_STRUCT} each. Child
+ * indices are relative to the root, so the bytes can sit anywhere in an arena.
  *
- * @param {MeshletBatch} meshlets
- * @param {number} primitive_count
+ * **Re-orders the triangles inside `meshlets`** ({@link bvh8_build_for_meshlets}): the tree and the
+ * batch belong together from here on, and any `(meshlet, triangle)` id taken before the call is stale.
+ *
+ * @param {MeshletBatch} meshlets triangles are re-ordered within each meshlet
+ * @param {number} primitive_count triangles in the batch
  * @param {Float32Array} bounding_box
- * @returns {ArrayBuffer}
+ * @returns {ArrayBuffer} empty for a batch with no triangles
  */
 export function blas_from_meshlets(meshlets: MeshletBatch, primitive_count: number, bounding_box: Float32Array): ArrayBuffer;
 //# sourceMappingURL=blas_from_meshlets.d.ts.map

package/src/shade/renderer/geometry/blas_from_meshlets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blas_from_meshlets.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/blas_from_meshlets.js"],"names":[],"mappings":"AAKA;;;;;;GAMG;AACH,4EAJW,MAAM,gBACN,YAAY,GACV,WAAW,CAyCvB"}
+{"version":3,"file":"blas_from_meshlets.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/blas_from_meshlets.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;GAYG;AACH,4EAJW,MAAM,gBACN,YAAY,GACV,WAAW,CAqBvB"}

package/src/shade/renderer/geometry/blas_from_meshlets.js

@@ -1,14 +1,20 @@
 import { assert } from "../../../core/assert.js";
-import { BVH } from "../../../core/bvh2/bvh3/BVH.js";
-import { bvh2_compress } from "./bvh/bvh2_compress.js";
-import { meshlet_batch_to_bvh } from "./meshlet_batch_to_bvh.js";
+import { BVH8 } from "../../../core/bvh8/BVH8.js";
+import { BVH8_INODE_STRUCT } from "../shader/chunk/bvh/bvh8/webgpu/BVH8_INODE_STRUCT.js";
+import { bvh8_build_for_meshlets } from "./bvh/bvh8_build_for_meshlets.js";
 
 /**
+ * The bottom-level tree of a meshlet batch: the nodes of a BVH8 whose leaves name the batch's own
+ * triangles as `(meshlet << 8) | triangle`, root first, {@link BVH8_INODE_STRUCT} each. Child
+ * indices are relative to the root, so the bytes can sit anywhere in an arena.
  *
- * @param {MeshletBatch} meshlets
- * @param {number} primitive_count
+ * **Re-orders the triangles inside `meshlets`** ({@link bvh8_build_for_meshlets}): the tree and the
+ * batch belong together from here on, and any `(meshlet, triangle)` id taken before the call is stale.
+ *
+ * @param {MeshletBatch} meshlets triangles are re-ordered within each meshlet
+ * @param {number} primitive_count triangles in the batch
  * @param {Float32Array} bounding_box
- * @returns {ArrayBuffer}
+ * @returns {ArrayBuffer} empty for a batch with no triangles
  */
 export function blas_from_meshlets(
     meshlets,
@@ -24,29 +30,9 @@ export function blas_from_meshlets(
         return new ArrayBuffer(0);
     }
 
-    const bvh2 = new BVH();
-
-    meshlet_batch_to_bvh({
-        bvh: bvh2,
-        meshlets,
-        bounding_box,
-        primitive_count,
-    });
-
-    assert.equal(bvh2.size, bvh2.node_capacity, 'bvh2 must be trimmed so size matches node_capacity');
-
-    if (bvh2.size === 0) {
-        return new ArrayBuffer(0);
-    }
-
-    const compressed = new ArrayBuffer(8 * 4 * bvh2.size);
-
-    bvh2_compress(
-        compressed, 0,
-        bvh2.data_buffer, 0,
-        bvh2.size
-    );
+    const bvh8 = new BVH8();
 
+    bvh8_build_for_meshlets(bvh8, meshlets, bounding_box);
 
-    return compressed;
-}
+    return bvh8.data_buffer.slice(0, bvh8.nodes.size * BVH8_INODE_STRUCT.size);
+}

package/src/shade/renderer/geometry/bvh/BLAS8_REFIT_TARGET_STRUCT.d.ts

@@ -0,0 +1,14 @@
+/**
+ * One BVH8 in a batched refit: where its nodes are, how many, where its part of the batch's spine
+ * starts, and which geometry's triangles it holds.
+ *
+ * A tree's nodes are one run of the arena, the root first; its part of the spine is the same run in
+ * the spine's own numbering, so that one buffer serves every tree of the batch.
+ *
+ * Read by {@link shader_blas8_refit_batch} once per workgroup, through its workgroup lookup.
+ *
+ * @type {WebGPUStruct}
+ */
+export const BLAS8_REFIT_TARGET_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=BLAS8_REFIT_TARGET_STRUCT.d.ts.map

package/src/shade/renderer/geometry/bvh/BLAS8_REFIT_TARGET_STRUCT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BLAS8_REFIT_TARGET_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/bvh/BLAS8_REFIT_TARGET_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,wCAFU,YAAY,CAoBC;6BA/BM,mCAAmC"}

package/src/shade/renderer/geometry/bvh/BLAS8_REFIT_TARGET_STRUCT.js

@@ -0,0 +1,33 @@
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+
+/**
+ * One BVH8 in a batched refit: where its nodes are, how many, where its part of the batch's spine
+ * starts, and which geometry's triangles it holds.
+ *
+ * A tree's nodes are one run of the arena, the root first; its part of the spine is the same run in
+ * the spine's own numbering, so that one buffer serves every tree of the batch.
+ *
+ * Read by {@link shader_blas8_refit_batch} once per workgroup, through its workgroup lookup.
+ *
+ * @type {WebGPUStruct}
+ */
+export const BLAS8_REFIT_TARGET_STRUCT = WebGPUStruct.from({
+    /**
+     * Arena node this tree's root sits at.
+     */
+    node_offset: u32,
+    /**
+     * Nodes in the tree.
+     */
+    node_count: u32,
+    /**
+     * Spine node this tree's root is published at.
+     */
+    spine_offset: u32,
+    /**
+     * Row in the geometry table whose meshlets the tree's nodes address. For a skinned clone, the
+     * clone's own row: the one whose positions skinning has just moved.
+     */
+    geometry_index: u32,
+}, "Blas8RefitTarget");

package/src/shade/renderer/geometry/bvh/GPUBLASRefitBatch.d.ts

@@ -2,29 +2,26 @@
  * Refit a set of BLAS trees every frame, as one batch: a fixed number of commands whatever the
  * number of trees, and no per-tree host work while the set and its residency hold still.
  *
- * The seam is the one the per-tree recorder had: an entry is an `owner` — the identity a tree
- * was registered under, per {@link GPUGeometryBVHManager#obtain} — and a `geometry_index`, the row
- * whose vertices the bounds come from. Nothing here knows what a clone is, or that skinning is why
- * the vertices moved; anything that deforms vertices in place can list its trees here.
+ * An entry is an `owner` — the identity a tree was registered under, per
+ * {@link GPUGeometryBVHManager#obtain} — and a `geometry_index`, the row whose vertices the boxes
+ * come from. Nothing here knows what a clone is, or that skinning is why the vertices moved; anything
+ * that deforms vertices in place can list its trees here.
  *
- * Three tables live on the GPU between frames. The target rows ({@link BLAS_REFIT_TARGET_STRUCT})
- * say where each tree sits in the manager's arenas and where its arrival counters sit in the
- * batch's own; the two lookups say, for every workgroup of a dispatch, which tree it serves and
- * which run of that tree's leaves — or, for the seeding pass, of its node slots. All three are
- * rebuilt from {@link GPUGeometryBVHManager#get_refit_target} when the entries change or the
- * manager's {@link GPUGeometryBVHManager#residency_version} moves, and not otherwise. Entries whose
- * tree is not resident yet are simply absent from the tables; the version moving is what brings
+ * Two tables live on the GPU between frames. The target rows ({@link BLAS8_REFIT_TARGET_STRUCT}) say
+ * where each tree sits in the manager's arena and where its part of the batch's spine starts; the
+ * lookup says, for every workgroup of the dispatch, which tree it serves and which run of that tree's
+ * nodes. Both are rebuilt from {@link GPUGeometryBVHManager#get_refit_target} when the entries change
+ * or the manager's {@link GPUGeometryBVHManager#residency_version} moves, and not otherwise. Entries
+ * whose tree is not resident yet are simply absent from the tables; the version moving is what brings
  * them in.
  *
- * Every frame is then: two transient buffers, the counters and the deferred list, with a clear
- * each; {@link shader_blas_refit_batch_seed} and then {@link shader_blas_refit_batch}, one dispatch
- * per page of workgroups under the device's per-dimension cap — one page for well over a hundred
- * characters of the playground's size; and one indirect {@link shader_bvh_refit_repair}, which runs
- * nothing unless a climb read a box before it arrived (R1 in GPU_BVH_BUILD_PLAN.md).
+ * Every frame is then one transient buffer, the spine, with its clear, and
+ * {@link shader_blas8_refit_batch}: one dispatch per page of workgroups under the device's
+ * per-dimension cap.
  *
  * `record` belongs inside {@link GPUMeshSkinningContext#update}, or somewhere with the same
- * guarantee: it binds the manager's arena buffers as they are at that moment, and those buffers are
- * replaced — the old ones destroyed — when an arena grows in {@link GPUGeometryBVHManager#update}.
+ * guarantee: it binds the manager's arena buffer as it is at that moment, and that buffer is
+ * replaced — the old one destroyed — when the arena grows in {@link GPUGeometryBVHManager#update}.
  * That runs before the frame's command context exists, so a refit recorded inside the frame is safe
  * by call order. A refit recorded across one of those updates would submit a destroyed buffer, and
  * the software device cannot catch it, since it executes nothing at submit.
@@ -38,7 +35,7 @@ export class GPUBLASRefitBatch {
      * The set of trees to refit from now on. Replaces the previous set; the tables are rebuilt on the
      * next {@link record}.
      *
-     * An owner may appear once: two rows for one tree would be two climbs racing on its nodes.
+     * An owner may appear once: two rows for one tree would be two sets of lanes writing its nodes.
      *
      * @param {{owner: object, geometry_index: number}[]} entries
      */
@@ -51,8 +48,8 @@ export class GPUBLASRefitBatch {
      *
      * @param {ShadeGPUCommandContext} cmd
      * @param {Object} options
-     * @param {GPUGeometryBVHManager} options.blas tree residency — arenas for nodes, parents and leaf lists
-     * @param {GPUGeometryManager} options.geometries geometry metadata table the leaf boxes read vertices through
+     * @param {GPUGeometryBVHManager} options.blas tree residency — the node arena
+     * @param {GPUGeometryManager} options.geometries geometry metadata table the boxes read vertices through
      * @returns {boolean} whether anything was recorded
      */
     record(cmd: ShadeGPUCommandContext, { blas, geometries }: {

package/src/shade/renderer/geometry/bvh/GPUBLASRefitBatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUBLASRefitBatch.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/bvh/GPUBLASRefitBatch.js"],"names":[],"mappings":"AA0BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH;IAiFI;;OAEG;IACH,+BAIC;IAED;;;;;;;OAOG;IACH,qBAFW;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAC,EAAE,QAkBnD;IAED;;;;;;;;OAQG;IACH;QAJ0C,IAAI;QACP,UAAU;QACpC,OAAO,CA0FnB;IA0JD,gBAqBC;;CACJ"}
+{"version":3,"file":"GPUBLASRefitBatch.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/bvh/GPUBLASRefitBatch.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IAgEI;;OAEG;IACH,+BAIC;IAED;;;;;;;OAOG;IACH,qBAFW;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAC,EAAE,QAkBnD;IAED;;;;;;;;OAQG;IACH;QAJ0C,IAAI;QACP,UAAU;QACpC,OAAO,CAmDnB;IA4ID,gBAgBC;;CACJ"}