@woosh/meep-engine 3.11.3 → 3.13.0

package/src/shade/device/pass/ShadeGPUComputePassEncoder.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Decorates {@link GPUComputePassEncoder}.
+ *
+ * **Every compute pass Shade opens is one of these.** There is no unwrapped path and no conditional
+ * wrapping, and that is what makes hand-written forwarding safe: a method missing here is
+ * `pass.setPipeline is not a function` on the first frame of every build, rather than a call
+ * silently dropped in the one configuration nobody runs. The `Proxy` this replaces forwarded
+ * everything by reflection precisely because it was conditional, and a conditional wrapper's
+ * defects only appear while profiling.
+ *
+ * The method names follow WebGPU's to remove friction for anyone who already knows the API. They
+ * are **not** a promise of substitutability — see {@link setBindGroupRange}, which is Shade's own
+ * name for a form WebGPU resolves by counting arguments.
+ *
+ * When a capture is running the pass is handed a {@link GPUProfileWork} to tally into. This class
+ * imports nothing from the profiler and does not know what a capture is; `work` is a record of
+ * counters, and `null` is the ordinary case.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ShadeGPUComputePassEncoder {
+    /**
+     * @param {GPUComputePassEncoder} pass
+     * @param {GPUProfileWork|null} work
+     */
+    constructor(pass: GPUComputePassEncoder, work: GPUProfileWork | null);
+    /**
+     * @param {string} value
+     */
+    set label(arg: string);
+    /**
+     * @returns {string}
+     */
+    get label(): string;
+    /**
+     * @param {GPUComputePipeline} pipeline
+     */
+    setPipeline(pipeline: GPUComputePipeline): void;
+    /**
+     * @param {number} x
+     * @param {number} [y=1]
+     * @param {number} [z=1]
+     */
+    dispatchWorkgroups(x: number, y?: number, z?: number): void;
+    /**
+     * @param {GPUBuffer} indirect_buffer
+     * @param {number} indirect_offset
+     */
+    dispatchWorkgroupsIndirect(indirect_buffer: GPUBuffer, indirect_offset: number): void;
+    end(): void;
+    /**
+     * @param {number} index
+     * @param {GPUBindGroup} bind_group
+     * @param {number[]} [dynamic_offsets]
+     */
+    setBindGroup(index: number, bind_group: GPUBindGroup, dynamic_offsets?: number[]): void;
+    /**
+     * The `Uint32Array`-slice form of {@link setBindGroup}.
+     *
+     * Named apart rather than overloaded on arity. Both forms then pass every argument they
+     * declare, so neither can select the other's overload by accident, and the name says at the
+     * call site which one is meant.
+     *
+     * @param {number} index
+     * @param {GPUBindGroup} bind_group
+     * @param {Uint32Array} dynamic_offsets_data
+     * @param {number} data_start
+     * @param {number} data_length
+     */
+    setBindGroupRange(index: number, bind_group: GPUBindGroup, dynamic_offsets_data: Uint32Array, data_start: number, data_length: number): void;
+    /**
+     * Rest arguments, so the arity that arrives is the arity that leaves — `data_size` has no
+     * default to stand in for, and a trailing `undefined` is not the same as an absent argument.
+     * @see setBindGroup
+     *
+     * @param {number} range_offset
+     * @param {ArrayBufferView|ArrayBuffer} data
+     * @param {number} [data_offset]
+     * @param {number} [data_size]
+     */
+    setImmediates(...args: any[]): void;
+    /**
+     * @param {string} label
+     */
+    pushDebugGroup(label: string): void;
+    popDebugGroup(): void;
+    /**
+     * @param {string} label
+     */
+    insertDebugMarker(label: string): void;
+    /**
+     * Record which pipeline descriptor this pass ran.
+     *
+     * Separate from {@link setPipeline} because that receives the compiled
+     * {@link GPUComputePipeline}, and neither the label the descriptor was given nor its workgroup
+     * size is on it. Only `constructComputePass` holds the descriptor, so a pass begun the long way
+     * records its counts but not what ran them — which the model represents as an unknown rather
+     * than a zero.
+     *
+     * @param {ComputePipelineDescriptor} descriptor
+     * @returns {void}
+     */
+    record_pipeline(descriptor: ComputePipelineDescriptor): void;
+    #private;
+}
+//# sourceMappingURL=ShadeGPUComputePassEncoder.d.ts.map

package/src/shade/device/pass/ShadeGPUComputePassEncoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShadeGPUComputePassEncoder.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/pass/ShadeGPUComputePassEncoder.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAmBI;;;OAGG;IACH,+CAFW,iBAAe,IAAI,EAO7B;IASD;;OAEG;IACH,uBAEC;IAZD;;OAEG;IACH,oBAEC;IAWD;;OAEG;IACH,gDAEC;IAED;;;;OAIG;IACH,sBAJW,MAAM,MACN,MAAM,MACN,MAAM,QAahB;IAED;;;OAGG;IACH,wEAFW,MAAM,QAYhB;IAED,YAMC;IAID;;;;OAIG;IACH,oBAJW,MAAM,8CAEN,MAAM,EAAE,QAqBlB;IAED;;;;;;;;;;;;OAYG;IACH,yBANW,MAAM,kDAEN,WAAW,cACX,MAAM,eACN,MAAM,QAIhB;IAED;;;;;;;;;OASG;IACH,oCAEC;IAID;;OAEG;IACH,sBAFW,MAAM,QAIhB;IAED,sBAEC;IAED;;OAEG;IACH,yBAFW,MAAM,QAIhB;IAID;;;;;;;;;;;OAWG;IACH,wDAFa,IAAI,CAWhB;;CACJ"}

package/src/shade/device/pass/ShadeGPUComputePassEncoder.js

@@ -0,0 +1,222 @@
+import { assert } from "../../../core/assert.js";
+
+/**
+ * Decorates {@link GPUComputePassEncoder}.
+ *
+ * **Every compute pass Shade opens is one of these.** There is no unwrapped path and no conditional
+ * wrapping, and that is what makes hand-written forwarding safe: a method missing here is
+ * `pass.setPipeline is not a function` on the first frame of every build, rather than a call
+ * silently dropped in the one configuration nobody runs. The `Proxy` this replaces forwarded
+ * everything by reflection precisely because it was conditional, and a conditional wrapper's
+ * defects only appear while profiling.
+ *
+ * The method names follow WebGPU's to remove friction for anyone who already knows the API. They
+ * are **not** a promise of substitutability — see {@link setBindGroupRange}, which is Shade's own
+ * name for a form WebGPU resolves by counting arguments.
+ *
+ * When a capture is running the pass is handed a {@link GPUProfileWork} to tally into. This class
+ * imports nothing from the profiler and does not know what a capture is; `work` is a record of
+ * counters, and `null` is the ordinary case.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ShadeGPUComputePassEncoder {
+
+    /**
+     * @type {GPUComputePassEncoder}
+     */
+    #pass;
+
+    /**
+     * Where this pass's encoded work is tallied, or null when nothing is profiling.
+     *
+     * @type {GPUProfileWork|null}
+     */
+    #work;
+
+    /**
+     * @type {boolean}
+     */
+    #ended = false;
+
+    /**
+     * @param {GPUComputePassEncoder} pass
+     * @param {GPUProfileWork|null} work
+     */
+    constructor(pass, work) {
+        assert.defined(pass, 'pass');
+
+        this.#pass = pass;
+        this.#work = work;
+    }
+
+    /**
+     * @returns {string}
+     */
+    get label() {
+        return this.#pass.label;
+    }
+
+    /**
+     * @param {string} value
+     */
+    set label(value) {
+        this.#pass.label = value;
+    }
+
+    // --- GPUComputePassEncoder ----------------------------------------------
+
+    /**
+     * @param {GPUComputePipeline} pipeline
+     */
+    setPipeline(pipeline) {
+        this.#pass.setPipeline(pipeline);
+    }
+
+    /**
+     * @param {number} x
+     * @param {number} [y=1]
+     * @param {number} [z=1]
+     */
+    dispatchWorkgroups(x, y = 1, z = 1) {
+        const work = this.#work;
+
+        if (work !== null) {
+            work.dispatch_count++;
+            work.workgroups[0] += x;
+            work.workgroups[1] += y;
+            work.workgroups[2] += z;
+        }
+
+        this.#pass.dispatchWorkgroups(x, y, z);
+    }
+
+    /**
+     * @param {GPUBuffer} indirect_buffer
+     * @param {number} indirect_offset
+     */
+    dispatchWorkgroupsIndirect(indirect_buffer, indirect_offset) {
+        const work = this.#work;
+
+        if (work !== null) {
+            // Size lives in a GPU buffer, so there is nothing to add to `workgroups`. Counted apart
+            // so the totals are not read as covering this.
+            work.indirect_dispatch_count++;
+        }
+
+        this.#pass.dispatchWorkgroupsIndirect(indirect_buffer, indirect_offset);
+    }
+
+    end() {
+        assert.notOk(this.#ended, 'pass already ended');
+
+        this.#ended = true;
+
+        this.#pass.end();
+    }
+
+    // --- GPUBindingCommandsMixin --------------------------------------------
+
+    /**
+     * @param {number} index
+     * @param {GPUBindGroup} bind_group
+     * @param {number[]} [dynamic_offsets]
+     */
+    setBindGroup(index, bind_group, dynamic_offsets) {
+        /*
+         Omitted, not forwarded as `undefined`.
+
+         `dynamicOffsets` is declared optional with a default of `[]`, which reads as though an
+         explicit `undefined` would take that default. Some Chrome builds accept it; others convert
+         what they were handed and raise "the provided value cannot be converted to a sequence",
+         which takes out every ordinary two-argument call in the renderer. This shipped broken for
+         exactly that reason.
+
+         So the rule this file follows, having learnt it the hard way: forward exactly the arity
+         that arrived, and never reason about what a binding layer will do with a trailing
+         `undefined`. It costs one branch and it is true on every build.
+        */
+        if (dynamic_offsets === undefined) {
+            this.#pass.setBindGroup(index, bind_group);
+        } else {
+            this.#pass.setBindGroup(index, bind_group, dynamic_offsets);
+        }
+    }
+
+    /**
+     * The `Uint32Array`-slice form of {@link setBindGroup}.
+     *
+     * Named apart rather than overloaded on arity. Both forms then pass every argument they
+     * declare, so neither can select the other's overload by accident, and the name says at the
+     * call site which one is meant.
+     *
+     * @param {number} index
+     * @param {GPUBindGroup} bind_group
+     * @param {Uint32Array} dynamic_offsets_data
+     * @param {number} data_start
+     * @param {number} data_length
+     */
+    setBindGroupRange(index, bind_group, dynamic_offsets_data, data_start, data_length) {
+        this.#pass.setBindGroup(index, bind_group, dynamic_offsets_data, data_start, data_length);
+    }
+
+    /**
+     * Rest arguments, so the arity that arrives is the arity that leaves — `data_size` has no
+     * default to stand in for, and a trailing `undefined` is not the same as an absent argument.
+     * @see setBindGroup
+     *
+     * @param {number} range_offset
+     * @param {ArrayBufferView|ArrayBuffer} data
+     * @param {number} [data_offset]
+     * @param {number} [data_size]
+     */
+    setImmediates(...args) {
+        this.#pass.setImmediates(...args);
+    }
+
+    // --- GPUDebugCommandsMixin ----------------------------------------------
+
+    /**
+     * @param {string} label
+     */
+    pushDebugGroup(label) {
+        this.#pass.pushDebugGroup(label);
+    }
+
+    popDebugGroup() {
+        this.#pass.popDebugGroup();
+    }
+
+    /**
+     * @param {string} label
+     */
+    insertDebugMarker(label) {
+        this.#pass.insertDebugMarker(label);
+    }
+
+    // --- Shade --------------------------------------------------------------
+
+    /**
+     * Record which pipeline descriptor this pass ran.
+     *
+     * Separate from {@link setPipeline} because that receives the compiled
+     * {@link GPUComputePipeline}, and neither the label the descriptor was given nor its workgroup
+     * size is on it. Only `constructComputePass` holds the descriptor, so a pass begun the long way
+     * records its counts but not what ran them — which the model represents as an unknown rather
+     * than a zero.
+     *
+     * @param {ComputePipelineDescriptor} descriptor
+     * @returns {void}
+     */
+    record_pipeline(descriptor) {
+        const work = this.#work;
+
+        if (work === null) {
+            return;
+        }
+
+        work.pipeline = descriptor.label ?? "";
+        work.workgroup_size = descriptor.workgroup_size;
+    }
+}

package/src/shade/device/pass/ShadeGPURenderPassEncoder.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Decorates {@link GPURenderPassEncoder}.
+ *
+ * The render half of {@link ShadeGPUComputePassEncoder} — see there for why the forwarding is
+ * hand-written, why every pass is wrapped rather than only the profiled ones, and what `work` is.
+ *
+ * **Known blind spot:** draws inside a {@link GPURenderBundle} handed to {@link executeBundles} are
+ * not counted, because the bundle was encoded somewhere this pass never saw. The `Proxy` this
+ * replaces had the same gap and nothing in Shade uses bundles.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ShadeGPURenderPassEncoder {
+    /**
+     * @param {GPURenderPassEncoder} pass
+     * @param {GPUProfileWork|null} work
+     */
+    constructor(pass: GPURenderPassEncoder, work: GPUProfileWork | null);
+    /**
+     * @param {string} value
+     */
+    set label(arg: string);
+    /**
+     * @returns {string}
+     */
+    get label(): string;
+    /**
+     * @param {number} x
+     * @param {number} y
+     * @param {number} width
+     * @param {number} height
+     * @param {number} min_depth
+     * @param {number} max_depth
+     */
+    setViewport(x: number, y: number, width: number, height: number, min_depth: number, max_depth: number): void;
+    /**
+     * @param {number} x
+     * @param {number} y
+     * @param {number} width
+     * @param {number} height
+     */
+    setScissorRect(x: number, y: number, width: number, height: number): void;
+    /**
+     * @param {GPUColor} color
+     */
+    setBlendConstant(color: GPUColor): void;
+    /**
+     * @param {number} reference
+     */
+    setStencilReference(reference: number): void;
+    /**
+     * @param {number} query_index
+     */
+    beginOcclusionQuery(query_index: number): void;
+    endOcclusionQuery(): void;
+    /**
+     * @param {Iterable<GPURenderBundle>} bundles
+     */
+    executeBundles(bundles: Iterable<GPURenderBundle>): void;
+    end(): void;
+    /**
+     * @param {GPURenderPipeline} pipeline
+     */
+    setPipeline(pipeline: GPURenderPipeline): void;
+    /**
+     * Rest arguments, so the arity that arrives is the arity that leaves — `size` has no default to
+     * stand in for, it means "the rest of the buffer", and a trailing `undefined` is not the same
+     * as an absent argument.
+     * @see ShadeGPUComputePassEncoder#setBindGroup
+     *
+     * @param {GPUBuffer} buffer
+     * @param {GPUIndexFormat} index_format
+     * @param {number} [offset]
+     * @param {number} [size]
+     */
+    setIndexBuffer(...args: any[]): void;
+    /**
+     * Rest arguments, for the reason given on {@link setIndexBuffer}.
+     *
+     * @param {number} slot
+     * @param {GPUBuffer} buffer
+     * @param {number} [offset]
+     * @param {number} [size]
+     */
+    setVertexBuffer(...args: any[]): void;
+    /**
+     * Named parameters rather than rest arguments, because the counts have to be read — and the
+     * defaults are WebGPU's own, so materialising them here passes four defined values instead of
+     * a trailing `undefined`. @see ShadeGPUComputePassEncoder#setBindGroup
+     *
+     * @param {number} vertex_count
+     * @param {number} [instance_count=1]
+     * @param {number} [first_vertex=0]
+     * @param {number} [first_instance=0]
+     */
+    draw(vertex_count: number, instance_count?: number, first_vertex?: number, first_instance?: number): void;
+    /**
+     * Named parameters with WebGPU's own defaults, for the reason given on {@link draw}.
+     *
+     * @param {number} index_count
+     * @param {number} [instance_count=1]
+     * @param {number} [first_index=0]
+     * @param {number} [base_vertex=0]
+     * @param {number} [first_instance=0]
+     */
+    drawIndexed(index_count: number, instance_count?: number, first_index?: number, base_vertex?: number, first_instance?: number): void;
+    /**
+     * @param {GPUBuffer} indirect_buffer
+     * @param {number} indirect_offset
+     */
+    drawIndirect(indirect_buffer: GPUBuffer, indirect_offset: number): void;
+    /**
+     * @param {GPUBuffer} indirect_buffer
+     * @param {number} indirect_offset
+     */
+    drawIndexedIndirect(indirect_buffer: GPUBuffer, indirect_offset: number): void;
+    /**
+     * @see ShadeGPUComputePassEncoder#setBindGroup for why the third argument is omitted rather
+     * than forwarded as `undefined`
+     *
+     * @param {number} index
+     * @param {GPUBindGroup} bind_group
+     * @param {number[]} [dynamic_offsets]
+     */
+    setBindGroup(index: number, bind_group: GPUBindGroup, dynamic_offsets?: number[]): void;
+    /**
+     * The `Uint32Array`-slice form of {@link setBindGroup}.
+     *
+     * @see ShadeGPUComputePassEncoder#setBindGroupRange for why this is named rather than overloaded
+     *
+     * @param {number} index
+     * @param {GPUBindGroup} bind_group
+     * @param {Uint32Array} dynamic_offsets_data
+     * @param {number} data_start
+     * @param {number} data_length
+     */
+    setBindGroupRange(index: number, bind_group: GPUBindGroup, dynamic_offsets_data: Uint32Array, data_start: number, data_length: number): void;
+    /**
+     * Rest arguments, for the reason given on {@link setIndexBuffer}.
+     *
+     * @param {number} range_offset
+     * @param {ArrayBufferView|ArrayBuffer} data
+     * @param {number} [data_offset]
+     * @param {number} [data_size]
+     */
+    setImmediates(...args: any[]): void;
+    /**
+     * @param {string} label
+     */
+    pushDebugGroup(label: string): void;
+    popDebugGroup(): void;
+    /**
+     * @param {string} label
+     */
+    insertDebugMarker(label: string): void;
+    /**
+     * Record which pipeline descriptor this pass ran.
+     *
+     * @see ShadeGPUComputePassEncoder#record_pipeline
+     *
+     * @param {RenderPipelineDescriptor} descriptor
+     * @returns {void}
+     */
+    record_pipeline(descriptor: RenderPipelineDescriptor): void;
+    #private;
+}
+//# sourceMappingURL=ShadeGPURenderPassEncoder.d.ts.map

package/src/shade/device/pass/ShadeGPURenderPassEncoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShadeGPURenderPassEncoder.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/pass/ShadeGPURenderPassEncoder.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH;IAmBI;;;OAGG;IACH,8CAFW,iBAAe,IAAI,EAO7B;IASD;;OAEG;IACH,uBAEC;IAZD;;OAEG;IACH,oBAEC;IAWD;;;;;;;OAOG;IACH,eAPW,MAAM,KACN,MAAM,SACN,MAAM,UACN,MAAM,aACN,MAAM,aACN,MAAM,QAIhB;IAED;;;;;OAKG;IACH,kBALW,MAAM,KACN,MAAM,SACN,MAAM,UACN,MAAM,QAIhB;IAED;;OAEG;IACH,wCAEC;IAED;;OAEG;IACH,+BAFW,MAAM,QAIhB;IAED;;OAEG;IACH,iCAFW,MAAM,QAIhB;IAED,0BAEC;IAED;;OAEG;IACH,wBAFW,yBAAyB,QAInC;IAED,YAMC;IAID;;OAEG;IACH,+CAEC;IAED;;;;;;;;;;OAUG;IACH,qCAEC;IAED;;;;;;;OAOG;IACH,sCAEC;IAED;;;;;;;;;OASG;IACH,mBALW,MAAM,mBACN,MAAM,iBACN,MAAM,mBACN,MAAM,QAYhB;IAED;;;;;;;;OAQG;IACH,yBANW,MAAM,mBACN,MAAM,gBACN,MAAM,gBACN,MAAM,mBACN,MAAM,QAYhB;IAED;;;OAGG;IACH,0DAFW,MAAM,QAYhB;IAED;;;OAGG;IACH,iEAFW,MAAM,QAUhB;IAID;;;;;;;OAOG;IACH,oBAJW,MAAM,8CAEN,MAAM,EAAE,QAQlB;IAED;;;;;;;;;;OAUG;IACH,yBANW,MAAM,kDAEN,WAAW,cACX,MAAM,eACN,MAAM,QAIhB;IAED;;;;;;;OAOG;IACH,oCAEC;IAID;;OAEG;IACH,sBAFW,MAAM,QAIhB;IAED,sBAEC;IAED;;OAEG;IACH,yBAFW,MAAM,QAIhB;IAID;;;;;;;OAOG;IACH,uDAFa,IAAI,CAUhB;;CACJ"}