@woosh/meep-engine 3.23.0 → 3.25.0

package/src/engine/graphics3/shade_bundle_bounds.js

@@ -1,55 +1,47 @@
-import { assert } from "../../core/assert.js";
-import { aabb3_array_combine } from "../../core/geom/3d/aabb/aabb3_array_combine.js";
-
-/**
- * The box a loaded model occupies, in the model's own space.
- *
- * **Matrices are refreshed here.** A `Mesh`'s `bounding_box` is its geometry's box projected
- * through its global transform, and a bundle handed straight off a loader has never had
- * {@link Node3D.updateMatrices} run on it — so asking for the bounds without refreshing them reads
- * whatever the loader left, which for a node under a transformed parent is the wrong box.
- *
- * A bundle with no geometry in it — a file that is all empties, or a scene that is only lights —
- * has no bounds, and that is what `false` says. `result` is untouched then.
- *
- * @param {AABB3} result
- * @param {SceneBundle} bundle
- * @returns {boolean} whether the bundle had any geometry to bound
- */
-export function shade_bundle_bounds(result, bundle) {
-    assert.defined(result, 'result');
-    assert.defined(bundle, 'bundle');
-
-    let found = false;
-
-    /**
-     * @param {Mesh} node
-     */
-    function combine(node) {
-        if (node.isMesh !== true) {
-            // a grouping node carries no geometry, so it has no bounds of its own
-            return;
-        }
-
-        const bounds = node.bounding_box;
-
-        if (found) {
-            aabb3_array_combine(result, 0, result, 0, bounds, 0);
-        } else {
-            result.setBounds(bounds[0], bounds[1], bounds[2], bounds[3], bounds[4], bounds[5]);
-
-            found = true;
-        }
-    }
-
-    const scenes = bundle.scenes;
-
-    for (let i = 0; i < scenes.length; i++) {
-        const root = scenes[i];
-
-        root.updateMatrices();
-        root.traverse(combine);
-    }
-
-    return found;
-}
+import { assert } from "../../core/assert.js";
+import { aabb3_array_combine } from "../../core/geom/3d/aabb/aabb3_array_combine.js";
+import { aabb3_matrix4_project } from "../../core/geom/3d/aabb/aabb3_matrix4_project.js";
+
+const SCRATCH_BOX = new Float64Array(6);
+
+/**
+ * The box a loaded model occupies, in the model's own space: every primitive's geometry box
+ * under its node's world transform, composed here from the bundle's locals.
+ *
+ * A bundle with no geometry in it — a file that is all empties, or a scene that is only lights —
+ * has no bounds, and that is what `false` says. `result` is untouched then.
+ *
+ * @param {AABB3} result
+ * @param {SceneBundle} bundle
+ * @returns {boolean} whether the bundle had any geometry to bound
+ */
+export function shade_bundle_bounds(result, bundle) {
+    assert.defined(result, 'result');
+    assert.defined(bundle, 'bundle');
+    assert.equal(bundle.isSceneBundle, true, 'bundle.isSceneBundle !== true');
+
+    const nodes = bundle.nodes;
+    const worlds = bundle.compute_world_matrices();
+
+    let found = false;
+
+    for (let i = 0; i < nodes.length; i++) {
+        const geometry = nodes[i].geometry;
+
+        if (geometry === null) {
+            // a grouping node carries no geometry, so it has no bounds of its own
+            continue;
+        }
+
+        aabb3_matrix4_project(SCRATCH_BOX, geometry.bounding_box, worlds[i]);
+
+        if (found) {
+            aabb3_array_combine(result, 0, result, 0, SCRATCH_BOX, 0);
+        } else {
+            result.setBounds(SCRATCH_BOX[0], SCRATCH_BOX[1], SCRATCH_BOX[2], SCRATCH_BOX[3], SCRATCH_BOX[4], SCRATCH_BOX[5]);
+            found = true;
+        }
+    }
+
+    return found;
+}

package/src/engine/graphics3/shader_picking_gather.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Words a query occupies, on the way in and on the way back: a pixel's x and y going in, the mesh
+ * row and the depth's bit pattern coming out.
+ *
+ * @type {number}
+ */
+export const PICKING_GATHER_STRIDE_WORDS: number;
+/**
+ * The `x` of a query whose point is not on the view at all.
+ *
+ * A pick names a fraction of the view and a caller is free to ask outside it, so a query carries
+ * either a pixel or this. No pixel can collide with it: `maxTextureDimension2D` is nowhere near
+ * 2^32 - 1 in any WebGPU profile, so there is no view this is a column of.
+ *
+ * @type {number}
+ */
+export const PICKING_QUERY_OFF_VIEW: number;
+/**
+ * @type {number}
+ */
+export const PICKING_GATHER_WORKGROUP_SIZE: number;
+/**
+ * Reads the visibility buffer's mesh row and the frame's depth at a handful of pixels, into a
+ * buffer small enough to read back on a click.
+ *
+ * **A dispatch rather than a copy, twice over.** The obvious shape for this is
+ * `copyTextureToBuffer` of a 1x1 region per query, and it is not legal WebGPU for either texture.
+ * The visibility buffer is a render attachment the renderer never gave `COPY_SRC` — and should not
+ * have to, since the flag is for the whole frame and a pick happens on a click — while a depth
+ * format may not be sub-region copied **at all**: "if the format is a depth-or-stencil format [...]
+ * the subresource size is equal to size", so the only legal copy of a 1065x1668 depth buffer is all
+ * 7 MB of it. Both textures are already `TEXTURE_BINDING`, because the frame shades from them, and
+ * `textureLoad` has neither restriction.
+ *
+ * One thread per query. Nothing is sampled, filtered or interpolated: the answer has to be the row
+ * the rasterizer wrote at that exact pixel, which is what makes a pick as precise as the frame.
+ */
+export const shader_picking_gather: ComputeShader;
+import { ComputeShader } from "../../shade/renderer/shader/ComputeShader.js";
+//# sourceMappingURL=shader_picking_gather.d.ts.map

package/src/engine/graphics3/shader_picking_gather.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_picking_gather.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/shader_picking_gather.js"],"names":[],"mappings":"AAWA;;;;;GAKG;AACH,0CAFU,MAAM,CAE6B;AAE7C;;;;;;;;GAQG;AACH,qCAFU,MAAM,CAEiC;AAEjD;;GAEG;AACH,4CAFU,MAAM,CAEgC;AAkEhD;;;;;;;;;;;;;;;GAeG;AACH,kDAIG;8BAnH2B,8CAA8C"}

package/src/engine/graphics3/shader_picking_gather.js

@@ -0,0 +1,120 @@
+import {
+    VIZ_BUFFER_INVALID_MESH_VALUE
+} from "../../shade/renderer/rasterize/native/viz/VIZ_BUFFER_INVALID_MESH_VALUE.js";
+import { CodeChunk } from "../../shade/renderer/shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shade/renderer/shader/ComputeShader.js";
+import {
+    ShaderResourceSetDescriptor
+} from "../../shade/renderer/shader/resource/ShaderResourceSetDescriptor.js";
+import { u32 } from "../../shade/renderer/shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shade/renderer/shader/type/WebGPUArray.js";
+
+/**
+ * Words a query occupies, on the way in and on the way back: a pixel's x and y going in, the mesh
+ * row and the depth's bit pattern coming out.
+ *
+ * @type {number}
+ */
+export const PICKING_GATHER_STRIDE_WORDS = 2;
+
+/**
+ * The `x` of a query whose point is not on the view at all.
+ *
+ * A pick names a fraction of the view and a caller is free to ask outside it, so a query carries
+ * either a pixel or this. No pixel can collide with it: `maxTextureDimension2D` is nowhere near
+ * 2^32 - 1 in any WebGPU profile, so there is no view this is a column of.
+ *
+ * @type {number}
+ */
+export const PICKING_QUERY_OFF_VIEW = 0xFFFFFFFF;
+
+/**
+ * @type {number}
+ */
+export const PICKING_GATHER_WORKGROUP_SIZE = 64;
+
+const resources = new ShaderResourceSetDescriptor();
+
+// per-dispatch, four bytes, read-only: immediate data rather than a uniform buffer
+resources.setImmediate("query_count", u32);
+
+resources.createGroup()
+    // The frame's visibility buffer — the `meshes` row the rasterizer wrote at each pixel — and the
+    // depth it wrote with it. Both are read as *bindings*, which is the whole reason this pass is a
+    // dispatch: see the note on {@link shader_picking_gather}.
+    .addTexture("viz_mesh", "uint")
+    .addTexture("viz_depth", "depth");
+
+resources.createGroup()
+    // x, y per query; `PICKING_QUERY_OFF_VIEW` in x for a query that is off the view
+    .addStorageBuffer("queries", WebGPUArray.u32)
+    // mesh row, then the depth's bits, per query
+    .addStorageBuffer("results", WebGPUArray.u32, true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const PICKING_STRIDE : u32 = ${PICKING_GATHER_STRIDE_WORDS}u;
+const PICKING_OFF_VIEW : u32 = ${PICKING_QUERY_OFF_VIEW}u;
+const PICKING_VIZ_INVALID : u32 = ${VIZ_BUFFER_INVALID_MESH_VALUE}u;
+
+@compute @workgroup_size(${PICKING_GATHER_WORKGROUP_SIZE},1,1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    let index = gid.x;
+
+    /*
+     The dispatch is sized to ceil(query_count / 64) workgroups, so the tail carries up to 63 idle
+     threads. Guarded on the immediate rather than on arrayLength: both buffers come from the
+     transient pool, which matches approximately, so their lengths are pool state rather than the
+     number of queries — a thread past the end would read a previous tenant's pixel and write a row
+     nobody asked for.
+    */
+    if index >= query_count {
+        return;
+    }
+
+    let base = index * PICKING_STRIDE;
+
+    let x = queries[base];
+    let y = queries[base + 1u];
+
+    /*
+     Every slot is written, the off-view ones included. A pooled buffer arrives carrying whatever its
+     last tenant left, and a query off the view has to read back as nothing rather than as that — so
+     the pass defines the whole of its output instead of a clear being encoded ahead of it.
+    */
+    if x == PICKING_OFF_VIEW {
+        results[base] = PICKING_VIZ_INVALID;
+        results[base + 1u] = 0u;
+
+        return;
+    }
+
+    let at = vec2<i32>(i32(x), i32(y));
+
+    results[base] = textureLoad(viz_mesh, at, 0).r;
+    results[base + 1u] = bitcast<u32>(textureLoad(viz_depth, at, 0));
+}
+`);
+
+/**
+ * Reads the visibility buffer's mesh row and the frame's depth at a handful of pixels, into a
+ * buffer small enough to read back on a click.
+ *
+ * **A dispatch rather than a copy, twice over.** The obvious shape for this is
+ * `copyTextureToBuffer` of a 1x1 region per query, and it is not legal WebGPU for either texture.
+ * The visibility buffer is a render attachment the renderer never gave `COPY_SRC` — and should not
+ * have to, since the flag is for the whole frame and a pick happens on a click — while a depth
+ * format may not be sub-region copied **at all**: "if the format is a depth-or-stencil format [...]
+ * the subresource size is equal to size", so the only legal copy of a 1065x1668 depth buffer is all
+ * 7 MB of it. Both textures are already `TEXTURE_BINDING`, because the frame shades from them, and
+ * `textureLoad` has neither restriction.
+ *
+ * One thread per query. Nothing is sampled, filtered or interpolated: the answer has to be the row
+ * the rasterizer wrote at that exact pixel, which is what makes a pick as precise as the frame.
+ */
+export const shader_picking_gather = ComputeShader.from({
+    label: "Picking/Gather",
+    resources,
+    body,
+});

package/src/engine/graphics3/terrain/pack_terrain_row_table.d.ts

@@ -1,26 +1,19 @@
 /**
- * Build the lookup the splat shader reads: one word per mesh row, 1 where the row is one of this
- * terrain's tiles, addressed by the row the visibility buffer writes.
+ * The lookup the splat pass reads a visibility-buffer mesh row through: one word per row, 1 for a
+ * row that is a tile of this terrain, 0 for anything else.
  *
- * **The scene decides the indices** — a tile that has not reached the scene database yet has no
- * row and contributes nothing, which is also what makes "no tile drawn yet" read as an empty
- * table rather than an error. Rebuilt per frame like the highlight table, and for the same
- * reason: rows move as the scene streams, and the walk is over this terrain's few tiles rather
- * than over the scene.
+ * A tile is an entity, and its row is the entity's, one on — so the table is sized by the highest
+ * tile entity and the rows in between belong to whatever else the level holds. Whether a row has
+ * been written yet is not this table's business: a row the scene has not placed is in no pixel of
+ * the visibility buffer, and marking it costs nothing.
  *
  * @param {object} args
- * @param {{values(): Iterable<Mesh>}} args.meshes the terrain's tile meshes, e.g. the entry's
- * `Map<TerrainTile, Mesh>`
- * @param {GPUSceneContext} args.scene resolves a node to its row
- * @param {Uint32Array} args.table reused between frames; replaced when it is too small
- * @returns {{table: Uint32Array, size: number}} `size` is one past the highest row written, and
- * zero when no tile is in the scene
+ * @param {Map<*, number>} args.tiles the terrain's tile entities, by whatever spawned them
+ * @param {Uint32Array} args.table the previous frame's table, reused when it is long enough
+ * @returns {{table: Uint32Array, size: number}} the table and how much of it is meaningful
  */
-export function pack_terrain_row_table({ meshes, scene, table }: {
-    meshes: {
-        values(): Iterable<Mesh>;
-    };
-    scene: GPUSceneContext;
+export function pack_terrain_row_table({ tiles, table }: {
+    tiles: Map<any, number>;
     table: Uint32Array;
 }): {
     table: Uint32Array;

package/src/engine/graphics3/terrain/pack_terrain_row_table.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pack_terrain_row_table.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/terrain/pack_terrain_row_table.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH;IAP4C,MAAM,EAAvC;QAAC,MAAM,IAAI,cAAc,CAAA;KAAC;IAEJ,KAAK;IACT,KAAK,EAAvB,WAAW;IACT;IAAC,KAAK,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAqC9C"}
+{"version":3,"file":"pack_terrain_row_table.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/terrain/pack_terrain_row_table.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH;IAJgC,KAAK,EAA1B,SAAO,MAAM,CAAC;IACI,KAAK,EAAvB,WAAW;IACT;IAAC,KAAK,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAiC9C"}

package/src/engine/graphics3/terrain/pack_terrain_row_table.js

@@ -1,53 +1,48 @@
-/**
- * Build the lookup the splat shader reads: one word per mesh row, 1 where the row is one of this
- * terrain's tiles, addressed by the row the visibility buffer writes.
- *
- * **The scene decides the indices** — a tile that has not reached the scene database yet has no
- * row and contributes nothing, which is also what makes "no tile drawn yet" read as an empty
- * table rather than an error. Rebuilt per frame like the highlight table, and for the same
- * reason: rows move as the scene streams, and the walk is over this terrain's few tiles rather
- * than over the scene.
- *
- * @param {object} args
- * @param {{values(): Iterable<Mesh>}} args.meshes the terrain's tile meshes, e.g. the entry's
- * `Map<TerrainTile, Mesh>`
- * @param {GPUSceneContext} args.scene resolves a node to its row
- * @param {Uint32Array} args.table reused between frames; replaced when it is too small
- * @returns {{table: Uint32Array, size: number}} `size` is one past the highest row written, and
- * zero when no tile is in the scene
- */
-export function pack_terrain_row_table({ meshes, scene, table }) {
-    let highest = -1;
-
-    /*
-     Two sweeps, because the table has to be as long as the highest row before anything can be
-     written into it. Asking twice is cheaper than growing a typed array mid-walk.
-    */
-    for (const mesh of meshes.values()) {
-        const row = scene.mesh_row_of(mesh);
-
-        if (row > highest) {
-            highest = row;
-        }
-    }
-
-    const size = highest + 1;
-
-    let result = table;
-
-    if (result.length < size) {
-        result = new Uint32Array(size);
-    } else {
-        result.fill(0, 0, size);
-    }
-
-    for (const mesh of meshes.values()) {
-        const row = scene.mesh_row_of(mesh);
-
-        if (row >= 0) {
-            result[row] = 1;
-        }
-    }
-
-    return { table: result, size };
-}
+import { row_of_entity } from "../../../shade/renderer/scene/rows/GPUSceneRows.js";
+
+/**
+ * The lookup the splat pass reads a visibility-buffer mesh row through: one word per row, 1 for a
+ * row that is a tile of this terrain, 0 for anything else.
+ *
+ * A tile is an entity, and its row is the entity's, one on — so the table is sized by the highest
+ * tile entity and the rows in between belong to whatever else the level holds. Whether a row has
+ * been written yet is not this table's business: a row the scene has not placed is in no pixel of
+ * the visibility buffer, and marking it costs nothing.
+ *
+ * @param {object} args
+ * @param {Map<*, number>} args.tiles the terrain's tile entities, by whatever spawned them
+ * @param {Uint32Array} args.table the previous frame's table, reused when it is long enough
+ * @returns {{table: Uint32Array, size: number}} the table and how much of it is meaningful
+ */
+export function pack_terrain_row_table({ tiles, table }) {
+    let highest = -1;
+
+    /*
+     Two sweeps, because the table has to be as long as the highest row before anything can be
+     written into it. Asking twice is cheaper than growing a typed array mid-walk — and is why this
+     takes the map rather than an iterator, which would be spent by the first.
+    */
+    for (const tile of tiles.values()) {
+        const row = row_of_entity(tile);
+
+        if (row > highest) {
+            highest = row;
+        }
+    }
+
+    const size = highest + 1;
+
+    let result = table;
+
+    if (result.length < size) {
+        result = new Uint32Array(size);
+    } else {
+        result.fill(0, 0, size);
+    }
+
+    for (const tile of tiles.values()) {
+        result[row_of_entity(tile)] = 1;
+    }
+
+    return { table: result, size };
+}