typegpu 0.12.5 → 0.12.6

package/common/index.d.ts

@@ -1,2 +1,3 @@
 export { fullScreenTriangle } from './fullScreenTriangle.ts';
+export { writeChannels } from './writeChannels.ts';
 export { writeSoA } from './writeSoA.ts';

package/common/index.js

@@ -1,3 +1,4 @@
 // NOTE: This is a barrel file, internal files should not import things from this file
 export { fullScreenTriangle } from "./fullScreenTriangle.js";
+export { writeChannels } from "./writeChannels.js";
 export { writeSoA } from "./writeSoA.js";

package/common/writeChannels.d.ts

@@ -0,0 +1,31 @@
+import type { TgpuTexture } from '../core/texture/texture.ts';
+import { type TextureChannel, type TextureWriteOptions } from '../core/texture/textureWrite.ts';
+import type { RenderFlag } from '../core/texture/usageExtension.ts';
+export type TextureChannelSource = {
+    source: GPUCopyExternalImageSource;
+    from: TextureChannel;
+};
+export type TextureChannels = {
+    [Channel in TextureChannel]?: TextureChannelSource | undefined;
+};
+/**
+ * Writes image sources into individual channels of `texture`. Each entry
+ * writes a single channel, with `from` selecting which channel of the
+ * source to read. Omitted channels are left untouched.
+ *
+ * Requires the `'render'` usage flag on the texture.
+ *
+ * @example
+ * ```ts
+ * common.writeChannels(material, {
+ *   r: { source: roughnessMap, from: 'r' },
+ *   g: { source: metalnessMap, from: 'r' },
+ *   a: { source: maskMap, from: 'r' },
+ * });
+ * ```
+ */
+export declare function writeChannels(texture: TgpuTexture & RenderFlag, channels: TextureChannels, options?: TextureWriteOptions): void;
+export declare namespace writeChannels {
+    type Channels = TextureChannels;
+    type Source = TextureChannelSource;
+}

package/common/writeChannels.js

@@ -0,0 +1,32 @@
+import { writeImages } from "../core/texture/textureUtils.js";
+import { resolveImageWrite, } from "../core/texture/textureWrite.js";
+import { $internal, $soul } from "../shared/symbols.js";
+/**
+ * Writes image sources into individual channels of `texture`. Each entry
+ * writes a single channel, with `from` selecting which channel of the
+ * source to read. Omitted channels are left untouched.
+ *
+ * Requires the `'render'` usage flag on the texture.
+ *
+ * @example
+ * ```ts
+ * common.writeChannels(material, {
+ *   r: { source: roughnessMap, from: 'r' },
+ *   g: { source: metalnessMap, from: 'r' },
+ *   a: { source: maskMap, from: 'r' },
+ * });
+ * ```
+ */
+export function writeChannels(texture, channels, options = {}) {
+    const writes = [];
+    for (const to of ['r', 'g', 'b', 'a']) {
+        const entry = channels[to];
+        if (entry) {
+            writes.push({
+                ...resolveImageWrite(texture.props, entry.source, options),
+                channel: { from: entry.from, to },
+            });
+        }
+    }
+    writeImages(texture[$soul].device, texture[$internal].materialize(), writes);
+}

package/core/commandEncoder/computePass.d.ts

@@ -1,8 +1,10 @@
 import type { PrimitiveOffsetInfo } from '../../data/offsetUtils.ts';
 import type { AnyWgslData } from '../../data/wgslTypes.ts';
+import type { InferInput } from '../../shared/repr.ts';
 import { $internal } from '../../shared/symbols.ts';
 import type { TgpuBindGroup, TgpuBindGroupLayout, TgpuLayoutEntry } from '../../tgpuBindGroupLayout.ts';
 import type { IndirectFlag, TgpuBuffer } from '../buffer/buffer.ts';
+import type { TgpuImmediateVar } from '../immediate/immediateVar.ts';
 import { ComputeDrawState } from '../pipeline/drawState.ts';
 import type { TgpuComputePipeline } from '../pipeline/computePipeline.ts';
 import type { ExperimentalTgpuRoot } from '../root/rootTypes.ts';
@@ -41,6 +43,17 @@ export interface TgpuComputePass {
     setBindGroup(bindGroup: TgpuBindGroup): void;
     /** Associates a bind group with the given layout */
     setBindGroup<Entries extends Record<string, TgpuLayoutEntry | null>>(bindGroupLayout: TgpuBindGroupLayout<Entries>, bindGroup: TgpuBindGroup<Entries> | GPUBindGroup): void;
+    /**
+     * Provides a value for the given immediate variable, used by subsequent dispatches.
+     * The value is captured (copied) at call time; mutating it afterwards has no
+     * effect until it is set again. Takes precedence over values held by the
+     * pipeline (`pipeline.with(immediate, value)`) and persists across pipeline
+     * switches until set again, like any other pass-level state.
+     *
+     * Passing an `ArrayBuffer` or typed array skips serialization entirely; the bytes
+     * are copied verbatim and the caller guarantees they match the schema's layout.
+     */
+    setImmediates<T extends AnyWgslData>(immediate: TgpuImmediateVar<T>, value: InferInput<T> | ArrayBuffer | ArrayBufferView): void;
     dispatchWorkgroups(x: number, y?: number, z?: number): void;
     /**
      * Dispatches compute workgroups using parameters read from a buffer.

package/core/commandEncoder/computePass.js

@@ -1,7 +1,7 @@
 import { $internal } from "../../shared/symbols.js";
 import { isGPUBuffer } from "../../types.js";
 import { DISPATCH_INDIRECT_SIZE, resolveIndirectOffset } from "../pipeline/pipelineUtils.js";
-import { ComputeDrawState, emitComputeDispatch, recordBindGroup, stampComputePipeline, } from "../pipeline/drawState.js";
+import { ComputeDrawState, emitComputeDispatch, recordBindGroup, selectPipeline, } from "../pipeline/drawState.js";
 import { unwrapTimestampWrites } from "./attachments.js";
 // --------------
 // Implementation
@@ -44,11 +44,14 @@ class TgpuComputePassImpl {
         emitComputeDispatch(this.#root, internals, pipeline, emit);
     }
     setPipeline(pipeline) {
-        stampComputePipeline(this[$internal].state, pipeline);
+        selectPipeline(this[$internal].state, pipeline);
     }
     setBindGroup(first, bindGroup) {
         recordBindGroup(this[$internal].state, first, bindGroup);
     }
+    setImmediates(immediate, value) {
+        this[$internal].state.immediates.set(immediate, value);
+    }
     dispatchWorkgroups(x, y, z) {
         this.#emit((rawPass) => rawPass.dispatchWorkgroups(x, y, z));
     }

package/core/commandEncoder/renderPass.d.ts

@@ -1,9 +1,11 @@
 import type { Disarray } from '../../data/dataTypes.ts';
 import type { PrimitiveOffsetInfo } from '../../data/offsetUtils.ts';
-import type { BaseData, WgslArray } from '../../data/wgslTypes.ts';
+import type { AnyWgslData, BaseData, WgslArray } from '../../data/wgslTypes.ts';
+import type { InferInput } from '../../shared/repr.ts';
 import { $internal } from '../../shared/symbols.ts';
 import type { TgpuBindGroup, TgpuBindGroupLayout, TgpuLayoutEntry } from '../../tgpuBindGroupLayout.ts';
 import type { IndexFlag, IndirectFlag, TgpuBuffer, VertexFlag } from '../buffer/buffer.ts';
+import type { TgpuImmediateVar } from '../immediate/immediateVar.ts';
 import { RenderDrawState } from '../pipeline/drawState.ts';
 import type { TgpuRenderPipeline } from '../pipeline/renderPipeline.ts';
 import { type TgpuQuerySet } from '../querySet/querySet.ts';
@@ -58,6 +60,17 @@ export interface TgpuRenderCommands {
     setVertexBuffer<TData extends WgslArray | Disarray>(vertexLayout: TgpuVertexLayout<TData>, buffer: (TgpuBuffer<TData> & VertexFlag) | GPUBuffer, offset?: number, size?: number): void;
     /** Sets the current index buffer */
     setIndexBuffer<TData extends WgslArray | Disarray>(buffer: (TgpuBuffer<TData> & IndexFlag) | GPUBuffer, indexFormat: GPUIndexFormat, offset?: number, size?: number): void;
+    /**
+     * Provides a value for the given immediate variable, used by subsequent draw calls.
+     * The value is captured (copied) at call time; mutating it afterwards has no
+     * effect until it is set again. Takes precedence over values held by the
+     * pipeline (`pipeline.with(immediate, value)`) and persists across pipeline
+     * switches until set again, like any other pass-level state.
+     *
+     * Passing an `ArrayBuffer` or typed array skips serialization entirely; the bytes
+     * are copied verbatim and the caller guarantees they match the schema's layout.
+     */
+    setImmediates<T extends AnyWgslData>(immediate: TgpuImmediateVar<T>, value: InferInput<T> | ArrayBuffer | ArrayBufferView): void;
     draw(vertexCount: number, instanceCount?: number, firstVertex?: number, firstInstance?: number): void;
     drawIndexed(indexCount: number, instanceCount?: number, firstIndex?: number, baseVertex?: number, firstInstance?: number): void;
     /**
@@ -108,9 +121,10 @@ export interface TgpuRenderPass extends TgpuRenderCommands {
     endOcclusionQuery(): void;
     /**
      * Executes previously recorded {@link GPURenderBundle}s as part of this pass.
-     * As per the WebGPU spec, this resets the raw pass's pipeline, bind group
-     * and vertex/index buffer state. The state tracked by this typed pass is
-     * re-applied on the next draw.
+     * As per the WebGPU spec, this resets the raw pass's pipeline, bind group,
+     * vertex/index buffer and immediate data state. The state tracked by this
+     * typed pass (including values set via `setImmediates`) is re-applied on
+     * the next draw.
      */
     executeBundles(bundles: Iterable<GPURenderBundle>): void;
     /** Completes the recording of this render pass */

package/core/commandEncoder/renderPass.js

@@ -2,7 +2,7 @@ import { $internal } from "../../shared/symbols.js";
 import { isGPUBuffer } from "../../types.js";
 import { DRAW_INDEXED_INDIRECT_SIZE, DRAW_INDIRECT_SIZE, resolveIndirectOffset, } from "../pipeline/pipelineUtils.js";
 import { isTexture, isTextureView } from "../texture/texture.js";
-import { emitRenderDraw, recordBindGroup, RenderDrawState, stampRenderPipeline, } from "../pipeline/drawState.js";
+import { emitRenderDraw, recordBindGroup, RenderDrawState, selectPipeline, } from "../pipeline/drawState.js";
 import { isQuerySet } from "../querySet/querySet.js";
 import { unwrapAttachmentView, unwrapTimestampWrites, } from "./attachments.js";
 // --------------
@@ -125,7 +125,7 @@ class TgpuRenderCommandsImpl {
         emitRenderDraw(this.#root, internals, pipeline, usesIndexBuffer, emit);
     }
     setPipeline(pipeline) {
-        stampRenderPipeline(this[$internal].state, pipeline);
+        selectPipeline(this[$internal].state, pipeline);
     }
     setBindGroup(first, bindGroup) {
         recordBindGroup(this[$internal].state, first, bindGroup);
@@ -140,6 +140,9 @@ class TgpuRenderCommandsImpl {
         state.indexBuffer = { buffer, indexFormat, offsetBytes: offset, sizeBytes: size };
         state.version++;
     }
+    setImmediates(immediate, value) {
+        this[$internal].state.immediates.set(immediate, value);
+    }
     draw(vertexCount, instanceCount, firstVertex, firstInstance) {
         this.#emit(false, (rawPass) => rawPass.draw(vertexCount, instanceCount, firstVertex, firstInstance));
     }
@@ -189,6 +192,7 @@ class TgpuRenderPassImpl extends TgpuRenderCommandsImpl {
         const internals = this[$internal];
         internals.rawPass.executeBundles(bundles);
         internals.appliedVersion = undefined;
+        internals.state.immediates.invalidate();
     }
     end() {
         this[$internal].rawPass.end();

package/core/declare/tgpuDeclare.d.ts

@@ -1,3 +1,6 @@
+import { type ResolvedSnippet } from '../../data/snippet.ts';
+import { $internal, $resolve } from '../../shared/symbols.ts';
+import type { ResolutionCtx, SelfResolvable } from '../../types.ts';
 /**
  * Extra declaration that shall be included in final WGSL code,
  * when resolving objects that use it.
@@ -13,3 +16,11 @@ export interface TgpuDeclare {
  * It was developed to ensure full compatibility of TypeGPU programs with current and future versions of WGSL.
  */
 export declare function declare(declaration: string): TgpuDeclare;
+export declare class TgpuDeclareImpl implements TgpuDeclare, SelfResolvable {
+    #private;
+    readonly [$internal] = true;
+    constructor(declaration: string);
+    $uses(dependencyMap: Record<string, unknown>): this;
+    [$resolve](ctx: ResolutionCtx): ResolvedSnippet;
+    toString(): string;
+}

package/core/declare/tgpuDeclare.js

@@ -15,7 +15,7 @@ export function declare(declaration) {
 // --------------
 // Implementation
 // --------------
-class TgpuDeclareImpl {
+export class TgpuDeclareImpl {
     [$internal] = true;
     #externals;
     #declaration;

package/core/immediate/immediateVar.d.ts

@@ -0,0 +1,52 @@
+import { type BaseData, type MatData, type ScalarData, type VecData, type WgslStruct } from '../../data/wgslTypes.ts';
+import type { TgpuNamable } from '../../shared/meta.ts';
+import type { InferGPU, InferInput } from '../../shared/repr.ts';
+import type { TgpuSoul } from '../../shared/soul.ts';
+import { $gpuValueOf, $internal, $soul } from '../../shared/symbols.ts';
+export type ImmediateData = ScalarData | VecData | MatData | WgslStruct;
+export interface TgpuImmediateVarSoul<TDataType extends BaseData = BaseData> extends TgpuSoul<'immediate-var'> {
+    readonly dataType: TDataType;
+    readonly defaultValue: InferInput<TDataType> | undefined;
+}
+export interface TgpuImmediateVar<TDataType extends BaseData = BaseData> extends TgpuNamable {
+    readonly [$internal]: true;
+    readonly [$soul]: TgpuImmediateVarSoul<TDataType>;
+    readonly resourceType: 'immediate-var';
+    readonly dataType: TDataType;
+    readonly defaultValue: InferInput<TDataType> | undefined;
+    readonly [$gpuValueOf]: InferGPU<TDataType>;
+    readonly $: InferGPU<TDataType>;
+}
+/**
+ * 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 declare function immediateVar<TDataType extends ImmediateData>(dataType: TDataType, defaultValue?: InferInput<TDataType>): TgpuImmediateVar<TDataType>;
+export declare function isImmediateVar(value: unknown): value is TgpuImmediateVar;
+/**
+ * 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 declare function validateImmediateUsage(immediate: TgpuImmediateVar, root: {
+    readonly enabledWgslLanguageFeatures: ReadonlySet<string>;
+}): number;
+/** Captured bytes of an immediate value, immutable once created */
+export type ImmediateSnapshot = Uint8Array<ArrayBuffer>;
+export declare function createImmediateSnapshot(immediate: TgpuImmediateVar, value: unknown): ImmediateSnapshot;
+/** Captures pass overrides and tracks the last snapshot written to its encoder. */
+export declare class ImmediatePassState {
+    #private;
+    set(immediate: TgpuImmediateVar, value: unknown): void;
+    invalidate(): void;
+    /** Pass overrides take precedence over pipeline values and the variable's default. */
+    write(pass: GPURenderPassEncoder | GPUComputePassEncoder | GPURenderBundleEncoder, immediate: TgpuImmediateVar, pipelineSnapshots: ReadonlyMap<TgpuImmediateVar, ImmediateSnapshot> | undefined, deduplicate: boolean): void;
+}

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