typegpu 0.12.5 → 0.12.7

package/core/immediate/immediateVar.js

@@ -0,0 +1,149 @@
+import { writeToArrayBuffer } from "../../data/dataIO.js";
+import { undecorate } from "../../data/dataTypes.js";
+import { sizeOf } from "../../data/sizeOf.js";
+import { snip } from "../../data/snippet.js";
+import { isBool, isDecorated, isMat, isNumericSchema, isVec, isVecBool, isWgslStruct, } from "../../data/wgslTypes.js";
+import { IllegalVarAccessError, MissingImmediatesError } from "../../errors.js";
+import { isInsideTgpuFn } from "../../execMode.js";
+import { getName, setName } from "../../shared/meta.js";
+import { $gpuValueOf, $internal, $soul, isMarkedInternal } from "../../shared/symbols.js";
+import { makeDereferenceable } from "../../tgsl/makeDereferenceable.js";
+import { makeResolvable } from "../../tgsl/makeResolvable.js";
+/**
+ * Defines a variable in the 'immediate' address space, set from the CPU on a per-draw
+ * (or per-dispatch) basis without the overhead of a buffer.
+ *
+ * Only one immediate variable can be used in a single shader, and its size is limited
+ * by the device's `maxImmediateSize` limit. Requires the `immediate_address_space`
+ * WGSL language extension, check `root.enabledWgslLanguageFeatures` for support.
+ *
+ * @param dataType The schema of the held data's type. Cannot contain arrays, atomics or booleans.
+ * @param defaultValue The value used when no override is provided via `pipeline.with(immediate, value)`
+ *                     or `pass.setImmediates`. Captured (serialized) at creation time.
+ */
+export function immediateVar(dataType, defaultValue) {
+    assertValidImmediateSchema(dataType);
+    return new TgpuImmediateVarImpl(dataType, defaultValue);
+}
+export function isImmediateVar(value) {
+    return value?.resourceType === 'immediate-var' && isMarkedInternal(value);
+}
+// --------------
+// Implementation
+// --------------
+function assertValidImmediateSchema(schema, rootSchema = schema) {
+    if (isWgslStruct(schema)) {
+        for (const propType of Object.values(schema.propTypes)) {
+            assertValidImmediateSchema(undecorate(propType), rootSchema);
+        }
+        return;
+    }
+    if (isBool(schema) || isVecBool(schema)) {
+        throw new Error(`Invalid schema '${rootSchema.type}' for immediateVar: immediates cannot contain booleans (found '${schema.type}'), use u32 or i32 instead`);
+    }
+    if (isDecorated(schema)) {
+        throw new Error(`Invalid schema for immediateVar: immediates cannot be decorated types`);
+    }
+    if (!isNumericSchema(schema) && !isVec(schema) && !isMat(schema)) {
+        throw new Error(`Invalid schema '${rootSchema.type}' for immediateVar: immediates can only hold scalars, vectors, matrices and structs of those (found '${schema.type}')`);
+    }
+}
+/**
+ * Validates that the given immediate variable can be used with the given root.
+ * @returns The size of the immediate data in bytes, to be passed as
+ * `immediateSize` to `device.createPipelineLayout`.
+ */
+export function validateImmediateUsage(immediate, root) {
+    if (!root.enabledWgslLanguageFeatures.has('immediate_address_space')) {
+        throw new Error(`Immediate variable '${getName(immediate) ?? '<unnamed>'}' cannot be used, because the 'immediate_address_space' WGSL language extension is not supported in this environment. Check support with root.enabledWgslLanguageFeatures and fall back to a uniform buffer (e.g. via tgpu.accessor) when unavailable.`);
+    }
+    return sizeOf(immediate.dataType);
+}
+const defaultSnapshots = new WeakMap();
+export function createImmediateSnapshot(immediate, value) {
+    const bytes = new Uint8Array(sizeOf(immediate.dataType));
+    writeToArrayBuffer(bytes.buffer, immediate.dataType, value);
+    return bytes;
+}
+/** Captures pass overrides and tracks the last snapshot written to its encoder. */
+export class ImmediatePassState {
+    #snapshots = new Map();
+    #lastWritten;
+    set(immediate, value) {
+        this.#snapshots.set(immediate, createImmediateSnapshot(immediate, value));
+    }
+    invalidate() {
+        this.#lastWritten = undefined;
+    }
+    /** Pass overrides take precedence over pipeline values and the variable's default. */
+    write(pass, immediate, pipelineSnapshots, deduplicate) {
+        const snapshot = this.#snapshots.get(immediate) ??
+            pipelineSnapshots?.get(immediate) ??
+            defaultSnapshots.get(immediate);
+        if (snapshot === undefined) {
+            throw new MissingImmediatesError(getName(immediate));
+        }
+        if (deduplicate && this.#lastWritten === snapshot) {
+            return;
+        }
+        pass.setImmediates(0, snapshot.buffer);
+        this.#lastWritten = snapshot;
+    }
+}
+class TgpuImmediateVarImpl {
+    [$soul];
+    static {
+        const prototype = TgpuImmediateVarImpl.prototype;
+        prototype.resourceType = 'immediate-var';
+        makeDereferenceable(makeResolvable(prototype, {
+            asString() {
+                return `immediateVar:${getName(this) ?? '<unnamed>'}`;
+            },
+            resolve(ctx) {
+                ctx.registerImmediate(this);
+                const id = ctx.makeUniqueIdentifier(getName(this), 'global');
+                return ctx.gen.declareGlobalVar({
+                    scope: 'immediate',
+                    id,
+                    dataType: this[$soul].dataType,
+                    init: undefined,
+                });
+            },
+        }), {
+            codegenMode: {
+                getBaseSnippet(trackingProxy) {
+                    return snip(trackingProxy, this[$soul].dataType, 'immediate', 
+                    /* possibleSideEffects */ false);
+                },
+            },
+            normalMode: {
+                get() {
+                    throw new IllegalVarAccessError(isInsideTgpuFn()
+                        ? `Cannot access immediate variable '${getName(this) ?? '<unnamed>'}'. TypeGPU functions that depend on GPU resources need to be part of a compute dispatch or draw call`
+                        : 'Immediate variables are inaccessible during normal JS execution');
+                },
+            },
+        });
+    }
+    constructor(dataType, defaultValue) {
+        this[$soul] = {
+            type: 'immediate-var',
+            dataType,
+            defaultValue,
+            label: undefined,
+        };
+        if (defaultValue !== undefined) {
+            defaultSnapshots.set(this, createImmediateSnapshot(this, defaultValue));
+        }
+    }
+    get dataType() {
+        return this[$soul].dataType;
+    }
+    get defaultValue() {
+        return this[$soul].defaultValue;
+    }
+    $name(label) {
+        setName(this, label);
+        return this;
+    }
+}

package/core/pipeline/computePipeline.d.ts

@@ -3,11 +3,13 @@ import type { TgpuQuerySet } from '../querySet/querySet.ts';
 import { type ResolvedSnippet } from '../../data/snippet.ts';
 import type { AnyWgslData } from '../../data/wgslTypes.ts';
 import type { TgpuNamable } from '../../shared/meta.ts';
+import type { InferInput } from '../../shared/repr.ts';
 import type { TgpuDeviceOwningSoul } from '../../shared/soul.ts';
 import { $getNameForward, $internal, $resolve, $soul } from '../../shared/symbols.ts';
 import { type TgpuBindGroup, type TgpuBindGroupLayout, type TgpuLayoutEntry } from '../../tgpuBindGroupLayout.ts';
 import { type TgpuCommandEncoder } from '../commandEncoder/commandEncoder.ts';
 import { type TgpuComputePass } from '../commandEncoder/computePass.ts';
+import { type ImmediateSnapshot, type TgpuImmediateVar } from '../immediate/immediateVar.ts';
 import type { LogResources } from '../../tgsl/consoleLog/types.ts';
 import { type ResolutionCtx, type SelfResolvable } from '../../types.ts';
 import type { IORecord } from '../function/fnTypes.ts';
@@ -27,6 +29,8 @@ export interface ComputePipelineInternals {
 export interface TgpuComputePipelineSoul extends TgpuDeviceOwningSoul<'compute-pipeline', GPUComputePipeline> {
     usedBindGroupLayouts?: TgpuBindGroupLayout[] | undefined;
     bindGroups?: [TgpuBindGroupLayout, TgpuBindGroup | GPUBindGroup][] | undefined;
+    usedImmediate?: TgpuImmediateVar | undefined;
+    immediates?: [TgpuImmediateVar, ImmediateSnapshot][] | undefined;
     timestampWrites?: TimestampWritesPriors['timestampWrites'];
     performanceCallback?: TimestampWritesPriors['performanceCallback'];
     nonTransferablePriors?: string[] | undefined;
@@ -42,6 +46,16 @@ export interface TgpuComputePipeline extends TgpuNamable, SelfResolvable, Timeab
     with<Entries extends Record<string, TgpuLayoutEntry | null>>(bindGroupLayout: TgpuBindGroupLayout<Entries>, bindGroup: TgpuBindGroup<Entries>): this;
     with(bindGroupLayout: TgpuBindGroupLayout, bindGroup: GPUBindGroup): this;
     with(bindGroup: TgpuBindGroup): this;
+    /**
+     * Provides a value for the given immediate variable, applied on dispatch
+     * like the rest of the pipeline-held state and overridden by
+     * `pass.setImmediates`. The value is captured (copied) at call time;
+     * mutating it afterwards has no effect.
+     *
+     * Passing an `ArrayBuffer` or typed array skips serialization entirely; the bytes
+     * are copied verbatim and the caller guarantees they match the schema's layout.
+     */
+    with<T extends AnyWgslData>(immediate: TgpuImmediateVar<T>, value: InferInput<T> | ArrayBuffer | ArrayBufferView): this;
     /**
      * Directs subsequent dispatches into the given compute pass, letting multiple
      * pipelines share one pass (and one submission).
@@ -93,12 +107,14 @@ type TgpuComputePipelinePriors = {
     readonly pass?: TgpuComputePass | undefined;
     /** An encoder the pipeline records its own passes into, but does not submit */
     readonly encoder?: TgpuCommandEncoder | undefined;
+    readonly immediatesMap?: Map<TgpuImmediateVar, ImmediateSnapshot> | undefined;
 } & TimestampWritesPriors;
 type Memo = {
     pipeline: GPUComputePipeline;
     usedBindGroupLayouts: TgpuBindGroupLayout[];
     catchall: [number, TgpuBindGroup] | undefined;
     logResources: LogResources | undefined;
+    usedImmediate: TgpuImmediateVar | undefined;
 };
 declare class TgpuComputePipelineImpl implements TgpuComputePipeline {
     #private;
@@ -112,6 +128,7 @@ declare class TgpuComputePipelineImpl implements TgpuComputePipeline {
     with<Entries extends Record<string, TgpuLayoutEntry | null>>(bindGroupLayout: TgpuBindGroupLayout<Entries>, bindGroup: TgpuBindGroup<Entries>): this;
     with(bindGroupLayout: TgpuBindGroupLayout, bindGroup: GPUBindGroup): this;
     with(bindGroup: TgpuBindGroup): this;
+    with<T extends AnyWgslData>(immediate: TgpuImmediateVar<T>, value: InferInput<T> | ArrayBuffer | ArrayBufferView): this;
     with(pass: TgpuComputePass): this;
     with(encoder: TgpuCommandEncoder): this;
     with(encoder: GPUCommandEncoder): this;

package/core/pipeline/computePipeline.js

@@ -6,6 +6,7 @@ import { $getNameForward, $internal, $resolve, $soul } from "../../shared/symbol
 import { isBindGroup, isBindGroupLayout, } from "../../tgpuBindGroupLayout.js";
 import { INTERNAL_adoptCommandEncoder, INTERNAL_createCommandEncoder, } from "../commandEncoder/commandEncoder.js";
 import { INTERNAL_adoptComputePass } from "../commandEncoder/computePass.js";
+import { createImmediateSnapshot, isImmediateVar, validateImmediateUsage, } from "../immediate/immediateVar.js";
 import { emitComputeDispatch, finalizeOwnEncoder } from "./drawState.js";
 import { isGPUCommandEncoder, isGPUComputePassEncoder, isTgpuCommandEncoder, isTgpuComputePass, } from "./typeGuards.js";
 import { isGPUBuffer } from "../../types.js";
@@ -30,9 +31,11 @@ export function INTERNAL_restoreComputePipeline(soul, ctx) {
         // The catchall group is already one of `bindGroups`, keyed by the layout it was resolved with
         catchall: undefined,
         logResources: undefined,
+        usedImmediate: soul.usedImmediate,
     });
     const pipeline = new TgpuComputePipelineImpl(core, {
         bindGroupLayoutMap: new Map(soul.bindGroups),
+        immediatesMap: new Map(soul.immediates),
     });
     return restoreTimestampPriors(pipeline, soul);
 }
@@ -59,6 +62,8 @@ class TgpuComputePipelineImpl {
                     soul.raw = memo.pipeline;
                     soul.usedBindGroupLayouts = memo.usedBindGroupLayouts;
                     soul.bindGroups = collectBindGroupPairs(memo.usedBindGroupLayouts, memo.catchall, priors.bindGroupLayoutMap);
+                    soul.usedImmediate = memo.usedImmediate;
+                    soul.immediates = [...(priors.immediatesMap ?? [])];
                     soul.timestampWrites = priors.timestampWrites;
                     soul.performanceCallback = priors.performanceCallback;
                     soul.nonTransferablePriors = nonTransferablePriorsOf(priors);
@@ -78,7 +83,7 @@ class TgpuComputePipelineImpl {
         const { core, priors } = this[$internal];
         return new TgpuComputePipelineImpl(core, { ...priors, ...patch });
     }
-    with(first, bindGroup) {
+    with(first, resource) {
         const internals = this[$internal];
         if (isTgpuComputePass(first)) {
             return this.#withPriors({ pass: first, encoder: undefined });
@@ -98,10 +103,15 @@ class TgpuComputePipelineImpl {
                 encoder: INTERNAL_adoptCommandEncoder(internals.root, first),
             });
         }
+        if (isImmediateVar(first)) {
+            return this.#withPriors({
+                immediatesMap: new Map(internals.priors.immediatesMap).set(first, createImmediateSnapshot(first, resource)),
+            });
+        }
         if (isBindGroup(first) || isBindGroupLayout(first)) {
             const [layout, group] = isBindGroup(first)
                 ? [first.layout, first]
-                : [first, bindGroup];
+                : [first, resource];
             return this.#withPriors({
                 bindGroupLayoutMap: new Map([
                     ...(internals.priors.bindGroupLayoutMap ?? []),
@@ -220,19 +230,20 @@ class ComputePipelineCore {
         if (this.#initAsyncPromise === undefined) {
             // the pipeline did not start resolution & compilation
             const device = this.root.device;
-            const { resolutionResult, module } = this.resolveAndCreateShaderModule();
-            const { usedBindGroupLayouts, catchall, logResources } = resolutionResult;
+            const { resolutionResult, module, immediateSize } = this.resolveAndCreateShaderModule();
+            const { usedBindGroupLayouts, catchall, logResources, usedImmediate } = resolutionResult;
             this.#initAsyncPromise = device
                 .createComputePipelineAsync({
                 label: getName(this) ?? '<unnamed>',
                 layout: device.createPipelineLayout({
                     label: `${getName(this) ?? '<unnamed>'} - Pipeline Layout`,
                     bindGroupLayouts: usedBindGroupLayouts.map((l) => this.root.unwrap(l)),
+                    immediateSize,
                 }),
                 compute: { module },
             })
                 .then((pipeline) => {
-                this.#memo = { pipeline, usedBindGroupLayouts, catchall, logResources };
+                this.#memo = { pipeline, usedBindGroupLayouts, catchall, logResources, usedImmediate };
                 this.#performanceTracker.measureCompile(device);
             })
                 .finally(() => {
@@ -249,20 +260,22 @@ class ComputePipelineCore {
             throw new Error("'pipeline.initAsync()' was called and is not yet resolved.");
         }
         const device = this.root.device;
-        const { resolutionResult, module } = this.resolveAndCreateShaderModule();
-        const { usedBindGroupLayouts, catchall, logResources } = resolutionResult;
+        const { resolutionResult, module, immediateSize } = this.resolveAndCreateShaderModule();
+        const { usedBindGroupLayouts, catchall, logResources, usedImmediate } = resolutionResult;
         this.#memo = {
             pipeline: device.createComputePipeline({
                 label: getName(this) ?? '<unnamed>',
                 layout: device.createPipelineLayout({
                     label: `${getName(this) ?? '<unnamed>'} - Pipeline Layout`,
                     bindGroupLayouts: usedBindGroupLayouts.map((l) => this.root.unwrap(l)),
+                    immediateSize,
                 }),
                 compute: { module },
             }),
             usedBindGroupLayouts,
             catchall,
             logResources,
+            usedImmediate,
         };
         this.#performanceTracker.measureCompile(device);
     }
@@ -284,15 +297,16 @@ class ComputePipelineCore {
                 : undefined,
             root: this.root,
         }));
-        const { code, usedBindGroupLayouts, catchall } = resolutionResult;
+        const { code, usedBindGroupLayouts, catchall, usedImmediate } = resolutionResult;
         if (catchall !== undefined) {
             usedBindGroupLayouts[catchall[0]]?.$name(`${getName(this) ?? '<unnamed>'} - Automatic Bind Group & Layout`);
         }
         warnIfOverflow(usedBindGroupLayouts, device.limits);
+        const immediateSize = usedImmediate ? validateImmediateUsage(usedImmediate, this.root) : 0;
         const module = device.createShaderModule({
             label: `${getName(this) ?? '<unnamed>'} - Shader`,
             code,
         });
-        return { resolutionResult, module };
+        return { resolutionResult, module, immediateSize };
     }
 }

package/core/pipeline/connectAttachmentToShader.d.ts

@@ -1,4 +1,4 @@
-import { type BaseData } from '../../data/wgslTypes.ts';
 import type { ColorAttachment } from '../commandEncoder/attachments.ts';
+import type { ConnectedTarget } from './connectTargetsToShader.ts';
 import type { AnyFragmentColorAttachment } from './renderPipeline.ts';
-export declare function connectAttachmentToShader(fragmentOut: BaseData, attachment: AnyFragmentColorAttachment): ColorAttachment[];
+export declare function connectAttachmentToShader(connectedTargets: (ConnectedTarget | null)[] | undefined, attachment: AnyFragmentColorAttachment): (ColorAttachment | null)[];

package/core/pipeline/connectAttachmentToShader.js

@@ -1,29 +1,24 @@
-import { isBuiltin } from "../../data/attributes.js";
-import { isVoid, isWgslStruct } from "../../data/wgslTypes.js";
 function isColorAttachment(value) {
     return !!value?.view;
 }
-export function connectAttachmentToShader(fragmentOut, attachment) {
-    if (isVoid(fragmentOut) || isBuiltin(fragmentOut)) {
+export function connectAttachmentToShader(connectedTargets, attachment) {
+    if (!connectedTargets) {
         return [];
     }
-    if (isWgslStruct(fragmentOut)) {
-        const result = [];
-        for (const key of Object.keys(fragmentOut.propTypes)) {
-            const outputValue = fragmentOut.propTypes[key];
-            if (isBuiltin(outputValue)) {
-                continue;
-            }
-            const matching = attachment[key];
-            if (!matching) {
-                throw new Error(`A color attachment by the name of '${key}' was not provided to the shader.`);
+    return connectedTargets.map((target) => {
+        if (!target) {
+            return null;
+        }
+        if (target.key === undefined) {
+            if (!isColorAttachment(attachment)) {
+                throw new Error('Expected a single color attachment, not a record.');
             }
-            result.push(matching);
+            return attachment;
         }
-        return result;
-    }
-    if (!isColorAttachment(attachment)) {
-        throw new Error('Expected a single color attachment, not a record.');
-    }
-    return [attachment];
+        const matching = attachment[target.key];
+        if (!matching) {
+            throw new Error(`A color attachment by the name of '${target.key}' was not provided to the shader.`);
+        }
+        return matching;
+    });
 }

package/core/pipeline/connectTargetsToShader.d.ts

@@ -1,3 +1,7 @@
 import { type BaseData } from '../../data/wgslTypes.ts';
 import type { AnyFragmentTargets } from './renderPipeline.ts';
-export declare function connectTargetsToShader(fragmentOut: BaseData, targets: AnyFragmentTargets): (GPUColorTargetState | null)[];
+export interface ConnectedTarget {
+    key: string | undefined;
+    target: GPUColorTargetState;
+}
+export declare function connectTargetsToShader(fragmentOut: BaseData, targets: AnyFragmentTargets): (ConnectedTarget | null)[];

package/core/pipeline/connectTargetsToShader.js

@@ -1,31 +1,36 @@
 import { isBuiltin } from "../../data/attributes.js";
 import { isVoid, isWgslStruct } from "../../data/wgslTypes.js";
+import { invariant } from "../../errors.js";
+import { getCustomLocation } from "../../data/dataTypes.js";
 export function connectTargetsToShader(fragmentOut, targets) {
-    let presentationFormat;
     if (isVoid(fragmentOut) || isBuiltin(fragmentOut)) {
         return [];
     }
+    const result = [];
+    function putInResult(index, key, target) {
+        while (index > result.length) {
+            result.push(null);
+        }
+        result[index] = { key, target };
+    }
     if (isWgslStruct(fragmentOut)) {
-        const result = [];
-        for (const key of Object.keys(fragmentOut.propTypes)) {
-            const outputValue = fragmentOut.propTypes[key];
-            if (isBuiltin(outputValue)) {
-                continue;
-            }
-            const matchingTarget = targets[key];
-            result.push({
+        const varyings = Object.entries(fragmentOut.propTypes).filter(([, value]) => !isBuiltin(value));
+        for (const [key, outputValue] of varyings) {
+            const matchingTarget = targets?.[key];
+            const location = getCustomLocation(outputValue);
+            invariant(location !== undefined, `'withLocations' failed or was not called.`);
+            putInResult(location, key, {
                 ...matchingTarget,
-                format: matchingTarget?.format ??
-                    (presentationFormat ??= navigator.gpu.getPreferredCanvasFormat()),
+                format: matchingTarget?.format ?? navigator.gpu.getPreferredCanvasFormat(),
             });
         }
-        return result;
     }
-    const singleTarget = targets;
-    return [
-        {
+    else {
+        const singleTarget = targets;
+        putInResult(getCustomLocation(fragmentOut) ?? 0, undefined, {
             ...singleTarget,
-            format: singleTarget?.format ?? (presentationFormat ??= navigator.gpu.getPreferredCanvasFormat()),
-        },
-    ];
+            format: singleTarget?.format ?? navigator.gpu.getPreferredCanvasFormat(),
+        });
+    }
+    return result;
 }

package/core/pipeline/drawState.d.ts

@@ -5,6 +5,7 @@ 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 { ImmediatePassState } from '../immediate/immediateVar.ts';
 import type { ExperimentalTgpuRoot } from '../root/rootTypes.ts';
 import type { TgpuVertexLayout } from '../vertexLayout/vertexLayout.ts';
 import type { TgpuComputePipeline } from './computePipeline.ts';
@@ -24,6 +25,7 @@ export interface IndexBufferEntry {
 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>;
+    readonly immediates: ImmediatePassState;
     currentPipeline: TgpuRenderPipeline | undefined;
     indexBuffer: IndexBufferEntry | undefined;
     stencilReference: GPUStencilValue | undefined;
@@ -35,15 +37,17 @@ export declare class RenderDrawState {
 }
 export declare class ComputeDrawState {
     readonly bindGroups: Map<TgpuBindGroupLayout<Record<string, import("../../tgpuBindGroupLayout.ts").TgpuLayoutEntry | null>>, TgpuBindGroup | GPUBindGroup>;
+    readonly immediates: ImmediatePassState;
     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;
+/** Makes the pipeline current; its held state is resolved at draw time, below what the pass holds */
+export declare function selectPipeline<TPipeline>(state: {
+    currentPipeline: TPipeline | undefined;
+    version: number;
+}, pipeline: TPipeline): 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;

package/core/pipeline/drawState.js

@@ -4,10 +4,12 @@ import { logger } from "../../tgpuLogger.js";
 import { isBindGroup, } from "../../tgpuBindGroupLayout.js";
 import { logDataFromGPU } from "../../tgsl/consoleLog/deserializers.js";
 import { isBuffer } from "../../types.js";
+import { ImmediatePassState } from "../immediate/immediateVar.js";
 import { queueTimestampResolve } from "./timeable.js";
 export class RenderDrawState {
     bindGroups = new Map();
     vertexBuffers = new Map();
+    immediates = new ImmediatePassState();
     currentPipeline;
     indexBuffer;
     stencilReference;
@@ -19,6 +21,7 @@ export class RenderDrawState {
 }
 export class ComputeDrawState {
     bindGroups = new Map();
+    immediates = new ImmediatePassState();
     currentPipeline;
     version = 0;
     rawAccessed = false;
@@ -32,38 +35,12 @@ export function recordBindGroup(state, 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);
-        }
+/** Makes the pipeline current; its held state is resolved at draw time, below what the pass holds */
+export function selectPipeline(state, pipeline) {
+    if (state.currentPipeline !== pipeline) {
+        state.currentPipeline = pipeline;
+        state.version++;
     }
-    state.version++;
 }
 function applyIndexBuffer(encoder, root, entry) {
     const { buffer, indexFormat, offsetBytes, sizeBytes } = entry;
@@ -117,25 +94,36 @@ function applyVertexBuffers(encoder, root, usedVertexLayouts, resolveVertexBuffe
     }
 }
 function applyRenderPipelineState(encoder, root, pipeline, passState) {
-    const memo = pipeline[$internal].core.unwrap();
+    const { core, priors } = pipeline[$internal];
+    const memo = 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;
+    applyBindGroups(encoder, root, memo.usedBindGroupLayouts, memo.catchall, (layout) => passState.bindGroups.get(layout) ?? priors.bindGroupLayoutMap?.get(layout));
+    applyVertexBuffers(encoder, root, memo.usedVertexLayouts, (vertexLayout) => {
+        const passEntry = passState.vertexBuffers.get(vertexLayout);
+        if (passEntry !== undefined) {
+            return passEntry;
+        }
+        const buffer = priors.vertexLayoutMap?.get(vertexLayout);
+        return buffer !== undefined ? { buffer } : undefined;
+    });
+    const indexBuffer = passState.indexBuffer ?? priors.indexBuffer;
+    if (indexBuffer !== undefined) {
+        applyIndexBuffer(encoder, root, indexBuffer);
+    }
+    if (typeof encoder.setStencilReference === 'function') {
+        const stencilReference = passState.stencilReference ?? priors.stencilReference ?? 0;
+        const dirty = passState.rawAccessed || stencilReference !== passState.appliedStencilReference;
+        if (dirty) {
+            encoder.setStencilReference(stencilReference);
+            passState.appliedStencilReference = stencilReference;
         }
     }
 }
 function applyComputePipelineState(encoder, root, pipeline, passState) {
-    const memo = pipeline[$internal].core.unwrap();
+    const { core, priors } = pipeline[$internal];
+    const memo = core.unwrap();
     encoder.setPipeline(memo.pipeline);
-    applyBindGroups(encoder, root, memo.usedBindGroupLayouts, memo.catchall, (layout) => passState.bindGroups.get(layout));
+    applyBindGroups(encoder, root, memo.usedBindGroupLayouts, memo.catchall, (layout) => passState.bindGroups.get(layout) ?? priors.bindGroupLayoutMap?.get(layout));
 }
 export function requireIndexBuffer(indexBuffer) {
     if (!indexBuffer) {
@@ -191,11 +179,9 @@ function reportIgnoredPriors(core, owner, hasTimestampWrites, logResources, pass
 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);
-    }
+    selectPipeline(state, pipeline);
     if (usesIndexBuffer) {
-        requireIndexBuffer(state.indexBuffer);
+        requireIndexBuffer(state.indexBuffer ?? priors.indexBuffer);
     }
     const memo = core.unwrap();
     if (!ownsPass) {
@@ -205,14 +191,15 @@ export function emitRenderDraw(root, passInternals, pipeline, usesIndexBuffer, e
         applyRenderPipelineState(rawPass, root, pipeline, state);
         passInternals.appliedVersion = state.version;
     }
+    if (memo.usedImmediate !== undefined) {
+        state.immediates.write(rawPass, memo.usedImmediate, priors.immediatesMap, !state.rawAccessed);
+    }
     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);
-    }
+    selectPipeline(state, pipeline);
     const memo = core.unwrap();
     if (!ownsPass) {
         reportIgnoredPriors(core, passInternals.owner, !!priors.timestampWrites, memo.logResources, 'compute');
@@ -221,5 +208,8 @@ export function emitComputeDispatch(root, passInternals, pipeline, emit, ownsPas
         applyComputePipelineState(rawPass, root, pipeline, state);
         passInternals.appliedVersion = state.version;
     }
+    if (memo.usedImmediate !== undefined) {
+        state.immediates.write(rawPass, memo.usedImmediate, priors.immediatesMap, !state.rawAccessed);
+    }
     emit(rawPass);
 }

package/core/pipeline/priors.js

@@ -1,6 +1,7 @@
 // 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',
+    'immediatesMap',
     'vertexLayoutMap',
     'indexBuffer',
     'stencilReference',