typegpu 0.11.9 → 0.12.1

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/pipeline/webgpuLimitations.d.ts

@@ -0,0 +1,10 @@
+import { type BaseData } from '../../data/wgslTypes.ts';
+import type { TgpuBindGroupLayout } from '../../tgpuBindGroupLayout.ts';
+/**
+ * Warns if layout exceeds supported buffer count limits.
+ */
+export declare function warnIfOverflow(layouts: TgpuBindGroupLayout[], limits: GPUSupportedLimits): void;
+/**
+ * See https://www.w3.org/TR/WGSL/#address-space-layout-constraints
+ */
+export declare function warnIfNotUniformAligned(schema: BaseData): void;

package/core/pipeline/webgpuLimitations.js

@@ -0,0 +1,81 @@
+import { alignmentOf } from "../../data/alignmentOf.js";
+import { memoryLayoutOf } from "../../data/offsetUtils.js";
+import { sizeOf } from "../../data/sizeOf.js";
+import { isWgslArray, isWgslStruct } from "../../data/wgslTypes.js";
+import { invariant } from "../../errors.js";
+import { roundUp } from "../../mathUtils.js";
+import { getName } from "../../shared/meta.js";
+import { logger } from "../../tgpuLogger.js";
+/**
+ * Warns if layout exceeds supported buffer count limits.
+ */
+export function warnIfOverflow(layouts, limits) {
+    const entries = Object.values(layouts)
+        .flatMap((layout) => Object.values(layout.entries))
+        .filter((entry) => entry !== null);
+    const uniform = entries.filter((entry) => 'uniform' in entry).length;
+    const storage = entries.filter((entry) => 'storage' in entry).length;
+    if (uniform > limits.maxUniformBuffersPerShaderStage) {
+        logger.warn('webgpu-limits-exceeded', `Total number of uniform buffers (${uniform}) exceeds maxUniformBuffersPerShaderStage (${limits.maxUniformBuffersPerShaderStage}). Consider:
+1. Grouping some of the uniforms into one using 'd.struct',
+2. Increasing the limit when requesting a device or creating a root.`);
+    }
+    if (storage > limits.maxStorageBuffersPerShaderStage) {
+        logger.warn('webgpu-limits-exceeded', `Total number of storage buffers (${storage}) exceeds maxStorageBuffersPerShaderStage (${limits.maxStorageBuffersPerShaderStage}).`);
+    }
+}
+function requiredAlignOf(schema) {
+    if (isWgslStruct(schema) || isWgslArray(schema)) {
+        return roundUp(alignmentOf(schema), 16);
+    }
+    return alignmentOf(schema);
+}
+/**
+ * See https://www.w3.org/TR/WGSL/#address-space-layout-constraints
+ */
+export function warnIfNotUniformAligned(schema) {
+    if (isWgslArray(schema)) {
+        warnIfNotUniformAligned(schema.elementType);
+        const stride = roundUp(sizeOf(schema.elementType), alignmentOf(schema.elementType));
+        if (stride % 16 !== 0) {
+            logger.warn('uniform-schema-misaligned', `\
+Schema '${getName(schema.elementType) ?? '<unnamed>'}' is used in an array in a uniform buffer, and its stride (${stride}) is not a multiple of 16.
+This is not portable (see https://www.w3.org/TR/WGSL/#address-space-layout-constraints), and will break on some devices.
+To address this, put the element schema in a struct and wrap the prop in 'd.align(16, ...)', or use a different schema like 'vec4f'.`);
+        }
+    }
+    if (isWgslStruct(schema)) {
+        Object.values(schema.propTypes).forEach(warnIfNotUniformAligned);
+        Object.entries(schema.propTypes).forEach(([key, value]) => {
+            const offset = memoryLayoutOf(schema, (schema) => schema[key]).offset;
+            const requiredAlignment = requiredAlignOf(value);
+            if (offset % requiredAlignment) {
+                logger.warn('uniform-schema-misaligned', `\
+Schema '${getName(schema) ?? '<unnamed>'}' is used in a uniform buffer, and its property '${key}' does not meet required alignment (offset is ${offset}, required alignment is ${requiredAlignment}).
+This is not portable (see https://www.w3.org/TR/WGSL/#address-space-layout-constraints), and will break on some devices.
+To address this, wrap the property '${key}' in 'd.align(${requiredAlignment}, ...)'.`);
+            }
+        });
+        const keys = Object.keys(schema.propTypes);
+        for (let i = 0; i < keys.length - 1; i++) {
+            const thisKey = keys[i];
+            const nextKey = keys[i + 1];
+            invariant(thisKey && nextKey);
+            const thisValue = schema.propTypes[thisKey];
+            invariant(thisValue);
+            if (!isWgslStruct(thisValue)) {
+                continue;
+            }
+            const minimumDifference = roundUp(sizeOf(thisValue), 16);
+            const thisKeyOffset = memoryLayoutOf(schema, (schema) => schema[thisKey]).offset;
+            const nextKeyOffset = memoryLayoutOf(schema, (schema) => schema[nextKey]).offset;
+            const difference = nextKeyOffset - thisKeyOffset;
+            if (minimumDifference > difference) {
+                logger.warn('uniform-schema-misaligned', `\
+Schema '${getName(schema) ?? '<unnamed>'}' is used in a uniform buffer, and the difference between memory offsets of '${thisKey}' and '${nextKey}' props (${difference}) is less than recommended (${minimumDifference}).
+This is not portable (see https://www.w3.org/TR/WGSL/#address-space-layout-constraints), and will break on some devices.
+To address this, wrap the '${thisKey}' prop in 'd.size(${minimumDifference}, ...)'.`);
+            }
+        }
+    }
+}

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>;