@woosh/meep-engine 3.33.0 → 3.34.0

package/src/engine/sound/ecs/audio/SpatialAudioIndex.js

@@ -1,174 +1,161 @@
-import { BVH } from "../../../../core/bvh2/bvh3/BVH.js";
-import { BvhClient } from "../../../../core/bvh2/bvh3/BvhClient.js";
-import { BVHQueryIntersectsSphere } from "../../../../core/bvh2/bvh3/query/BVHQueryIntersectsSphere.js";
-import { bvh_query_user_data_generic } from "../../../../core/bvh2/bvh3/query/bvh_query_user_data_generic.js";
-
-/**
- * Spatial broadphase for 3D audio emitters (P5.1, cull-only).
- *
- * Holds a dynamic BVH whose leaves are each emitter's AUDIBLE region — an axis-aligned box of
- * half-extent `event.distanceMax` centred on the emitter. So "which emitters can possibly be heard
- * from point P" is one O(log n + k) BVH point-query instead of an O(n) scan over every emitter. This
- * is the registered/dormant tier: a registered emitter is a record plus one BVH leaf — no
- * `EventInstance`, no WebAudio nodes, no per-frame work. Promoting in-range emitters to live instances
- * (voice slots, stealing, fades) is layered on top later; this class only answers the cull.
- *
- * Leaf bounds track the emitter REACTIVELY: each leaf subscribes to its position's `onChanged`, so a
- * still emitter costs nothing per frame and a moving one refits only when it actually moves. (meep is
- * fully dynamic — there is no static/dynamic distinction and no per-tick refit loop.)
- *
- * The cull is conservative: the leaf is a cube of half-extent `distanceMax`, so its corners admit a
- * few emitters whose true (spherical) distance slightly exceeds `distanceMax`. That is correct
- * broadphase behaviour — the exact distance test belongs to the narrowphase (the live instance).
- */
-export class SpatialAudioIndex {
-
-    /**
-     * @type {BVH}
-     */
-    #bvh = new BVH();
-
-    /**
-     * entity id -> { entity, event, position, bvhClient, onMove }
-     * @type {Map<number, {entity:number, event:EventDescription, position:Vector3, bvhClient:BvhClient, onMove:function}>}
-     */
-    #records = new Map();
-
-    /**
-     * Reused point-query. The sphere `[x, y, z, radius]` is mutated in place each query; radius stays 0,
-     * so the test is "listener point inside the leaf AABB".
-     * @type {number[]}
-     */
-    #querySphere = [0, 0, 0, 0];
-
-    /**
-     * @type {BVHQueryIntersectsSphere}
-     */
-    #query = BVHQueryIntersectsSphere.from(this.#querySphere);
-
-    /**
-     * @returns {number} number of registered emitters
-     */
-    get size() {
-        return this.#records.size;
-    }
-
-    /**
-     * @param {number} entity
-     * @returns {boolean}
-     */
-    has(entity) {
-        return this.#records.has(entity);
-    }
-
-    /**
-     * Register an emitter: insert a BVH leaf sized to its audible region and start tracking its
-     * position. The entity id is the leaf's user data (so queries return entity ids).
-     *
-     * @param {number} entity non-negative integer id
-     * @param {EventDescription} event read for `distanceMax` (and retained for later promotion)
-     * @param {Float64Array} position shared translation view over the entity's transform. It has no
-     *        signals, so the owner calls {@link refresh} when the entity moves.
-     */
-    add(entity, event, position) {
-        if (this.#records.has(entity)) {
-            throw new Error(`SpatialAudioIndex: entity ${entity} already registered`);
-        }
-
-        const bvhClient = new BvhClient();
-
-        const record = { entity, event, position, bvhClient, onMove: null };
-
-        this.#writeBounds(record);          // size the leaf AABB before linking (resize no-ops the write pre-link)
-        bvhClient.link(this.#bvh, entity);  // user_data = entity id
-
-        this.#records.set(entity, record);
-    }
-
-    /**
-     * Unregister an emitter: stop tracking its position and drop its BVH leaf. No-op for an unknown
-     * entity.
-     * @param {number} entity
-     */
-    remove(entity) {
-        const record = this.#records.get(entity);
-
-        if (record === undefined) {
-            return;
-        }
-
-        record.bvhClient.unlink();
-
-        this.#records.delete(entity);
-    }
-
-    /**
-     * Refit a record's leaf to `position ± distanceMax`. Called once at registration and again
-     * (reactively) whenever the position changes.
-     * @param {{event:EventDescription, position:Vector3, bvhClient:BvhClient}} record
-     */
-    #writeBounds(record) {
-        const p = record.position;
-        const d = record.event.distanceMax;
-
-        record.bvhClient.resize(
-            p[0] - d, p[1] - d, p[2] - d,
-            p[0] + d, p[1] + d, p[2] + d
-        );
-    }
-
-    /**
-     * Write the entity ids whose audible region contains `listenerPosition` into `out` (starting at
-     * `out_offset`) and return how many — every emitter that can possibly be heard from there (a
-     * conservative superset; see the class note), in unspecified order. Allocation-free: `out` is a
-     * caller-owned reusable buffer, grown as needed (never shrunk), so only `out[out_offset .. out_offset
-     * + count)` is meaningful — entries elsewhere may be stale from a prior query and must be ignored.
-     *
-     * @param {number[]} out caller-owned result buffer, reused across calls (grows, never shrinks)
-     * @param {number} out_offset index in `out` to start writing at
-     * @param {Vector3} listenerPosition
-     * @returns {number} number of matches written to `out`
-     */
-    queryAudible(out, out_offset, listenerPosition) {
-        this.#querySphere[0] = listenerPosition[0];
-        this.#querySphere[1] = listenerPosition[1];
-        this.#querySphere[2] = listenerPosition[2];
-        // radius stays 0 -> point-in-AABB
-
-        return bvh_query_user_data_generic(out, out_offset, this.#bvh, this.#bvh.root, this.#query);
-    }
-    /**
-     * Re-fit the entity's leaf to its current pose.
-     *
-     * The translation this index holds is a live view over the transform's buffer, so it is already
-     * up to date - what it cannot do is announce itself. The owner calls this when the dataset says
-     * the transform changed.
-     *
-     * @param {number} entity
-     */
-    /**
-     * Re-fit every leaf.
-     *
-     * The translations are live views over their transforms, so the data is already current - what
-     * is stale is the leaf AABB in the BVH. One pass per tick costs what the per-move refits cost
-     * before, and it is what the emitters' own "next tick re-attenuates" behaviour expects.
-     *
-     * @returns {void}
-     */
-    refresh_all() {
-        for (const record of this.#records.values()) {
-            this.#writeBounds(record);
-        }
-    }
-
-    refresh(entity) {
-        const record = this.#records.get(entity);
-
-        if (record === undefined) {
-            return;
-        }
-
-        this.#writeBounds(record);
-    }
-
-}
+import { BVH } from "../../../../core/bvh2/bvh3/BVH.js";
+import { BvhClient } from "../../../../core/bvh2/bvh3/BvhClient.js";
+import { BVHQueryIntersectsSphere } from "../../../../core/bvh2/bvh3/query/BVHQueryIntersectsSphere.js";
+import { bvh_query_user_data_generic } from "../../../../core/bvh2/bvh3/query/bvh_query_user_data_generic.js";
+
+/**
+ * Spatial broadphase for 3D audio emitters (P5.1, cull-only).
+ *
+ * Holds a dynamic BVH whose leaves are each emitter's AUDIBLE region — an axis-aligned box of
+ * half-extent `event.distanceMax` centred on the emitter. So "which emitters can possibly be heard
+ * from point P" is one O(log n + k) BVH point-query instead of an O(n) scan over every emitter. This
+ * is the registered/dormant tier: a registered emitter is a record plus one BVH leaf — no
+ * `EventInstance`, no WebAudio nodes, no per-frame work. Promoting in-range emitters to live instances
+ * (voice slots, stealing, fades) is layered on top later; this class only answers the cull.
+ *
+ * Leaf bounds track the emitter on demand: a position is a live view with no signal of its own, so the
+ * owner calls {@link refresh} for an entity when the dataset announces its transform changed. A still
+ * emitter costs nothing per frame and a moving one refits only when it actually moves. (meep is fully
+ * dynamic — there is no static/dynamic distinction and no per-tick refit loop.)
+ *
+ * The cull is conservative: the leaf is a cube of half-extent `distanceMax`, so its corners admit a
+ * few emitters whose true (spherical) distance slightly exceeds `distanceMax`. That is correct
+ * broadphase behaviour — the exact distance test belongs to the narrowphase (the live instance).
+ */
+export class SpatialAudioIndex {
+
+    /**
+     * @type {BVH}
+     */
+    #bvh = new BVH();
+
+    /**
+     * entity id -> { entity, event, position, bvhClient }
+     * @type {Map<number, {entity:number, event:EventDescription, position:Float64Array, bvhClient:BvhClient}>}
+     */
+    #records = new Map();
+
+    /**
+     * Reused point-query. The sphere `[x, y, z, radius]` is mutated in place each query; radius stays 0,
+     * so the test is "listener point inside the leaf AABB".
+     * @type {number[]}
+     */
+    #querySphere = [0, 0, 0, 0];
+
+    /**
+     * @type {BVHQueryIntersectsSphere}
+     */
+    #query = BVHQueryIntersectsSphere.from(this.#querySphere);
+
+    /**
+     * @returns {number} number of registered emitters
+     */
+    get size() {
+        return this.#records.size;
+    }
+
+    /**
+     * @param {number} entity
+     * @returns {boolean}
+     */
+    has(entity) {
+        return this.#records.has(entity);
+    }
+
+    /**
+     * Register an emitter: insert a BVH leaf sized to its audible region and start tracking its
+     * position. The entity id is the leaf's user data (so queries return entity ids).
+     *
+     * @param {number} entity non-negative integer id
+     * @param {EventDescription} event read for `distanceMax` (and retained for later promotion)
+     * @param {Float64Array} position shared translation view over the entity's transform. It has no
+     *        signals, so the owner calls {@link refresh} when the entity moves.
+     */
+    add(entity, event, position) {
+        if (this.#records.has(entity)) {
+            throw new Error(`SpatialAudioIndex: entity ${entity} already registered`);
+        }
+
+        const bvhClient = new BvhClient();
+
+        const record = { entity, event, position, bvhClient };
+
+        this.#writeBounds(record);          // size the leaf AABB before linking (resize no-ops the write pre-link)
+        bvhClient.link(this.#bvh, entity);  // user_data = entity id
+
+        this.#records.set(entity, record);
+    }
+
+    /**
+     * Unregister an emitter: stop tracking its position and drop its BVH leaf. No-op for an unknown
+     * entity.
+     * @param {number} entity
+     */
+    remove(entity) {
+        const record = this.#records.get(entity);
+
+        if (record === undefined) {
+            return;
+        }
+
+        record.bvhClient.unlink();
+
+        this.#records.delete(entity);
+    }
+
+    /**
+     * Refit a record's leaf to `position ± distanceMax`. Called once at registration and again from
+     * {@link refresh} whenever the owner reports a move.
+     * @param {{event:EventDescription, position:Float64Array, bvhClient:BvhClient}} record
+     */
+    #writeBounds(record) {
+        const p = record.position;
+        const d = record.event.distanceMax;
+
+        record.bvhClient.resize(
+            p[0] - d, p[1] - d, p[2] - d,
+            p[0] + d, p[1] + d, p[2] + d
+        );
+    }
+
+    /**
+     * Write the entity ids whose audible region contains `listenerPosition` into `out` (starting at
+     * `out_offset`) and return how many — every emitter that can possibly be heard from there (a
+     * conservative superset; see the class note), in unspecified order. Allocation-free: `out` is a
+     * caller-owned reusable buffer, grown as needed (never shrunk), so only `out[out_offset .. out_offset
+     * + count)` is meaningful — entries elsewhere may be stale from a prior query and must be ignored.
+     *
+     * @param {number[]} out caller-owned result buffer, reused across calls (grows, never shrinks)
+     * @param {number} out_offset index in `out` to start writing at
+     * @param {Vector3} listenerPosition
+     * @returns {number} number of matches written to `out`
+     */
+    queryAudible(out, out_offset, listenerPosition) {
+        this.#querySphere[0] = listenerPosition[0];
+        this.#querySphere[1] = listenerPosition[1];
+        this.#querySphere[2] = listenerPosition[2];
+        // radius stays 0 -> point-in-AABB
+
+        return bvh_query_user_data_generic(out, out_offset, this.#bvh, this.#bvh.root, this.#query);
+    }
+
+    /**
+     * Re-fit the entity's leaf to its current pose. No-op for an unknown entity.
+     *
+     * The translation this index holds is a live view over the transform's buffer, so it is already
+     * up to date - what it cannot do is announce itself. The owner calls this when the dataset says
+     * the transform changed.
+     *
+     * @param {number} entity
+     */
+    refresh(entity) {
+        const record = this.#records.get(entity);
+
+        if (record === undefined) {
+            return;
+        }
+
+        this.#writeBounds(record);
+    }
+
+}

package/src/shade/device/mock/SoftwareGPUBuffer.d.ts

@@ -80,7 +80,8 @@ export class SoftwareGPUBuffer extends SoftwareGPUObjectBase implements GPUBuffe
      * @param {number} [offset]
      * @param {number} [size] defaults to the rest of the buffer
      * @returns {Promise<undefined>} rejects with an `OperationError` for a range this device will
-     * not map, and raises the matching validation error on the device
+     * not map, and raises the matching validation error on the device; rejects with an `AbortError`,
+     * and raises nothing, when the buffer is unmapped or destroyed before the mapping resolves
      */
     mapAsync(mode: GPUMapModeFlags, offset?: number, size?: number): Promise<undefined>;
     /**
@@ -103,7 +104,7 @@ export class SoftwareGPUBuffer extends SoftwareGPUObjectBase implements GPUBuffe
     /**
      * End the mapping: every range handed out is written back into the buffer and then detached, so
      * a caller holding one sees the zero-length buffer a browser gives it rather than a stale view
-     * that still appears to work.
+     * that still appears to work. A mapping still in flight is abandoned — see {@link mapAsync}.
      */
     unmap(): void;
     /**
@@ -112,7 +113,8 @@ export class SoftwareGPUBuffer extends SoftwareGPUObjectBase implements GPUBuffe
      * careful.
      *
      * An outstanding mapping goes with it: WebGPU detaches every mapped range when the buffer is
-     * destroyed, so a range that kept working would hide a use-after-destroy.
+     * destroyed, so a range that kept working would hide a use-after-destroy. So does one still in
+     * flight, which is rejected with an `AbortError` — see {@link mapAsync}.
      */
     destroy(): void;
     /**

package/src/shade/device/mock/SoftwareGPUBuffer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SoftwareGPUBuffer.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/SoftwareGPUBuffer.js"],"names":[],"mappings":"AAkBA;;;;;;;GAOG;AAEH;;;GAGG;AACH,wEAFgB,SAAS;IAiJrB;;;;;;;OAOG;IACH,4EAFa,iBAAiB,CAI7B;IA5CD;;;;;OAKG;IACH,gFAFW,OAAO,EA4BjB;IAlID;;;OAGG;IACH,mBAEC;IAID;;;OAGG;IACH,8BAEC;IAQD;;;OAGG;IACH,kCAEC;IA4BD;;;;;;;;OAQG;IACH,wBAEC;IAID;;;;;;;;;;OAUG;IACH,uBAEC;IAID;;;OAGG;IACH,2BAEC;IA0HD;;;;;;;;;;;;OAYG;IACH,yCALW,MAAM,SACN,MAAM,GACJ,QAAQ,SAAS,CAAC,CAoB9B;IAsCD;;;;;;;;;;;;;;;OAeG;IACH,wBAPW,MAAM,SACN,MAAM,GAIJ,WAAW,CAgBvB;IAED;;;;OAIG;IACH,cAYC;IAED;;;;;;;OAOG;IACH,gBAiBC;IAGL;;;OAGG;IACH,8BAFU,OAAO,CAE8B;;CAN9C;;;;;;;;YA/Xa,MAAM;;;;UACN,MAAM;;;;UACN,WAAW;;sCAtBa,4BAA4B"}
+{"version":3,"file":"SoftwareGPUBuffer.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/SoftwareGPUBuffer.js"],"names":[],"mappings":"AAkBA;;;;;;;GAOG;AAEH;;;GAGG;AACH,wEAFgB,SAAS;IA2JrB;;;;;;;OAOG;IACH,4EAFa,iBAAiB,CAI7B;IA5CD;;;;;OAKG;IACH,gFAFW,OAAO,EA4BjB;IA5ID;;;OAGG;IACH,mBAEC;IAID;;;OAGG;IACH,8BAEC;IAQD;;;OAGG;IACH,kCAEC;IAsCD;;;;;;;;OAQG;IACH,wBAEC;IAID;;;;;;;;;;OAUG;IACH,uBAEC;IAID;;;OAGG;IACH,2BAEC;IA0HD;;;;;;;;;;;;;OAaG;IACH,yCANW,MAAM,SACN,MAAM,GACJ,QAAQ,SAAS,CAAC,CAkC9B;IAsCD;;;;;;;;;;;;;;;OAeG;IACH,wBAPW,MAAM,SACN,MAAM,GAIJ,WAAW,CAgBvB;IAED;;;;OAIG;IACH,cAcC;IAED;;;;;;;;OAQG;IACH,gBAmBC;IAGL;;;OAGG;IACH,8BAFU,OAAO,CAE8B;;CAN9C;;;;;;;;YA5Za,MAAM;;;;UACN,MAAM;;;;UACN,WAAW;;sCAtBa,4BAA4B"}

package/src/shade/device/mock/SoftwareGPUBuffer.js

@@ -72,6 +72,16 @@ export class SoftwareGPUBuffer extends SoftwareGPUObjectBase {
         return this.#mapState;
     }
 
+    /**
+     * The mapping in flight, while {@link mapState} is `"pending"`: a token only that call holds.
+     * {@link unmap} and {@link destroy} drop it, which is how the call learns on resolving that the
+     * mapping it was making has been abandoned — WebGPU rejects it with an `AbortError` rather than
+     * mapping a buffer somebody has since unmapped or released.
+     *
+     * @type {Object|null}
+     */
+    #pending_map = null;
+
     /**
      * The mapped region, meaningful only while {@link mapState} is `"mapped"`.
      *
@@ -269,7 +279,8 @@ export class SoftwareGPUBuffer extends SoftwareGPUObjectBase {
      * @param {number} [offset]
      * @param {number} [size] defaults to the rest of the buffer
      * @returns {Promise<undefined>} rejects with an `OperationError` for a range this device will
-     * not map, and raises the matching validation error on the device
+     * not map, and raises the matching validation error on the device; rejects with an `AbortError`,
+     * and raises nothing, when the buffer is unmapped or destroyed before the mapping resolves
      */
     async mapAsync(mode, offset = 0, size = this.#size - offset) {
         const refusal = this.#map_refusal(mode, offset, size);
@@ -278,12 +289,25 @@ export class SoftwareGPUBuffer extends SoftwareGPUObjectBase {
             throw this.#refuse_mapping(refusal);
         }
 
+        const pending = {};
+
+        this.#pending_map = pending;
         this.#mapState = "pending";
 
         // a real mapping completes on another turn, and host code is written around that — resolving
         // synchronously would let code that forgot to await appear to work
         await Promise.resolve();
 
+        if (this.#pending_map !== pending) {
+            // unmap() or destroy() got there first. Not a validation error: abandoning a mapping is
+            // legal, and the rejection is the whole of what the caller hears about it
+            throw new DOMException(
+                `mapAsync: buffer '${this.label}' was ${this.#destroyed ? 'destroyed' : 'unmapped'} before mapping was resolved`,
+                'AbortError'
+            );
+        }
+
+        this.#pending_map = null;
         this.#mapState = "mapped";
         this.#map_offset = offset;
         this.#map_size = size;
@@ -361,9 +385,11 @@ export class SoftwareGPUBuffer extends SoftwareGPUObjectBase {
     /**
      * End the mapping: every range handed out is written back into the buffer and then detached, so
      * a caller holding one sees the zero-length buffer a browser gives it rather than a stale view
-     * that still appears to work.
+     * that still appears to work. A mapping still in flight is abandoned — see {@link mapAsync}.
      */
     unmap() {
+        this.#pending_map = null;
+
         for (const range of this.#mapped_ranges) {
             array_buffer_copy(range.data, 0, this.#data, range.offset, range.size);
 
@@ -383,13 +409,16 @@ export class SoftwareGPUBuffer extends SoftwareGPUObjectBase {
      * careful.
      *
      * An outstanding mapping goes with it: WebGPU detaches every mapped range when the buffer is
-     * destroyed, so a range that kept working would hide a use-after-destroy.
+     * destroyed, so a range that kept working would hide a use-after-destroy. So does one still in
+     * flight, which is rejected with an `AbortError` — see {@link mapAsync}.
      */
     destroy() {
         if (this.#destroyed) {
             return;
         }
 
+        this.#pending_map = null;
+
         for (const range of this.#mapped_ranges) {
             range.data.transfer();
         }