@woosh/meep-engine 3.10.0 → 3.11.0

package/src/shade/device/timing/GPUTimerArray.d.ts

@@ -5,18 +5,36 @@ export class GPUTimerArray {
      * @param {number} [size] number of query slots
      */
     constructor(device: GPUDevice, size?: number);
+    /**
+     * How many passes went untimed because {@link size} was too small for the frame.
+     *
+     * @returns {number}
+     */
+    get dropped_count(): number;
     /**
      *
      * @param {string} label
-     * @returns {GPUComputePassTimestampWrites}
+     * @returns {GPUComputePassTimestampWrites|undefined} undefined when the array is full
      */
-    getComputeWrites(label: string): GPUComputePassTimestampWrites;
+    getComputeWrites(label: string): GPUComputePassTimestampWrites | undefined;
     /**
      *
      * @param {string} label
-     * @returns {GPURenderPassTimestampWrites}
+     * @returns {GPURenderPassTimestampWrites|undefined} undefined when the array is full
+     */
+    getRenderWrites(label: string): GPURenderPassTimestampWrites | undefined;
+    /**
+     * Visit every slot that was claimed this frame, in slot order, with its raw timestamps.
+     *
+     * Raw: nanoseconds as the device reported them, `BigInt`, unscaled. {@link
+     * results_to_console_table} is the same data rounded for a human to read at a glance; a
+     * recording needs the values themselves, and the difference matters once quantization is in
+     * play — see the profiler's treatment of `timestamp_period_ns`.
+     *
+     * @param {(slot_id: number, label: string, type: string, t_begin: bigint, t_end: bigint) => void} visitor
+     * @returns {void}
      */
-    getRenderWrites(label: string): GPURenderPassTimestampWrites;
+    traverse_results(visitor: (slot_id: number, label: string, type: string, t_begin: bigint, t_end: bigint) => void): void;
     destroy(): void;
     /**
      *

package/src/shade/device/timing/GPUTimerArray.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUTimerArray.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/timing/GPUTimerArray.js"],"names":[],"mappings":"AAGA;IA8FI;;;;OAIG;IACH,sCAFW,MAAM,EAoChB;IA/ED;;;;OAIG;IACH,wBAHW,MAAM,iCAgBhB;IAED;;;;OAIG;IACH,uBAHW,MAAM,gCAgBhB;IA2CD,gBAQC;IAED;;;OAGG;IACH,0CAQC;IAED,kCAwBC;IAED;;;OAGG;IACH,gCAqBC;;CAEJ"}
+{"version":3,"file":"GPUTimerArray.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/timing/GPUTimerArray.js"],"names":[],"mappings":"AAGA;IAwKI;;;;OAIG;IACH,sCAFW,MAAM,EAoChB;IAjKD;;;;OAIG;IACH,4BAEC;IAgED;;;;OAIG;IACH,wBAHW,MAAM,GACJ,gCAA8B,SAAS,CAInD;IAED;;;;OAIG;IACH,uBAHW,MAAM,GACJ,+BAA6B,SAAS,CAIlD;IAED;;;;;;;;;;OAUG;IACH,oCAHqB,MAAM,SAAS,MAAM,QAAQ,MAAM,WAAW,MAAM,SAAS,MAAM,KAAK,IAAI,GACpF,IAAI,CAsBhB;IA2CD,gBAQC;IAED;;;OAGG;IACH,0CAQC;IAED,kCAwBC;IAED;;;OAGG;IACH,gCAqBC;;CAEJ"}

package/src/shade/device/timing/GPUTimerArray.js

@@ -38,13 +38,44 @@ export class GPUTimerArray {
     #slot_metadata = [];
 
     /**
+     * Passes that asked for a slot after the array ran out.
+     *
+     * Reported rather than swallowed. A profile capture instruments far more passes than a one-off
+     * debug frame does, and a silent shortfall reads downstream as "those passes were free".
+     *
+     * @type {number}
+     */
+    #dropped_count = 0;
+
+    /**
+     * How many passes went untimed because {@link size} was too small for the frame.
+     *
+     * @returns {number}
+     */
+    get dropped_count() {
+        return this.#dropped_count;
+    }
+
+    /**
+     * Claim a slot, or report that there is none.
+     *
+     * The bound check is the point. `IdPool` hands out ids indefinitely, and an id at or past
+     * {@link size} addresses a query index the query set does not have — which WebGPU rejects at
+     * the `beginRenderPass` that used it, blaming a pass that did nothing wrong and saying nothing
+     * about the one that exhausted the array.
      *
      * @param {string} label
      * @param {string} type
-     * @return {number}
+     * @return {number} slot id, or -1 when the array is full
      */
     #bind_slot(label, type) {
 
+        if (this.#slots.peek() >= this.#size) {
+            this.#dropped_count++;
+
+            return -1;
+        }
+
         const id = this.#slots.get();
 
         this.#slot_metadata[id] = {
@@ -56,15 +87,27 @@ export class GPUTimerArray {
     }
 
     /**
-     *
      * @param {string} label
-     * @returns {GPUComputePassTimestampWrites}
+     * @param {string} type one of 'compute', 'render'
+     * @returns {GPUComputePassTimestampWrites|GPURenderPassTimestampWrites|undefined} undefined when
+     * there is no slot left, in which case the caller must leave `timestampWrites` off its
+     * descriptor — an untimed pass is the correct degradation, an invalid one is not
      */
-    getComputeWrites(label) {
+    #get_writes(label, type) {
 
         const querySet = this.#query_set;
 
-        const id = this.#bind_slot(label, 'compute');
+        if (querySet === undefined) {
+            // same guard as `resolve` and `download_results`: with the feature withheld the timers
+            // go quiet rather than taking the frame down
+            return undefined;
+        }
+
+        const id = this.#bind_slot(label, type);
+
+        if (id === -1) {
+            return undefined;
+        }
 
         const index0 = id * 2;
 
@@ -78,21 +121,52 @@ export class GPUTimerArray {
     /**
      *
      * @param {string} label
-     * @returns {GPURenderPassTimestampWrites}
+     * @returns {GPUComputePassTimestampWrites|undefined} undefined when the array is full
+     */
+    getComputeWrites(label) {
+        return this.#get_writes(label, 'compute');
+    }
+
+    /**
+     *
+     * @param {string} label
+     * @returns {GPURenderPassTimestampWrites|undefined} undefined when the array is full
      */
     getRenderWrites(label) {
+        return this.#get_writes(label, 'render');
+    }
 
-        const querySet = this.#query_set;
+    /**
+     * Visit every slot that was claimed this frame, in slot order, with its raw timestamps.
+     *
+     * Raw: nanoseconds as the device reported them, `BigInt`, unscaled. {@link
+     * results_to_console_table} is the same data rounded for a human to read at a glance; a
+     * recording needs the values themselves, and the difference matters once quantization is in
+     * play — see the profiler's treatment of `timestamp_period_ns`.
+     *
+     * @param {(slot_id: number, label: string, type: string, t_begin: bigint, t_end: bigint) => void} visitor
+     * @returns {void}
+     */
+    traverse_results(visitor) {
+        assert.isFunction(visitor, 'visitor');
 
-        const id = this.#bind_slot(label, 'render');
+        const results = this.#results;
 
-        const index0 = id * 2;
+        if (results === undefined) {
+            return;
+        }
 
-        return {
-            querySet,
-            beginningOfPassWriteIndex: index0,
-            endOfPassWriteIndex: index0 + 1,
-        };
+        this.#slots.traverseUsed(slot_id => {
+            const meta = this.#slot_metadata[slot_id];
+
+            visitor(
+                slot_id,
+                meta.label,
+                meta.type,
+                results[slot_id * 2],
+                results[slot_id * 2 + 1]
+            );
+        });
     }
 
     /**