typegpu 0.11.8 → 0.12.0

package/core/pipeline/timeable.d.ts

@@ -1,22 +1,32 @@
-import { TgpuQuerySet } from "../querySet/querySet.js";
-import "../root/rootTypes.js";
-
-//#region src/core/pipeline/timeable.d.ts
-interface Timeable {
-  withPerformanceCallback(callback: (start: bigint, end: bigint) => void | Promise<void>): this;
-  withTimestampWrites(options: {
-    querySet: TgpuQuerySet<'timestamp'> | GPUQuerySet;
-    beginningOfPassWriteIndex?: number;
-    endOfPassWriteIndex?: number;
-  }): this;
+import { type TgpuQuerySet } from '../querySet/querySet.ts';
+import type { ExperimentalTgpuRoot } from '../root/rootTypes.ts';
+import type { TgpuCommandEncoder } from '../commandEncoder/commandEncoder.ts';
+export interface Timeable {
+    /**
+     * Attaches a callback reporting the GPU-side start and end timestamps of the pipeline's pass.
+     * Repeated executions within one command encoder write to the same query set indices,
+     * so the callback fires once, with the timestamps of the last execution.
+     */
+    withPerformanceCallback(callback: (start: bigint, end: bigint) => void | Promise<void>): this;
+    withTimestampWrites(options: {
+        querySet: TgpuQuerySet<'timestamp'> | GPUQuerySet;
+        beginningOfPassWriteIndex?: number;
+        endOfPassWriteIndex?: number;
+    }): this;
 }
-type TimestampWritesPriors = {
-  readonly timestampWrites?: {
+export type TimestampWritesPriors = {
+    readonly timestampWrites?: {
+        querySet: TgpuQuerySet<'timestamp'> | GPUQuerySet;
+        beginningOfPassWriteIndex?: number;
+        endOfPassWriteIndex?: number;
+    };
+    readonly performanceCallback?: (start: bigint, end: bigint) => void | Promise<void>;
+};
+export declare function createWithPerformanceCallback<T extends TimestampWritesPriors>(currentPriors: T, callback: (start: bigint, end: bigint) => void | Promise<void>, querySet: TgpuQuerySet<'timestamp'>): T;
+export declare function createWithTimestampWrites<T extends TimestampWritesPriors>(currentPriors: T, options: {
     querySet: TgpuQuerySet<'timestamp'> | GPUQuerySet;
     beginningOfPassWriteIndex?: number;
     endOfPassWriteIndex?: number;
-  };
-  readonly performanceCallback?: (start: bigint, end: bigint) => void | Promise<void>;
-};
-//#endregion
-export { Timeable, TimestampWritesPriors };
+}, root: ExperimentalTgpuRoot): T;
+/** Returns false when the encoder is one we cannot defer work to, meaning the callback never fires */
+export declare function queueTimestampResolve(encoder: TgpuCommandEncoder, priors: TimestampWritesPriors): boolean;

package/core/pipeline/timeable.js

@@ -1,57 +1,95 @@
-import { $internal } from "../../shared/symbols.js";
 import { isQuerySet } from "../querySet/querySet.js";
-
-//#region src/core/pipeline/timeable.ts
-function createWithPerformanceCallback(currentPriors, callback, querySet) {
-	if (!currentPriors.timestampWrites) return {
-		...currentPriors,
-		performanceCallback: callback,
-		timestampWrites: {
-			querySet,
-			beginningOfPassWriteIndex: 0,
-			endOfPassWriteIndex: 1
-		}
-	};
-	return {
-		...currentPriors,
-		performanceCallback: callback
-	};
+import { $internal } from "../../shared/symbols.js";
+import { logger } from "../../tgpuLogger.js";
+export function createWithPerformanceCallback(currentPriors, callback, querySet) {
+    if (!currentPriors.timestampWrites) {
+        return {
+            ...currentPriors,
+            performanceCallback: callback,
+            timestampWrites: {
+                querySet,
+                beginningOfPassWriteIndex: 0,
+                endOfPassWriteIndex: 1,
+            },
+        };
+    }
+    return {
+        ...currentPriors,
+        performanceCallback: callback,
+    };
 }
-function createWithTimestampWrites(currentPriors, options, root) {
-	if (!root.enabledFeatures.has("timestamp-query")) throw new Error("Timestamp writes require the \"timestamp-query\" feature to be enabled on GPU device.");
-	const timestampWrites = { querySet: options.querySet };
-	if (options.beginningOfPassWriteIndex !== void 0) timestampWrites.beginningOfPassWriteIndex = options.beginningOfPassWriteIndex;
-	if (options.endOfPassWriteIndex !== void 0) timestampWrites.endOfPassWriteIndex = options.endOfPassWriteIndex;
-	return {
-		...currentPriors,
-		timestampWrites
-	};
+export function createWithTimestampWrites(currentPriors, options, root) {
+    if (!root.enabledFeatures.has('timestamp-query')) {
+        throw new Error('Timestamp writes require the "timestamp-query" feature to be enabled on GPU device.');
+    }
+    const timestampWrites = {
+        querySet: options.querySet,
+    };
+    if (options.beginningOfPassWriteIndex !== undefined) {
+        timestampWrites.beginningOfPassWriteIndex = options.beginningOfPassWriteIndex;
+    }
+    if (options.endOfPassWriteIndex !== undefined) {
+        timestampWrites.endOfPassWriteIndex = options.endOfPassWriteIndex;
+    }
+    return {
+        ...currentPriors,
+        timestampWrites,
+    };
 }
-function setupTimestampWrites(priors, root) {
-	if (!priors.timestampWrites) return {};
-	const { querySet, beginningOfPassWriteIndex, endOfPassWriteIndex } = priors.timestampWrites;
-	const timestampWrites = { querySet: isQuerySet(querySet) ? root.unwrap(querySet) : querySet };
-	if (beginningOfPassWriteIndex !== void 0) timestampWrites.beginningOfPassWriteIndex = beginningOfPassWriteIndex;
-	if (endOfPassWriteIndex !== void 0) timestampWrites.endOfPassWriteIndex = endOfPassWriteIndex;
-	return { timestampWrites };
+const pendingTimestampReads = new WeakMap();
+async function readTimestamps(querySet, registrations) {
+    if (!querySet.available) {
+        return;
+    }
+    const result = await querySet.read();
+    for (const { priors, callback } of registrations) {
+        const start = result[priors.timestampWrites?.beginningOfPassWriteIndex ?? 0];
+        const end = result[priors.timestampWrites?.endOfPassWriteIndex ?? 1];
+        if (start === undefined || end === undefined) {
+            throw new Error('QuerySet did not return valid timestamps.');
+        }
+        await callback(start, end);
+    }
 }
-function triggerPerformanceCallback({ root, priors }) {
-	const querySet = priors.timestampWrites?.querySet;
-	const callback = priors.performanceCallback;
-	if (!querySet) throw new Error("Cannot dispatch workgroups with performance callback without a query set.");
-	if (!isQuerySet(querySet)) throw new Error("Performance callback with raw GPUQuerySet is not supported. Use TgpuQuerySet instead.");
-	const commandEncoder = root.device.createCommandEncoder();
-	commandEncoder.resolveQuerySet(root.unwrap(querySet), 0, querySet.count, querySet[$internal].resolveBuffer, 0);
-	root.device.queue.submit([commandEncoder.finish()]);
-	root.device.queue.onSubmittedWorkDone().then(async () => {
-		if (!querySet.available) return;
-		const result = await querySet.read();
-		const start = result[priors.timestampWrites?.beginningOfPassWriteIndex ?? 0];
-		const end = result[priors.timestampWrites?.endOfPassWriteIndex ?? 1];
-		if (start === void 0 || end === void 0) throw new Error("QuerySet did not return valid timestamps.");
-		await callback(start, end);
-	});
+/** Returns false when the encoder is one we cannot defer work to, meaning the callback never fires */
+export function queueTimestampResolve(encoder, priors) {
+    const querySet = priors.timestampWrites?.querySet;
+    const callback = priors.performanceCallback;
+    if (!querySet) {
+        throw new Error('Cannot dispatch workgroups with performance callback without a query set.');
+    }
+    if (!isQuerySet(querySet)) {
+        throw new Error('Performance callback with raw GPUQuerySet is not supported. Use TgpuQuerySet instead.');
+    }
+    const internals = encoder[$internal];
+    if (internals.adopted) {
+        return false;
+    }
+    const { root } = internals;
+    // recorded at submission time to capture the last pass written into this encoder
+    internals.beforeFinish.set(querySet, (rawEncoder) => {
+        rawEncoder.resolveQuerySet(root.unwrap(querySet), 0, querySet.count, querySet[$internal].resolveBuffer, 0);
+    });
+    let byQuerySet = pendingTimestampReads.get(encoder);
+    if (!byQuerySet) {
+        byQuerySet = new Map();
+        pendingTimestampReads.set(encoder, byQuerySet);
+    }
+    let registrations = byQuerySet.get(querySet);
+    if (!registrations) {
+        const regs = [];
+        registrations = regs;
+        byQuerySet.set(querySet, regs);
+        internals.afterSubmit.set(querySet, () => {
+            byQuerySet.delete(querySet);
+            void readTimestamps(querySet, regs);
+        });
+    }
+    if (registrations.some((reg) => reg.priors === priors)) {
+        logger.warnOnce('suspicious', querySet, 'repeated-timed-execution', 'Repeated executions of a timed pipeline within one command encoder write to the same query set indices, so the performance callback reports only the last execution.');
+    }
+    else {
+        registrations.push({ priors, callback });
+    }
+    return true;
 }
-
-//#endregion
-export { createWithPerformanceCallback, createWithTimestampWrites, setupTimestampWrites, triggerPerformanceCallback };

package/core/pipeline/typeGuards.d.ts

@@ -0,0 +1,17 @@
+import type { TgpuCommandEncoder } from '../commandEncoder/commandEncoder.ts';
+import type { TgpuComputePass } from '../commandEncoder/computePass.ts';
+import type { TgpuRenderCommands, TgpuRenderPass } from '../commandEncoder/renderPass.ts';
+import type { TgpuComputePipeline } from './computePipeline.ts';
+import type { TgpuRenderPipeline } from './renderPipeline.ts';
+export declare function isComputePipeline(value: unknown): value is TgpuComputePipeline;
+export declare function isRenderPipeline(value: unknown): value is TgpuRenderPipeline;
+export declare function isPipeline(value: unknown): value is TgpuComputePipeline | TgpuRenderPipeline;
+export declare function isTgpuCommandEncoder(value: unknown): value is TgpuCommandEncoder;
+export declare function isTgpuRenderPass(value: unknown): value is TgpuRenderPass;
+export declare function isTgpuRenderCommands(value: unknown): value is TgpuRenderCommands;
+export declare function isTgpuComputePass(value: unknown): value is TgpuComputePass;
+export declare function isGPUCanvasContext(value: unknown): value is GPUCanvasContext;
+export declare function isGPUCommandEncoder(value: unknown): value is GPUCommandEncoder;
+export declare function isGPUComputePassEncoder(value: unknown): value is GPUComputePassEncoder;
+export declare function isGPURenderPassEncoder(value: unknown): value is GPURenderPassEncoder;
+export declare function isGPURenderBundleEncoder(value: unknown): value is GPURenderBundleEncoder;

package/core/pipeline/typeGuards.js

@@ -1,29 +1,59 @@
-import { $internal } from "../../shared/symbols.js";
-
-//#region src/core/pipeline/typeGuards.ts
-function isComputePipeline(value) {
-	const maybe = value;
-	return maybe?.resourceType === "compute-pipeline" && !!maybe[$internal];
+import { isMarkedInternal } from "../../shared/symbols.js";
+export function isComputePipeline(value) {
+    const maybe = value;
+    return maybe?.resourceType === 'compute-pipeline' && isMarkedInternal(maybe);
 }
-function isRenderPipeline(value) {
-	const maybe = value;
-	return maybe?.resourceType === "render-pipeline" && !!maybe[$internal];
+export function isRenderPipeline(value) {
+    const maybe = value;
+    return maybe?.resourceType === 'render-pipeline' && isMarkedInternal(maybe);
 }
-function isPipeline(value) {
-	return isRenderPipeline(value) || isComputePipeline(value);
+export function isPipeline(value) {
+    return isRenderPipeline(value) || isComputePipeline(value);
 }
-function isGPUCommandEncoder(value) {
-	return !!value && typeof value === "object" && "beginRenderPass" in value && "beginComputePass" in value;
+export function isTgpuCommandEncoder(value) {
+    const maybe = value;
+    return maybe?.resourceType === 'command-encoder' && isMarkedInternal(maybe);
 }
-function isGPUComputePassEncoder(value) {
-	return !!value && typeof value === "object" && "dispatchWorkgroups" in value && !("beginRenderPass" in value);
+export function isTgpuRenderPass(value) {
+    const maybe = value;
+    return maybe?.resourceType === 'render-pass' && isMarkedInternal(maybe);
 }
-function isGPURenderPassEncoder(value) {
-	return !!value && typeof value === "object" && "executeBundles" in value && "draw" in value;
+export function isTgpuRenderCommands(value) {
+    const maybe = value;
+    return ((maybe?.resourceType === 'render-pass' || maybe?.resourceType === 'render-bundle-encoder') &&
+        isMarkedInternal(maybe));
 }
-function isGPURenderBundleEncoder(value) {
-	return !!value && typeof value === "object" && "draw" in value && "finish" in value && !("executeBundles" in value) && !("beginRenderPass" in value) && !("dispatchWorkgroups" in value);
+export function isTgpuComputePass(value) {
+    const maybe = value;
+    return maybe?.resourceType === 'compute-pass' && isMarkedInternal(maybe);
+}
+export function isGPUCanvasContext(value) {
+    return typeof value?.getCurrentTexture === 'function';
+}
+export function isGPUCommandEncoder(value) {
+    const maybe = value;
+    return (!isMarkedInternal(maybe) &&
+        typeof maybe?.beginRenderPass === 'function' &&
+        typeof maybe?.beginComputePass === 'function');
+}
+export function isGPUComputePassEncoder(value) {
+    const maybe = value;
+    return (!isMarkedInternal(maybe) &&
+        typeof maybe?.dispatchWorkgroups === 'function' &&
+        maybe?.beginRenderPass === undefined);
+}
+export function isGPURenderPassEncoder(value) {
+    const maybe = value;
+    return (!isMarkedInternal(maybe) &&
+        typeof maybe?.executeBundles === 'function' &&
+        typeof maybe?.draw === 'function');
+}
+export function isGPURenderBundleEncoder(value) {
+    const maybe = value;
+    return (!isMarkedInternal(maybe) &&
+        typeof maybe?.draw === 'function' &&
+        typeof maybe?.finish === 'function' &&
+        maybe?.executeBundles === undefined &&
+        maybe?.beginRenderPass === undefined &&
+        maybe?.dispatchWorkgroups === undefined);
 }
-
-//#endregion
-export { isComputePipeline, isGPUCommandEncoder, isGPUComputePassEncoder, isGPURenderBundleEncoder, isGPURenderPassEncoder, isPipeline, isRenderPipeline };

package/core/querySet/querySet.d.ts

@@ -1,22 +1,27 @@
-import { TgpuNamable } from "../../shared/meta.js";
-import { $internal } from "../../shared/symbols.js";
-import "../root/rootTypes.js";
-
-//#region src/core/querySet/querySet.d.ts
-interface TgpuQuerySet<T extends GPUQueryType> extends TgpuNamable {
-  readonly resourceType: 'query-set';
-  readonly type: T;
-  readonly count: number;
-  readonly querySet: GPUQuerySet;
-  readonly destroyed: boolean;
-  readonly available: boolean;
-  readonly [$internal]: {
-    readonly readBuffer: GPUBuffer;
-    readonly resolveBuffer: GPUBuffer;
-  };
-  resolve(): void;
-  read(): Promise<bigint[]>;
-  destroy(): void;
+import { type TgpuNamable } from '../../shared/meta.ts';
+import type { ExperimentalTgpuRoot } from '../root/rootTypes.ts';
+import type { TgpuDeviceOwningSoul } from '../../shared/soul.ts';
+import { $internal, $soul } from '../../shared/symbols.ts';
+export interface TgpuQuerySetSoul<T extends GPUQueryType = GPUQueryType> extends TgpuDeviceOwningSoul<'query-set', GPUQuerySet> {
+    readonly queryType: T;
+    readonly count: number;
 }
-//#endregion
-export { TgpuQuerySet };
+export interface TgpuQuerySet<T extends GPUQueryType> extends TgpuNamable {
+    readonly resourceType: 'query-set';
+    readonly type: T;
+    readonly count: number;
+    readonly querySet: GPUQuerySet;
+    readonly destroyed: boolean;
+    readonly available: boolean;
+    readonly [$soul]: TgpuQuerySetSoul<T>;
+    readonly [$internal]: {
+        readonly readBuffer: GPUBuffer;
+        readonly resolveBuffer: GPUBuffer;
+        readonly materialize: () => GPUQuerySet;
+    };
+    resolve(): void;
+    read(): Promise<bigint[]>;
+    destroy(): void;
+}
+export declare function INTERNAL_createQuerySet<T extends GPUQueryType>(group: ExperimentalTgpuRoot, type: T, count: number, rawQuerySet?: GPUQuerySet): TgpuQuerySet<T>;
+export declare function isQuerySet<T extends GPUQueryType>(value: unknown): value is TgpuQuerySet<T>;

package/core/querySet/querySet.js

@@ -1,106 +1,130 @@
-import { $internal } from "../../shared/symbols.js";
 import { setName } from "../../shared/meta.js";
-
-//#region src/core/querySet/querySet.ts
-function INTERNAL_createQuerySet(group, type, count, rawQuerySet) {
-	return new TgpuQuerySetImpl(group, type, count, rawQuerySet);
+import { $internal, $soul } from "../../shared/symbols.js";
+export function INTERNAL_createQuerySet(group, type, count, rawQuerySet) {
+    return new TgpuQuerySetImpl(group, type, count, rawQuerySet);
 }
-function isQuerySet(value) {
-	const maybe = value;
-	return maybe?.resourceType === "query-set" && !!maybe[$internal];
+export function isQuerySet(value) {
+    const maybe = value;
+    return maybe?.resourceType === 'query-set' && !!maybe[$internal];
+}
+class TgpuQuerySetImpl {
+    resourceType = 'query-set';
+    #ownQuerySet;
+    #destroyed = false;
+    #available = true;
+    #readBuffer = undefined;
+    #resolveBuffer = undefined;
+    [$soul];
+    [$internal];
+    constructor(root, type, count, rawQuerySet) {
+        this.#ownQuerySet = !rawQuerySet;
+        this[$soul] = {
+            type: 'query-set',
+            device: root.device,
+            queryType: type,
+            count,
+            raw: rawQuerySet,
+            label: undefined,
+        };
+        // oxlint-disable-next-line typescript/no-this-alias
+        const self = this;
+        this[$internal] = {
+            get readBuffer() {
+                if (!self.#readBuffer) {
+                    self.#readBuffer = self[$soul].device.createBuffer({
+                        size: self.count * BigUint64Array.BYTES_PER_ELEMENT,
+                        usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+                    });
+                }
+                return self.#readBuffer;
+            },
+            get resolveBuffer() {
+                if (!self.#resolveBuffer) {
+                    self.#resolveBuffer = self[$soul].device.createBuffer({
+                        size: self.count * BigUint64Array.BYTES_PER_ELEMENT,
+                        usage: GPUBufferUsage.QUERY_RESOLVE | GPUBufferUsage.COPY_SRC,
+                    });
+                }
+                return self.#resolveBuffer;
+            },
+            materialize: () => {
+                if (this.#destroyed) {
+                    throw new Error('This QuerySet has been destroyed.');
+                }
+                const soul = this[$soul];
+                if (!soul.raw) {
+                    soul.raw = soul.device.createQuerySet({
+                        type: soul.queryType,
+                        count: soul.count,
+                    });
+                }
+                return soul.raw;
+            },
+        };
+    }
+    get type() {
+        return this[$soul].queryType;
+    }
+    get count() {
+        return this[$soul].count;
+    }
+    get querySet() {
+        return this[$internal].materialize();
+    }
+    get destroyed() {
+        return this.#destroyed;
+    }
+    get available() {
+        return this.#available;
+    }
+    $name(label) {
+        setName(this, label);
+        const raw = this[$soul].raw;
+        if (raw) {
+            raw.label = label;
+        }
+        return this;
+    }
+    resolve() {
+        if (this.#destroyed) {
+            throw new Error('This QuerySet has been destroyed.');
+        }
+        if (!this.#available) {
+            throw new Error('This QuerySet is busy resolving or reading.');
+        }
+        const commandEncoder = this[$soul].device.createCommandEncoder();
+        commandEncoder.resolveQuerySet(this.querySet, 0, this.count, this[$internal].resolveBuffer, 0);
+        this[$soul].device.queue.submit([commandEncoder.finish()]);
+    }
+    async read() {
+        if (!this.#resolveBuffer) {
+            throw new Error('QuerySet must be resolved before reading.');
+        }
+        this.#available = false;
+        try {
+            const commandEncoder = this[$soul].device.createCommandEncoder();
+            commandEncoder.copyBufferToBuffer(this[$internal].resolveBuffer, 0, this[$internal].readBuffer, 0, this.count * BigUint64Array.BYTES_PER_ELEMENT);
+            this[$soul].device.queue.submit([commandEncoder.finish()]);
+            const readBuffer = this[$internal].readBuffer;
+            await readBuffer.mapAsync(GPUMapMode.READ);
+            const data = new BigUint64Array(readBuffer.getMappedRange().slice());
+            readBuffer.unmap();
+            return Array.from(data);
+        }
+        finally {
+            this.#available = true;
+        }
+    }
+    destroy() {
+        if (this.#destroyed) {
+            return;
+        }
+        this.#destroyed = true;
+        if (this[$soul].raw && this.#ownQuerySet) {
+            this[$soul].raw.destroy();
+        }
+        this.#readBuffer?.destroy();
+        this.#resolveBuffer?.destroy();
+        this.#readBuffer = this.#resolveBuffer = undefined;
+    }
 }
-var TgpuQuerySetImpl = class {
-	resourceType = "query-set";
-	type;
-	count;
-	#rawQuerySet;
-	#device;
-	#querySet;
-	#ownQuerySet;
-	#destroyed = false;
-	#available = true;
-	#readBuffer = void 0;
-	#resolveBuffer = void 0;
-	constructor(root, type, count, rawQuerySet) {
-		this.#device = root.device;
-		this.type = type;
-		this.count = count;
-		this.#rawQuerySet = rawQuerySet;
-		this.#ownQuerySet = !rawQuerySet;
-		this.#querySet = rawQuerySet;
-	}
-	get querySet() {
-		if (this.#destroyed) throw new Error("This QuerySet has been destroyed.");
-		if (this.#rawQuerySet) return this.#rawQuerySet;
-		if (this.#querySet) return this.#querySet;
-		this.#querySet = this.#device.createQuerySet({
-			type: this.type,
-			count: this.count
-		});
-		return this.#querySet;
-	}
-	get destroyed() {
-		return this.#destroyed;
-	}
-	get available() {
-		return this.#available;
-	}
-	get [$internal]() {
-		const self = this;
-		return {
-			get readBuffer() {
-				if (!self.#readBuffer) self.#readBuffer = self.#device.createBuffer({
-					size: self.count * BigUint64Array.BYTES_PER_ELEMENT,
-					usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ
-				});
-				return self.#readBuffer;
-			},
-			get resolveBuffer() {
-				if (!self.#resolveBuffer) self.#resolveBuffer = self.#device.createBuffer({
-					size: self.count * BigUint64Array.BYTES_PER_ELEMENT,
-					usage: GPUBufferUsage.QUERY_RESOLVE | GPUBufferUsage.COPY_SRC
-				});
-				return self.#resolveBuffer;
-			}
-		};
-	}
-	$name(label) {
-		setName(this, label);
-		if (this.#querySet) this.#querySet.label = label;
-		return this;
-	}
-	resolve() {
-		if (this.#destroyed) throw new Error("This QuerySet has been destroyed.");
-		if (!this.#available) throw new Error("This QuerySet is busy resolving or reading.");
-		const commandEncoder = this.#device.createCommandEncoder();
-		commandEncoder.resolveQuerySet(this.querySet, 0, this.count, this[$internal].resolveBuffer, 0);
-		this.#device.queue.submit([commandEncoder.finish()]);
-	}
-	async read() {
-		if (!this.#resolveBuffer) throw new Error("QuerySet must be resolved before reading.");
-		this.#available = false;
-		try {
-			const commandEncoder = this.#device.createCommandEncoder();
-			commandEncoder.copyBufferToBuffer(this[$internal].resolveBuffer, 0, this[$internal].readBuffer, 0, this.count * BigUint64Array.BYTES_PER_ELEMENT);
-			this.#device.queue.submit([commandEncoder.finish()]);
-			const readBuffer = this[$internal].readBuffer;
-			await readBuffer.mapAsync(GPUMapMode.READ);
-			const data = new BigUint64Array(readBuffer.getMappedRange().slice());
-			readBuffer.unmap();
-			return Array.from(data);
-		} finally {
-			this.#available = true;
-		}
-	}
-	destroy() {
-		if (this.#destroyed) return;
-		this.#destroyed = true;
-		if (this.#querySet && this.#ownQuerySet) this.#querySet.destroy();
-		this.#readBuffer?.destroy();
-		this.#resolveBuffer?.destroy();
-		this.#readBuffer = this.#resolveBuffer = void 0;
-	}
-};
-
-//#endregion
-export { INTERNAL_createQuerySet, isQuerySet };

package/core/rawCodeSnippet/tgpuRawCodeSnippet.d.ts

@@ -1,22 +1,18 @@
-import { $gpuValueOf } from "../../shared/symbols.js";
-import { Origin } from "../../data/snippet.js";
-import { BaseData } from "../../data/wgslTypes.js";
-import { InferGPU } from "../../shared/repr.js";
-import { AnyData } from "../../data/dataTypes.js";
-
-//#region src/core/rawCodeSnippet/tgpuRawCodeSnippet.d.ts
-
+import type { AnyData } from '../../data/dataTypes.ts';
+import { type Origin } from '../../data/snippet.ts';
+import type { BaseData } from '../../data/wgslTypes.ts';
+import type { InferGPU } from '../../shared/repr.ts';
+import { $gpuValueOf } from '../../shared/symbols.ts';
 /**
  * Extra declaration that will be included in final WGSL code
  * when resolving objects that use it.
  */
-interface TgpuRawCodeSnippet<TDataType extends BaseData> {
-  $: InferGPU<TDataType>;
-  value: InferGPU<TDataType>;
-  readonly [$gpuValueOf]: InferGPU<TDataType>;
-  $uses(dependencyMap: Record<string, unknown>): this;
+export interface TgpuRawCodeSnippet<TDataType extends BaseData> {
+    $: InferGPU<TDataType>;
+    readonly [$gpuValueOf]: InferGPU<TDataType>;
+    $uses(dependencyMap: Record<string, unknown>): this;
 }
-type RawCodeSnippetOrigin = Exclude<Origin, 'function' | 'local-def' | 'argument' | 'constant-immutable-def' | 'runtime-immutable-def'>;
+export type RawCodeSnippetOrigin = Exclude<Origin, 'function' | 'local-def' | 'argument' | 'constant-immutable-def' | 'runtime-immutable-def'>;
 /**
  * An advanced API that creates a typed shader expression which
  * can be injected into the final shader bundle upon use.
@@ -24,6 +20,7 @@ type RawCodeSnippetOrigin = Exclude<Origin, 'function' | 'local-def' | 'argument
  * @param expression The code snippet that will be injected in place of `foo.$`
  * @param type The type of the expression
  * @param [origin='runtime'] Where the value originates from.
+ * @param [possibleSideEffects=true] Whether generating this snippet may produce a WGSL expression with observable side-effects (e.g. calling a barrier, discarding a fragment, or writing to memory).
  *
  * **-- Which origin to choose?**
  *
@@ -42,7 +39,7 @@ type RawCodeSnippetOrigin = Exclude<Origin, 'function' | 'local-def' | 'argument
  * // final shader bundle, but we cannot
  * // refer to it in any other way.
  * const existingGlobal = tgpu['~unstable']
- *   .rawCodeSnippet('EXISTING_GLOBAL', d.f32, 'constant');
+ *   .rawCodeSnippet('EXISTING_GLOBAL', d.f32, 'constant', false);
  *
  * const foo = () => {
  *   'use gpu';
@@ -55,6 +52,4 @@ type RawCodeSnippetOrigin = Exclude<Origin, 'function' | 'local-def' | 'argument
  * // }
  * ```
  */
-declare function rawCodeSnippet<TDataType extends AnyData>(expression: string, type: TDataType, origin?: RawCodeSnippetOrigin | undefined): TgpuRawCodeSnippet<TDataType>;
-//#endregion
-export { RawCodeSnippetOrigin, TgpuRawCodeSnippet, rawCodeSnippet };
+export declare function rawCodeSnippet<TDataType extends AnyData>(expression: string, type: TDataType, origin?: RawCodeSnippetOrigin | undefined, possibleSideEffects?: boolean | undefined): TgpuRawCodeSnippet<TDataType>;