@woosh/meep-engine 3.24.0 → 3.26.0

package/src/core/geom/3d/shape/UnionShape3D.js

@@ -7,6 +7,7 @@ import { min2 } from "../../../math/min2.js";
 import { seededRandom } from "../../../math/random/seededRandom.js";
 import { number_compare_ascending } from "../../../primitives/numbers/number_compare_ascending.js";
 import { v3_dot } from "../../vec3/v3_dot.js";
+import { Ray3 } from "../ray/Ray3.js";
 import { AbstractShape3D } from "./AbstractShape3D.js";
 import { compute_signed_distance_gradient_by_sampling } from "./util/compute_signed_distance_gradient_by_sampling.js";
 
@@ -326,6 +327,69 @@ export class UnionShape3D extends AbstractShape3D {
 
     }
 
+    /**
+     * Nearest hit across the children, which all share the union's own frame — so, unlike the other
+     * two wrappers, there is no ray to re-frame and no answer to map back.
+     *
+     * Each child is handed the best distance so far as its `tMax`, so a child can only report a hit by
+     * beating every child before it. That is what makes it safe to let the children write straight into
+     * `hit`: a child that writes is a child that won, and a child that misses leaves `hit` untouched by
+     * the family convention, so the standing answer survives it.
+     *
+     * The distance to narrow on is recovered from the point the child wrote, as
+     * `(p − origin)·direction` — the shape-level API hands back a point where the narrowphase's
+     * `refine_ray_union` has the distance already. Two children closer together than a float32 ulp
+     * of the coordinates involved are therefore a tie, settled by whichever is listed last.
+     *
+     * That ulp is the API's, not this method's: a child writes `origin + direction · t` into a float32
+     * `hit` before anything here reads it, so the resolution is already spent by the time a LONE shape
+     * answers. Measured against the narrowphase over 4,000 rays per scale, this union's error tracks a
+     * lone sphere's within a factor of two everywhere — 3e-6 near the origin, 1e-3 at 1e4 out, 0.1 at
+     * 1e6, where one float32 ulp IS 0.06 world units. A compound collider that far out wants a float64
+     * ray, which is what the narrowphase path already gives it; it does not want a different union.
+     *
+     * DIVERGENCE from `refine_ray_union`: that one carries a sentinel for a shape it cannot answer and
+     * poisons the entire union with it, because reporting the nearest of the children it COULD answer
+     * would be a hit confidently too far. There is no sentinel in this API — a child that does not
+     * implement `raycast` throws from {@link AbstractShape3D#raycast} — but the effect is the one that
+     * matters: every child is visited unconditionally, so such a child is never quietly skipped, and
+     * the throw leaves the union with no answer rather than a partial one.
+     *
+     * @param {Float32Array|number[]} hit out: [px, py, pz, nx, ny, nz]
+     * @param {Ray3} ray union-frame ray (origin in [0..2], unit direction in [3..5], tMax in [6])
+     * @returns {boolean} whether anything was hit
+     */
+    raycast(hit, ray) {
+        const children = this.children;
+        const child_count = children.length;
+
+        const ox = ray[0], oy = ray[1], oz = ray[2];
+        const dx = ray[3], dy = ray[4], dz = ray[5];
+
+        // Allocated per call rather than kept as a module scratch: a union may hold another wrapper,
+        // and every level of that recursion needs its own narrowing ray alive across the loop below.
+        const child_ray = new Ray3();
+
+        child_ray[0] = ox; child_ray[1] = oy; child_ray[2] = oz;
+        child_ray[3] = dx; child_ray[4] = dy; child_ray[5] = dz;
+        child_ray[6] = ray[6];
+
+        let found = false;
+
+        for (let i = 0; i < child_count; i++) {
+            if (!children[i].raycast(hit, child_ray)) {
+                continue;
+            }
+
+            // The direction is unit, so the hit's projection onto it IS the distance travelled.
+            child_ray[6] = (hit[0] - ox) * dx + (hit[1] - oy) * dy + (hit[2] - oz) * dz;
+
+            found = true;
+        }
+
+        return found;
+    }
+
     /**
      *
      * @param {UnionShape3D} other

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

@@ -2,12 +2,12 @@
  * Answers "what is under this pixel" for entities that asked to be pickable.
  *
  * **Off the visibility buffer.** The rasterizer writes every pixel's `meshes` row — an entity's
- * row, one on — and its depth; a pick copies those two texels out of the frame that drew them and
+ * row, one on — and its depth; a pick reads those two texels out of the frame that drew them and
  * resolves the row to the entity that drew it, then up its parents to the one that opted in. What
  * was drawn is what is picked: at triangle precision, under skinning, with nothing kept on the CPU
  * for it — no bounds, no tree, no per-frame refresh.
  *
- * **Asynchronous and batched, of necessity.** The texels are copied by the frame after the query
+ * **Asynchronous and batched, of necessity.** The texels are gathered by the frame after the query
  * was asked and read back when the device has finished it, so an answer is a frame or two late and
  * arrives for the whole batch at once. A result is a promise for that reason, and nothing this
  * tick can come to depend on it.
@@ -79,7 +79,7 @@ export class PickingSystem extends System<any> {
     #private;
 }
 /**
- * Copies the queried texels out of the frame that drew them, after the G-buffer is written and
+ * Gathers the queried texels out of the frame that drew them, after the G-buffer is written and
  * before anything overwrites the visibility buffer, and answers the batch when they land.
  */
 export class PickingExtension extends RenderExtension {

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

@@ -1 +1 @@
-{"version":3,"file":"PickingSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/PickingSystem.js"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;;GAgBG;AACH;IAyBI;;OAEG;IACH,sCAQC;IADG,kCAA8B;IAGlC,2CAIC;IAED,4CAYC;IAED;;;OAGG;IACH,eAHW,QAAQ,UACR,MAAM,QAIhB;IAED;;;OAGG;IACH,iBAHW,QAAQ,UACR,MAAM,QAIhB;IAED;;;;OAIG;IACH,6BAEC;IAED;;;;OAIG;IACH,4BAEC;IAED;;;;;;;;;;;OAWG;IACH,cAHW,cAAc,GACZ,QAAQ,aAAa,EAAE,CAAC,CAYpC;IAED;;;;OAIG;IACH,gBAFa;QAAC,OAAO,EAAE,cAAc,CAAC;QAAC,OAAO,SAAW,aAAa,EAAE,KAAG,IAAI,CAAC;QAAC,MAAM,SAAW,KAAK,KAAG,IAAI,CAAA;KAAC,EAAE,CAIhH;IAED;;;;;;OAMG;IACH,iBAHW,MAAM,GACJ,MAAM,CAuBlB;;CACJ;AAED;;;GAGG;AACH;IASI;;OAEG;IACH,oBAFW,aAAa,EAMvB;;CA8IJ;uBAhWsB,kBAAkB;yBAChB,eAAe;8BACV,oBAAoB;gCAPlB,mDAAmD"}
+{"version":3,"file":"PickingSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/PickingSystem.js"],"names":[],"mappings":"AA0BA;;;;;;;;;;;;;;;;GAgBG;AACH;IAyBI;;OAEG;IACH,sCAQC;IADG,kCAA8B;IAGlC,2CAIC;IAED,4CAYC;IAED;;;OAGG;IACH,eAHW,QAAQ,UACR,MAAM,QAIhB;IAED;;;OAGG;IACH,iBAHW,QAAQ,UACR,MAAM,QAIhB;IAED;;;;OAIG;IACH,6BAEC;IAED;;;;OAIG;IACH,4BAEC;IAED;;;;;;;;;;;OAWG;IACH,cAHW,cAAc,GACZ,QAAQ,aAAa,EAAE,CAAC,CAYpC;IAED;;;;OAIG;IACH,gBAFa;QAAC,OAAO,EAAE,cAAc,CAAC;QAAC,OAAO,SAAW,aAAa,EAAE,KAAG,IAAI,CAAC;QAAC,MAAM,SAAW,KAAK,KAAG,IAAI,CAAA;KAAC,EAAE,CAIhH;IAED;;;;;;OAMG;IACH,iBAHW,MAAM,GACJ,MAAM,CAuBlB;;CACJ;AAED;;;GAGG;AACH;IASI;;OAEG;IACH,oBAFW,aAAa,EAMvB;;CA4IJ;uBA7VsB,kBAAkB;yBAChB,eAAe;8BACV,oBAAoB;gCAPlB,mDAAmD"}

package/src/engine/graphics3/PickingSystem.js

@@ -11,30 +11,29 @@ import { ParentEntity } from "../ecs/parent/ParentEntity.js";
 import { System } from "../ecs/System.js";
 import { Pickable } from "./Pickable.js";
 import { PickingResult } from "./PickingResult.js";
+import {
+    PICKING_GATHER_STRIDE_WORDS,
+    PICKING_QUERY_OFF_VIEW,
+    shader_picking_gather
+} from "./shader_picking_gather.js";
 
 /**
- * Bytes one texel's copy occupies in the readback: WebGPU rounds `bytesPerRow` up to 256, and
- * each query copies two texels — the mesh row and the depth — one row each.
+ * Bytes a query occupies in the gather buffer: the mesh row and the depth, one word each.
  *
  * @type {number}
  */
-const TEXEL_STRIDE = 256;
-
-/**
- * @type {number}
- */
-const QUERY_STRIDE = TEXEL_STRIDE * 2;
+const QUERY_STRIDE = PICKING_GATHER_STRIDE_WORDS * 4;
 
 /**
  * Answers "what is under this pixel" for entities that asked to be pickable.
  *
  * **Off the visibility buffer.** The rasterizer writes every pixel's `meshes` row — an entity's
- * row, one on — and its depth; a pick copies those two texels out of the frame that drew them and
+ * row, one on — and its depth; a pick reads those two texels out of the frame that drew them and
  * resolves the row to the entity that drew it, then up its parents to the one that opted in. What
  * was drawn is what is picked: at triangle precision, under skinning, with nothing kept on the CPU
  * for it — no bounds, no tree, no per-frame refresh.
  *
- * **Asynchronous and batched, of necessity.** The texels are copied by the frame after the query
+ * **Asynchronous and batched, of necessity.** The texels are gathered by the frame after the query
  * was asked and read back when the device has finished it, so an answer is a frame or two late and
  * arrives for the whole batch at once. A result is a promise for that reason, and nothing this
  * tick can come to depend on it.
@@ -199,7 +198,7 @@ export class PickingSystem extends System {
 }
 
 /**
- * Copies the queried texels out of the frame that drew them, after the G-buffer is written and
+ * Gathers the queried texels out of the frame that drew them, after the G-buffer is written and
  * before anything overwrites the visibility buffer, and answers the batch when they land.
  */
 export class PickingExtension extends RenderExtension {
@@ -251,61 +250,57 @@ export class PickingExtension extends RenderExtension {
             }
         }
 
+        /*
+         The pixel each query names, resolved here rather than in the shader: the fraction is the
+         caller's unit and the resolution is the frame's, and neither is the gather's business. A
+         query that is not on the view at all carries `PICKING_QUERY_OFF_VIEW` instead of a pixel.
+        */
+        const pixels = new Uint32Array(queries.length * PICKING_GATHER_STRIDE_WORDS);
+
+        for (let i = 0; i < queries.length; i++) {
+            const query = queries[i];
+            const base = i * PICKING_GATHER_STRIDE_WORDS;
+
+            if (on_view(query)) {
+                pixels[base] = texel(query.u, width);
+                pixels[base + 1] = texel(query.v, height);
+            } else {
+                pixels[base] = PICKING_QUERY_OFF_VIEW;
+            }
+        }
+
         const textures = frame.get(ViewTextures);
         const graph = frame.graph;
 
-        // A transient pool buffer carries what its last tenant left: a query off the view has to
-        // read as nothing rather than as whatever that was, so the buffer is cleared before the
-        // copies land in it.
-        const cleared = {};
-        const clear = graph.add("Picking / clear texels", cleared, (d, resources, context) => {
-            context.encoder.clearBuffer(resources.get(d.target));
-        });
-
-        cleared.target = clear.create("picking/texels", BufferResourceDescriptor.from(
-            queries.length * QUERY_STRIDE,
-            GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC
-        ));
-
         const data = {};
-        const pass = graph.add("Picking / copy texels", data, (data, resources, context) => {
-            const mesh = resources.get(data.mesh).gpu_texture;
-            const depth = resources.get(data.depth).gpu_texture;
-            const target = resources.get(data.target);
+        const pass = graph.add("Picking / gather texels", data, (data, resources, context) => {
             const encoder = context.encoder;
 
-            for (let i = 0; i < queries.length; i++) {
-                const query = queries[i];
-
-                if (!on_view(query)) {
-                    // off the view: nothing is copied, and the texel reads as nothing
-                    continue;
-                }
-
-                const origin = { x: texel(query.u, width), y: texel(query.v, height) };
-                const offset = i * QUERY_STRIDE;
-
-                encoder.copyTextureToBuffer(
-                    { texture: mesh, origin },
-                    { buffer: target, offset, bytesPerRow: TEXEL_STRIDE },
-                    [1, 1, 1]
-                );
-
-                encoder.copyTextureToBuffer(
-                    { texture: depth, origin, aspect: "depth-only" },
-                    { buffer: target, offset: offset + TEXEL_STRIDE, bytesPerRow: TEXEL_STRIDE },
-                    [1, 1, 1]
-                );
-            }
+            shader_picking_gather.dispatchThreads({
+                encoder,
+                bindings: {
+                    query_count: queries.length,
+                    viz_mesh: resources.get(data.mesh),
+                    viz_depth: resources.get(data.depth),
+                    queries: encoder.allocateTransientBufferAndLoad(
+                        pixels.buffer, GPUBufferUsage.STORAGE
+                    ),
+                    results: resources.get(data.results),
+                },
+                thread_count_x: queries.length,
+            });
         });
 
         data.mesh = pass.read(textures.visibility_mesh);
         data.depth = pass.read(textures.depth);
-        data.target = pass.write(cleared.target);
+        data.results = pass.create("picking/results", BufferResourceDescriptor.from(
+            queries.length * QUERY_STRIDE,
+            GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC
+        ));
 
         const system = this.#system;
 
-        graph_read_buffer({ graph, buffer: data.target })
+        graph_read_buffer({ graph, buffer: data.results })
             .then(ref => {
                 try {
                     const words = new Uint32Array(ref.getValue());
@@ -323,10 +318,12 @@ export class PickingExtension extends RenderExtension {
                             results.push(result);
 
                             if (!on_view(query)) {
+                                // the gather writes an invalid row here too; this is the same
+                                // answer without depending on a dispatch having run
                                 continue;
                             }
 
-                            const base = index * QUERY_STRIDE / 4;
+                            const base = index * PICKING_GATHER_STRIDE_WORDS;
                             const entity = system.resolve_row(words[base]);
 
                             if (entity === PickingResult.NOTHING) {
@@ -338,7 +335,7 @@ export class PickingExtension extends RenderExtension {
                             unproject(
                                 result.position, view_projection,
                                 texel(query.u, width), texel(query.v, height), width, height,
-                                floats[base + TEXEL_STRIDE / 4]
+                                floats[base + 1]
                             );
 
                             result.distance = Math.hypot(

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,
+});