typegpu 0.12.4 → 0.12.6

package/bin.mjs

@@ -1,79 +1,51 @@
 #!/usr/bin/env node
-import { spawn } from 'node:child_process';
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
 import pkg from './package.json' with { type: 'json' };
 
-/**
- * Used to extract the version of `typegpu` that was used to
- * trigger the CLI, which then allows us to download the latest
- * version matching the major and minor of the `typegpu` package.
- */
-const versionPattern = /^(\d+)\.(\d+)\.(\d+)/;
-
-const result = versionPattern.exec(pkg.version);
-const [_, major, minor] = result;
+const [major, minor] = pkg.version.split('.');
+const semver = `^${major}.${minor}.0`;
 
-if (major === undefined || minor === undefined) {
-  throw new Error(`TypeGPU version doesn't match the expected major.minor.patch format`);
+const windows = process.platform === 'win32';
+const npm = windows ? 'npm.cmd' : 'npm';
+const npx = windows ? 'npx.cmd' : 'npx';
+const execFileAsync = promisify(execFile);
+
+/** True only when the registry confirms no `@typegpu/cli` satisfies `semver` */
+async function noMatchingCli() {
+  const args = ['view', `@typegpu/cli@${semver}`, 'version', '--json'];
+  try {
+    const { stdout } = await execFileAsync(npm, args, { shell: windows, timeout: 3_000 });
+    return ['', '[]'].includes(stdout.trim());
+  } catch (err) {
+    return /E404|ETARGET/.test(err.stderr ?? '');
+  }
 }
 
-/**
- * Targeting the latest version with the same major and minor as `typegpu`
- */
-const semver = `^${major}.${minor}.0`;
-
-/**
- * @returns {Promise<number | undefined>}
- */
-function asyncSpawn(...args) {
+/** Resolves with the child's exit code, re-raising a fatal signal on this process */
+function run(command, args) {
   return new Promise((resolve, reject) => {
-    const child = spawn(...args);
-
-    child.on('exit', (code, signal) => {
-      if (signal) {
-        process.kill(process.pid, signal);
-        process.exit(0);
-        return;
-      }
-
-      resolve(code);
-    });
-
-    child.on('error', (err) => {
-      reject(err);
-    });
+    spawn(command, args, { stdio: 'inherit', shell: windows })
+      .on('error', reject)
+      .on('exit', (code, signal) => {
+        if (signal) {
+          process.kill(process.pid, signal);
+        } else {
+          resolve(code ?? 1);
+        }
+      });
   });
 }
 
-/**
- * @param {string} label
- */
-function failedToRunErrHandler(label) {
-  return (err) => {
-    console.error(`Failed to run '${label}':`, err);
-    process.exit(1);
-  };
+const fallback = await noMatchingCli();
+if (fallback) {
+  console.warn(`Couldn't find @typegpu/cli version matching ${semver}, falling back to latest...`);
 }
+const spec = fallback ? '@typegpu/cli@latest' : `@typegpu/cli@${semver}`;
 
-(async () => {
-  const windows = process.platform === 'win32';
-  const npxCommand = windows ? 'npx.cmd' : 'npx';
-
-  const code = await asyncSpawn(npxCommand, [`@typegpu/cli@${semver}`, ...process.argv.slice(2)], {
-    stdio: 'inherit',
-    shell: windows, // needs to be ran through the shell on Windows
-  }).catch(failedToRunErrHandler(`npx @typegpu/cli@${semver}`));
-
-  if (code !== 0) {
-    console.warn(
-      `Couldn't find @typegpu/cli version matching ${semver}, falling back to latest...`,
-    );
-    // Fallback to latest
-    const code = await asyncSpawn(npxCommand, [`@typegpu/cli@latest`, ...process.argv.slice(2)], {
-      stdio: 'inherit',
-      shell: windows, // needs to be ran through the shell on Windows
-    }).catch(failedToRunErrHandler('npx @typegpu/cli@latest'));
-    process.exit(code ?? 0);
-  }
-
-  process.exit(code ?? 0);
-})();
+try {
+  process.exit(await run(npx, [spec, ...process.argv.slice(2)]));
+} catch (err) {
+  console.error(`Failed to run 'npx ${spec}':`, err);
+  process.exit(2);
+}

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).
@@ -54,6 +68,11 @@ export interface TgpuComputePipeline extends TgpuNamable, SelfResolvable, Timeab
     with(encoder: TgpuCommandEncoder): this;
     with(encoder: GPUCommandEncoder): this;
     with(pass: GPUComputePassEncoder): this;
+    /**
+     * Applies a transform to this pipeline, letting packages hand out reusable
+     * configuration steps, e.g. `pipeline.pipe(cache.inject())`.
+     */
+    pipe<T>(transform: (pipeline: this) => T): T;
     dispatchWorkgroups(x: number, y?: number, z?: number): void;
     /**
      * Immediately resolves the pipeline, then awaits `device.createComputePipelineAsync()`.
@@ -88,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;
@@ -107,10 +128,12 @@ 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;
     with(pass: GPUComputePassEncoder): this;
+    pipe<T>(transform: (pipeline: this) => T): T;
     withPerformanceCallback(callback: (start: bigint, end: bigint) => void | Promise<void>): this;
     withTimestampWrites(options: {
         querySet: TgpuQuerySet<'timestamp'> | GPUQuerySet;