typegpu 0.11.9 → 0.12.1

package/core/pipeline/drawState.d.ts

@@ -0,0 +1,52 @@
+import type { BaseData } from '../../data/wgslTypes.ts';
+import { type TgpuBindGroup, type TgpuBindGroupLayout } from '../../tgpuBindGroupLayout.ts';
+import type { LogResources } from '../../tgsl/consoleLog/types.ts';
+import type { IndexFlag, TgpuBuffer, VertexFlag } from '../buffer/buffer.ts';
+import type { TgpuCommandEncoder } from '../commandEncoder/commandEncoder.ts';
+import type { ComputePassInternals } from '../commandEncoder/computePass.ts';
+import type { RenderPassInternals } from '../commandEncoder/renderPass.ts';
+import type { ExperimentalTgpuRoot } from '../root/rootTypes.ts';
+import type { TgpuVertexLayout } from '../vertexLayout/vertexLayout.ts';
+import type { TgpuComputePipeline } from './computePipeline.ts';
+import type { TgpuRenderPipeline } from './renderPipeline.ts';
+import { type TimestampWritesPriors } from './timeable.ts';
+export interface VertexBufferEntry {
+    buffer: (TgpuBuffer<BaseData> & VertexFlag) | GPUBuffer;
+    offset?: number | undefined;
+    size?: number | undefined;
+}
+export interface IndexBufferEntry {
+    buffer: (TgpuBuffer<BaseData> & IndexFlag) | GPUBuffer;
+    indexFormat: GPUIndexFormat;
+    offsetBytes?: number | undefined;
+    sizeBytes?: number | undefined;
+}
+export declare class RenderDrawState {
+    readonly bindGroups: Map<TgpuBindGroupLayout<Record<string, import("../../tgpuBindGroupLayout.ts").TgpuLayoutEntry | null>>, TgpuBindGroup | GPUBindGroup>;
+    readonly vertexBuffers: Map<TgpuVertexLayout<import("../../data/wgslTypes.ts").WgslArray<BaseData> | import("../../data/dataTypes.ts").Disarray<BaseData>>, VertexBufferEntry>;
+    currentPipeline: TgpuRenderPipeline | undefined;
+    indexBuffer: IndexBufferEntry | undefined;
+    stencilReference: GPUStencilValue | undefined;
+    /** What the raw pass holds, starting at the WebGPU default; survives executeBundles */
+    appliedStencilReference: GPUStencilValue;
+    version: number;
+    /** Raw access via `root.unwrap(pass)` can mutate state invisibly, disabling deduplication */
+    rawAccessed: boolean;
+}
+export declare class ComputeDrawState {
+    readonly bindGroups: Map<TgpuBindGroupLayout<Record<string, import("../../tgpuBindGroupLayout.ts").TgpuLayoutEntry | null>>, TgpuBindGroup | GPUBindGroup>;
+    currentPipeline: TgpuComputePipeline | undefined;
+    version: number;
+    rawAccessed: boolean;
+}
+export declare function recordBindGroup(state: RenderDrawState | ComputeDrawState, first: TgpuBindGroup | TgpuBindGroupLayout, bindGroup: TgpuBindGroup | GPUBindGroup | undefined): void;
+/** Writes the pipeline and its bound resources into pass state; later set* calls overwrite them */
+export declare function stampRenderPipeline(state: RenderDrawState, pipeline: TgpuRenderPipeline): void;
+/** The compute counterpart of {@link stampRenderPipeline} */
+export declare function stampComputePipeline(state: ComputeDrawState, pipeline: TgpuComputePipeline): void;
+export declare function requireIndexBuffer(indexBuffer: IndexBufferEntry | undefined): void;
+export declare function finalizeOwnEncoder(encoder: TgpuCommandEncoder, core: object, logResources: LogResources | undefined, priors: TimestampWritesPriors & {
+    readonly encoder?: TgpuCommandEncoder | undefined;
+}): void;
+export declare function emitRenderDraw(root: ExperimentalTgpuRoot, passInternals: RenderPassInternals, pipeline: TgpuRenderPipeline, usesIndexBuffer: boolean, emit: (rawPass: GPURenderPassEncoder | GPURenderBundleEncoder) => void, ownsPass?: boolean): void;
+export declare function emitComputeDispatch(root: ExperimentalTgpuRoot, passInternals: ComputePassInternals, pipeline: TgpuComputePipeline, emit: (rawPass: GPUComputePassEncoder) => void, ownsPass?: boolean): void;

package/core/pipeline/drawState.js

@@ -0,0 +1,225 @@
+import { MissingBindGroupsError, MissingVertexBuffersError } from "../../errors.js";
+import { $internal } from "../../shared/symbols.js";
+import { logger } from "../../tgpuLogger.js";
+import { isBindGroup, } from "../../tgpuBindGroupLayout.js";
+import { logDataFromGPU } from "../../tgsl/consoleLog/deserializers.js";
+import { isBuffer } from "../../types.js";
+import { queueTimestampResolve } from "./timeable.js";
+export class RenderDrawState {
+    bindGroups = new Map();
+    vertexBuffers = new Map();
+    currentPipeline;
+    indexBuffer;
+    stencilReference;
+    /** What the raw pass holds, starting at the WebGPU default; survives executeBundles */
+    appliedStencilReference = 0;
+    version = 0;
+    /** Raw access via `root.unwrap(pass)` can mutate state invisibly, disabling deduplication */
+    rawAccessed = false;
+}
+export class ComputeDrawState {
+    bindGroups = new Map();
+    currentPipeline;
+    version = 0;
+    rawAccessed = false;
+}
+export function recordBindGroup(state, first, bindGroup) {
+    if (isBindGroup(first)) {
+        state.bindGroups.set(first.layout, first);
+    }
+    else {
+        state.bindGroups.set(first, bindGroup);
+    }
+    state.version++;
+}
+/** Writes the pipeline and its bound resources into pass state; later set* calls overwrite them */
+export function stampRenderPipeline(state, pipeline) {
+    const { priors } = pipeline[$internal];
+    state.currentPipeline = pipeline;
+    if (priors.bindGroupLayoutMap) {
+        for (const [layout, group] of priors.bindGroupLayoutMap) {
+            state.bindGroups.set(layout, group);
+        }
+    }
+    if (priors.vertexLayoutMap) {
+        for (const [layout, buffer] of priors.vertexLayoutMap) {
+            state.vertexBuffers.set(layout, { buffer, offset: undefined, size: undefined });
+        }
+    }
+    if (priors.indexBuffer) {
+        state.indexBuffer = priors.indexBuffer;
+    }
+    if (priors.stencilReference !== undefined) {
+        state.stencilReference = priors.stencilReference;
+    }
+    state.version++;
+}
+/** The compute counterpart of {@link stampRenderPipeline} */
+export function stampComputePipeline(state, pipeline) {
+    const { priors } = pipeline[$internal];
+    state.currentPipeline = pipeline;
+    if (priors.bindGroupLayoutMap) {
+        for (const [layout, group] of priors.bindGroupLayoutMap) {
+            state.bindGroups.set(layout, group);
+        }
+    }
+    state.version++;
+}
+function applyIndexBuffer(encoder, root, entry) {
+    const { buffer, indexFormat, offsetBytes, sizeBytes } = entry;
+    if (isBuffer(buffer)) {
+        encoder.setIndexBuffer(root.unwrap(buffer), indexFormat, offsetBytes, sizeBytes);
+    }
+    else {
+        encoder.setIndexBuffer(buffer, indexFormat, offsetBytes, sizeBytes);
+    }
+}
+function applyBindGroups(encoder, root, usedBindGroupLayouts, catchall, resolveBindGroup) {
+    const missingBindGroups = new Set(usedBindGroupLayouts);
+    usedBindGroupLayouts.forEach((layout, idx) => {
+        if (catchall && idx === catchall[0]) {
+            encoder.setBindGroup(idx, root.unwrap(catchall[1]));
+            missingBindGroups.delete(layout);
+        }
+        else {
+            const bindGroup = resolveBindGroup(layout);
+            if (bindGroup !== undefined) {
+                missingBindGroups.delete(layout);
+                if (isBindGroup(bindGroup)) {
+                    encoder.setBindGroup(idx, root.unwrap(bindGroup));
+                }
+                else {
+                    encoder.setBindGroup(idx, bindGroup);
+                }
+            }
+        }
+    });
+    if (missingBindGroups.size > 0) {
+        throw new MissingBindGroupsError(missingBindGroups);
+    }
+}
+function applyVertexBuffers(encoder, root, usedVertexLayouts, resolveVertexBuffer) {
+    const missingVertexLayouts = new Set();
+    usedVertexLayouts.forEach((vertexLayout, idx) => {
+        const entry = resolveVertexBuffer(vertexLayout);
+        if (!entry || !entry.buffer) {
+            missingVertexLayouts.add(vertexLayout);
+        }
+        else if (isBuffer(entry.buffer)) {
+            encoder.setVertexBuffer(idx, root.unwrap(entry.buffer), entry.offset, entry.size);
+        }
+        else {
+            encoder.setVertexBuffer(idx, entry.buffer, entry.offset, entry.size);
+        }
+    });
+    if (missingVertexLayouts.size > 0) {
+        throw new MissingVertexBuffersError(missingVertexLayouts);
+    }
+}
+function applyRenderPipelineState(encoder, root, pipeline, passState) {
+    const memo = pipeline[$internal].core.unwrap();
+    encoder.setPipeline(memo.pipeline);
+    applyBindGroups(encoder, root, memo.usedBindGroupLayouts, memo.catchall, (layout) => passState.bindGroups.get(layout));
+    applyVertexBuffers(encoder, root, memo.usedVertexLayouts, (vertexLayout) => passState.vertexBuffers.get(vertexLayout));
+    if (passState.indexBuffer !== undefined) {
+        applyIndexBuffer(encoder, root, passState.indexBuffer);
+    }
+    if (typeof encoder.setStencilReference === 'function' &&
+        passState.stencilReference !== undefined) {
+        if (passState.rawAccessed || passState.stencilReference !== passState.appliedStencilReference) {
+            encoder.setStencilReference(passState.stencilReference);
+            passState.appliedStencilReference = passState.stencilReference;
+        }
+    }
+}
+function applyComputePipelineState(encoder, root, pipeline, passState) {
+    const memo = pipeline[$internal].core.unwrap();
+    encoder.setPipeline(memo.pipeline);
+    applyBindGroups(encoder, root, memo.usedBindGroupLayouts, memo.catchall, (layout) => passState.bindGroups.get(layout));
+}
+export function requireIndexBuffer(indexBuffer) {
+    if (!indexBuffer) {
+        throw new Error('No index buffer is set. Call pipeline.withIndexBuffer or pass.setIndexBuffer before drawing indexed geometry.');
+    }
+}
+function warnAboutUnreachableSubmission(core, what) {
+    logger.warnOnce('suspicious', core, what, `${what} is ignored when recording into a raw GPUCommandEncoder, since there is no submission to report after. Use root['~unstable'].createCommandEncoder() instead.`);
+}
+/** Returns false when there is no encoder to defer the read to, meaning the output is lost */
+function queueLogDrain(encoder, logResources) {
+    if (!encoder || encoder[$internal].adopted) {
+        return false;
+    }
+    encoder[$internal].afterSubmit.set(logResources, () => logDataFromGPU(logResources));
+    return true;
+}
+export function finalizeOwnEncoder(encoder, core, logResources, priors) {
+    if (logResources && !queueLogDrain(encoder, logResources)) {
+        warnAboutUnreachableSubmission(core, 'Shader console.log output');
+    }
+    if (priors.performanceCallback && !queueTimestampResolve(encoder, priors)) {
+        warnAboutUnreachableSubmission(core, 'The performance callback');
+    }
+    if (priors.encoder === undefined) {
+        encoder.submit();
+    }
+}
+const PassKindWording = {
+    render: {
+        into: 'drawing into a render pass',
+        intoRaw: 'drawing into a raw render pass',
+        begin: 'beginRenderPass',
+    },
+    compute: {
+        into: 'dispatching into a compute pass',
+        intoRaw: 'dispatching into a raw compute pass',
+        begin: 'beginComputePass',
+    },
+};
+function reportIgnoredPriors(core, owner, hasTimestampWrites, logResources, passKind, hasAttachments = false) {
+    const wording = PassKindWording[passKind];
+    if (hasAttachments) {
+        logger.warnOnce('suspicious', core, 'attachments', `Pipeline-level attachments are ignored when ${wording.into}. Pass \`colorAttachments\` and \`depthStencilAttachment\` to encoder.${wording.begin} instead.`);
+    }
+    if (hasTimestampWrites) {
+        logger.warnOnce('suspicious', core, 'timestampWrites', `Pipeline-level timestamp writes are ignored when ${wording.into}. Pass \`timestampWrites\` to encoder.${wording.begin} instead.`);
+    }
+    if (logResources && !queueLogDrain(owner, logResources)) {
+        logger.warnOnce('suspicious', core, 'logs', `Shader console.log output is ignored when ${wording.intoRaw} encoder, since there is no submission to read it back after.`);
+    }
+}
+export function emitRenderDraw(root, passInternals, pipeline, usesIndexBuffer, emit, ownsPass = false) {
+    const { state, rawPass } = passInternals;
+    const { core, priors } = pipeline[$internal];
+    if (state.currentPipeline !== pipeline) {
+        stampRenderPipeline(state, pipeline);
+    }
+    if (usesIndexBuffer) {
+        requireIndexBuffer(state.indexBuffer);
+    }
+    const memo = core.unwrap();
+    if (!ownsPass) {
+        reportIgnoredPriors(core, passInternals.owner, !!priors.timestampWrites, memo.logResources, 'render', !!priors.colorAttachment || !!priors.depthStencilAttachment);
+    }
+    if (state.rawAccessed || passInternals.appliedVersion !== state.version) {
+        applyRenderPipelineState(rawPass, root, pipeline, state);
+        passInternals.appliedVersion = state.version;
+    }
+    emit(rawPass);
+}
+export function emitComputeDispatch(root, passInternals, pipeline, emit, ownsPass = false) {
+    const { state, rawPass } = passInternals;
+    const { core, priors } = pipeline[$internal];
+    if (state.currentPipeline !== pipeline) {
+        stampComputePipeline(state, pipeline);
+    }
+    const memo = core.unwrap();
+    if (!ownsPass) {
+        reportIgnoredPriors(core, passInternals.owner, !!priors.timestampWrites, memo.logResources, 'compute');
+    }
+    if (state.rawAccessed || passInternals.appliedVersion !== state.version) {
+        applyComputePipelineState(rawPass, root, pipeline, state);
+        passInternals.appliedVersion = state.version;
+    }
+    emit(rawPass);
+}

package/core/pipeline/performanceTracker.d.ts

@@ -0,0 +1,14 @@
+import type { ResolutionResult } from '../../resolutionCtx.ts';
+export interface PerformanceTracker {
+    measureResolve(callback: () => ResolutionResult): ResolutionResult;
+    measureCompile(device: GPUDevice): void;
+}
+export declare class PerformanceTrackerImpl implements PerformanceTracker {
+    #private;
+    measureResolve(callback: () => ResolutionResult): ResolutionResult;
+    measureCompile(device: GPUDevice): void;
+}
+export declare class NullPerformanceTracker implements PerformanceTracker {
+    measureResolve(callback: () => ResolutionResult): ResolutionResult;
+    measureCompile(): void;
+}

package/core/pipeline/performanceTracker.js

@@ -0,0 +1,34 @@
+import { PERF } from "../../shared/meta.js";
+export class PerformanceTrackerImpl {
+    #resolveMeasure;
+    #wgslSize;
+    measureResolve(callback) {
+        const resolveStart = performance.mark('typegpu:resolution:start');
+        const result = callback();
+        this.#resolveMeasure = performance.measure('typegpu:resolution', {
+            start: resolveStart.name,
+        });
+        this.#wgslSize = result.code.length;
+        return result;
+    }
+    measureCompile(device) {
+        void (async () => {
+            const start = performance.mark('typegpu:compile-start');
+            await device.queue.onSubmittedWorkDone();
+            const compileMeasure = performance.measure('typegpu:compiled', {
+                start: start.name,
+            });
+            PERF?.record('resolution', {
+                resolveDuration: this.#resolveMeasure?.duration,
+                compileDuration: compileMeasure.duration,
+                wgslSize: this.#wgslSize,
+            });
+        })();
+    }
+}
+export class NullPerformanceTracker {
+    measureResolve(callback) {
+        return callback();
+    }
+    measureCompile() { }
+}

package/core/pipeline/pipelineUtils.d.ts

@@ -0,0 +1,18 @@
+import type { IndirectFlag, TgpuBuffer } from '../buffer/buffer.ts';
+import { type PrimitiveOffsetInfo } from '../../data/offsetUtils.ts';
+import type { BaseData } from '../../data/wgslTypes.ts';
+import type { TgpuBindGroup, TgpuBindGroupLayout } from '../../tgpuBindGroupLayout.ts';
+import type { TgpuVertexLayout } from '../vertexLayout/vertexLayout.ts';
+import type { Timeable, TimestampWritesPriors } from './timeable.ts';
+export declare const DISPATCH_INDIRECT_SIZE = 12;
+export declare const DRAW_INDIRECT_SIZE = 16;
+export declare const DRAW_INDEXED_INDIRECT_SIZE = 20;
+export declare function collectBindGroupPairs(layouts: TgpuBindGroupLayout[], catchall: [number, TgpuBindGroup] | undefined, map: Map<TgpuBindGroupLayout, TgpuBindGroup | GPUBindGroup> | undefined): [TgpuBindGroupLayout, TgpuBindGroup | GPUBindGroup][];
+export declare function collectVertexBufferPairs<Buffer>(layouts: TgpuVertexLayout[], map: Map<TgpuVertexLayout, Buffer> | undefined): [TgpuVertexLayout, Buffer][];
+export declare function restoreTimestampPriors<T extends Timeable>(pipeline: T, priors: {
+    readonly timestampWrites?: TimestampWritesPriors['timestampWrites'] | undefined;
+    readonly performanceCallback?: TimestampWritesPriors['performanceCallback'] | undefined;
+}): T;
+type IndirectOperation = 'dispatchWorkgroupsIndirect' | 'drawIndirect' | 'drawIndexedIndirect';
+export declare function resolveIndirectOffset(indirectBuffer: (TgpuBuffer<BaseData> & IndirectFlag) | GPUBuffer, start: PrimitiveOffsetInfo | number | undefined, requiredSize: number, operation: IndirectOperation): number;
+export {};

package/core/pipeline/pipelineUtils.js

@@ -1,31 +1,60 @@
-import { isGPUBuffer } from "../../types.js";
-import { sizeOf } from "../../data/sizeOf.js";
 import { memoryLayoutOf } from "../../data/offsetUtils.js";
-
-//#region src/core/pipeline/pipelineUtils.ts
+import { sizeOf } from "../../data/sizeOf.js";
+import { isGPUBuffer } from "../../types.js";
+import { logger } from "../../tgpuLogger.js";
+export const DISPATCH_INDIRECT_SIZE = 12; // 3 x u32 (x, y, z)
+export const DRAW_INDIRECT_SIZE = 16; // 4 x 4
+export const DRAW_INDEXED_INDIRECT_SIZE = 20; // 5 x 4
+export function collectBindGroupPairs(layouts, catchall, map) {
+    return layouts.flatMap((layout, idx) => {
+        const resource = catchall && idx === catchall[0] ? catchall[1] : map?.get(layout);
+        return resource ? [[layout, resource]] : [];
+    });
+}
+export function collectVertexBufferPairs(layouts, map) {
+    return layouts.flatMap((layout) => {
+        const resource = map?.get(layout);
+        return resource ? [[layout, resource]] : [];
+    });
+}
+export function restoreTimestampPriors(pipeline, priors) {
+    let result = pipeline;
+    if (priors.timestampWrites) {
+        result = result.withTimestampWrites(priors.timestampWrites);
+    }
+    if (priors.performanceCallback) {
+        result = result.withPerformanceCallback(priors.performanceCallback);
+    }
+    return result;
+}
 const IndirectOperationToRequiredData = {
-	dispatchWorkgroupsIndirect: "3 x u32",
-	drawIndirect: "4 x u32",
-	drawIndexedIndirect: "3 x u32, i32, u32"
+    dispatchWorkgroupsIndirect: '3 x u32',
+    drawIndirect: '4 x u32',
+    drawIndexedIndirect: '3 x u32, i32, u32',
 };
 function validateIndirectBufferSize(bufferSize, offset, requiredBytes, operation) {
-	if (offset + requiredBytes > bufferSize) throw new Error(`Buffer too small for ${operation}. Required: ${requiredBytes} bytes at offset ${offset}, but buffer is only ${bufferSize} bytes.`);
-	if (offset % 4 !== 0) throw new Error(`Indirect buffer offset must be a multiple of 4. Got: ${offset}`);
+    if (offset + requiredBytes > bufferSize) {
+        throw new Error(`Buffer too small for ${operation}. Required: ${requiredBytes} bytes at offset ${offset}, but buffer is only ${bufferSize} bytes.`);
+    }
+    if (offset % 4 !== 0) {
+        throw new Error(`Indirect buffer offset must be a multiple of 4. Got: ${offset}`);
+    }
 }
-function resolveIndirectOffset(indirectBuffer, start, requiredSize, operation) {
-	if (isGPUBuffer(indirectBuffer)) {
-		const offset$1 = typeof start === "number" ? start : start?.offset ?? 0;
-		validateIndirectBufferSize(indirectBuffer.size, offset$1, requiredSize, operation);
-		return offset$1;
-	}
-	const { offset, contiguous } = start ? typeof start === "number" ? {
-		offset: start,
-		contiguous: requiredSize
-	} : start : memoryLayoutOf(indirectBuffer.dataType);
-	validateIndirectBufferSize(sizeOf(indirectBuffer.dataType), offset, requiredSize, operation);
-	if (contiguous < requiredSize) console.warn(`${operation}: Starting at offset ${offset}, only ${contiguous} contiguous bytes are available before padding. '${operation}' requires ${requiredSize} bytes (${IndirectOperationToRequiredData[operation]}). Reading across padding may result in undefined behavior.`);
-	return offset;
+export function resolveIndirectOffset(indirectBuffer, start, requiredSize, operation) {
+    if (isGPUBuffer(indirectBuffer)) {
+        const offset = typeof start === 'number' ? start : (start?.offset ?? 0);
+        validateIndirectBufferSize(indirectBuffer.size, offset, requiredSize, operation);
+        return offset;
+    }
+    const offsetInfo = start
+        ? typeof start === 'number'
+            ? { offset: start, contiguous: requiredSize }
+            : start
+        : memoryLayoutOf(indirectBuffer.dataType);
+    const { offset, contiguous } = offsetInfo;
+    validateIndirectBufferSize(sizeOf(indirectBuffer.dataType), offset, requiredSize, operation);
+    if (contiguous < requiredSize) {
+        logger.warn('suspicious', `${operation}: Starting at offset ${offset}, only ${contiguous} contiguous bytes are available before padding. '${operation}' requires ${requiredSize} bytes (${IndirectOperationToRequiredData[operation]}). Reading across padding may result in undefined behavior.`);
+    }
+    return offset;
 }
-
-//#endregion
-export { resolveIndirectOffset };

package/core/pipeline/priors.d.ts

@@ -0,0 +1 @@
+export declare function nonTransferablePriorsOf(priors: object): string[];

package/core/pipeline/priors.js

@@ -0,0 +1,12 @@
+// GPU objects like query sets cross runtimes as shareable host objects, performanceCallback crosses only if it is a worklet
+const TRANSFERABLE_PRIORS = new Set([
+    'bindGroupLayoutMap',
+    'vertexLayoutMap',
+    'indexBuffer',
+    'stencilReference',
+    'timestampWrites',
+    'performanceCallback',
+]);
+export function nonTransferablePriorsOf(priors) {
+    return Object.keys(priors).filter((key) => !TRANSFERABLE_PRIORS.has(key) && priors[key] !== undefined);
+}