typegpu 0.12.4 → 0.12.6

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 ?? []),
@@ -111,6 +121,9 @@ class TgpuComputePipelineImpl {
         }
         throw new Error('Unsupported value passed into .with()');
     }
+    pipe(transform) {
+        return transform(this);
+    }
     withPerformanceCallback(callback) {
         const internals = this[$internal];
         if (internals.priors.timestampWrites) {
@@ -217,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(() => {
@@ -246,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);
     }
@@ -281,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/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',

package/core/pipeline/renderPipeline.d.ts

@@ -3,8 +3,9 @@ import type { IndexFlag, IndirectFlag, TgpuBuffer, VertexFlag } from '../buffer/
 import type { TgpuQuerySet } from '../querySet/querySet.ts';
 import { type Disarray, type UndecorateRecord } from '../../data/dataTypes.ts';
 import { type ResolvedSnippet } from '../../data/snippet.ts';
-import { type AnyVecInstance, type BaseData, type U16, type U32, type v4f, Void, type WgslArray, type WgslStruct } from '../../data/wgslTypes.ts';
+import { type AnyVecInstance, type AnyWgslData, type BaseData, type U16, type U32, type v4f, Void, type WgslArray, type WgslStruct } 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 { AnyVertexAttribs } from '../../shared/vertexFormat.ts';
@@ -19,6 +20,7 @@ import type { TgpuSlot } from '../slot/slotTypes.ts';
 import { type TgpuVertexLayout } from '../vertexLayout/vertexLayout.ts';
 import { type TgpuCommandEncoder } from '../commandEncoder/commandEncoder.ts';
 import type { ColorAttachment, DepthStencilAttachment } from '../commandEncoder/attachments.ts';
+import { type ImmediateSnapshot, type TgpuImmediateVar } from '../immediate/immediateVar.ts';
 import { type TgpuRenderCommands } from '../commandEncoder/renderPass.ts';
 import { type Timeable, type TimestampWritesPriors } from './timeable.ts';
 import { type PrimitiveOffsetInfo } from '../../data/offsetUtils.ts';
@@ -34,6 +36,8 @@ export interface TgpuRenderPipelineSoul extends TgpuDeviceOwningSoul<'render-pip
     usedVertexLayouts?: TgpuVertexLayout[] | undefined;
     fragmentOut?: BaseData | undefined;
     bindGroups?: [TgpuBindGroupLayout, TgpuBindGroup | GPUBindGroup][] | undefined;
+    usedImmediate?: TgpuImmediateVar | undefined;
+    immediates?: [TgpuImmediateVar, ImmediateSnapshot][] | undefined;
     vertexBuffers?: [TgpuVertexLayout, (TgpuBuffer<BaseData> & VertexFlag) | GPUBuffer][] | undefined;
     indexBuffer?: {
         buffer: (TgpuBuffer<BaseData> & IndexFlag) | GPUBuffer;
@@ -76,6 +80,16 @@ export interface TgpuRenderPipeline<in Targets = never> extends TgpuNamable, Sel
     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 draw 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 draw calls into the given render pass or render bundle
      * encoder, letting multiple pipelines share one pass (and one submission).
@@ -89,6 +103,11 @@ export interface TgpuRenderPipeline<in Targets = never> extends TgpuNamable, Sel
     with(encoder: GPUCommandEncoder): this;
     with(pass: GPURenderPassEncoder): this;
     with(bundleEncoder: GPURenderBundleEncoder): this;
+    /**
+     * Applies a transform to this pipeline, letting packages hand out reusable
+     * configuration steps, e.g. `pipeline.pipe(mesh.inject())`.
+     */
+    pipe<T>(transform: (pipeline: this) => T): T;
     /**
      * Attaches texture views to the pipeline's targets (outputs).
      *
@@ -194,6 +213,7 @@ type TgpuRenderPipelinePriors = {
     readonly pass?: TgpuRenderCommands | 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: GPURenderPipeline;
@@ -202,6 +222,7 @@ type Memo = {
     logResources: LogResources | undefined;
     usedVertexLayouts: TgpuVertexLayout[];
     fragmentOut: BaseData | undefined;
+    usedImmediate: TgpuImmediateVar | undefined;
 };
 declare class TgpuRenderPipelineImpl implements TgpuRenderPipeline {
     #private;
@@ -218,11 +239,13 @@ declare class TgpuRenderPipelineImpl implements TgpuRenderPipeline {
     with(bindGroupLayout: TgpuBindGroupLayout, bindGroup: GPUBindGroup): this;
     with(bindGroup: TgpuBindGroup): this;
     with<TData extends WgslArray | Disarray>(vertexLayout: TgpuVertexLayout<TData>, buffer: GPUBuffer): this;
+    with<T extends AnyWgslData>(immediate: TgpuImmediateVar<T>, value: InferInput<T> | ArrayBuffer | ArrayBufferView): this;
     with(pass: TgpuRenderCommands): this;
     with(encoder: TgpuCommandEncoder): this;
     with(encoder: GPUCommandEncoder): this;
     with(pass: GPURenderPassEncoder): this;
     with(bundleEncoder: GPURenderBundleEncoder): this;
+    pipe<T>(transform: (pipeline: this) => T): T;
     withPerformanceCallback(callback: (start: bigint, end: bigint) => void | Promise<void>): this;
     withTimestampWrites(options: {
         querySet: TgpuQuerySet<'timestamp'> | GPUQuerySet;

package/core/pipeline/renderPipeline.js

@@ -18,6 +18,7 @@ import { isVertexLayout } from "../vertexLayout/vertexLayout.js";
 import { connectAttachmentToShader } from "./connectAttachmentToShader.js";
 import { connectTargetsToShader } from "./connectTargetsToShader.js";
 import { INTERNAL_adoptCommandEncoder, INTERNAL_createCommandEncoder, } from "../commandEncoder/commandEncoder.js";
+import { createImmediateSnapshot, isImmediateVar, validateImmediateUsage, } from "../immediate/immediateVar.js";
 import { INTERNAL_adoptRenderCommands, } from "../commandEncoder/renderPass.js";
 import { emitRenderDraw, finalizeOwnEncoder, requireIndexBuffer } from "./drawState.js";
 import { isGPUCommandEncoder, isGPURenderBundleEncoder, isGPURenderPassEncoder, isTgpuCommandEncoder, isTgpuRenderCommands, } from "./typeGuards.js";
@@ -42,9 +43,11 @@ export function INTERNAL_restoreRenderPipeline(soul, ctx) {
         logResources: undefined,
         usedVertexLayouts: soul.usedVertexLayouts ?? [],
         fragmentOut: soul.fragmentOut,
+        usedImmediate: soul.usedImmediate,
     });
     const pipeline = new TgpuRenderPipelineImpl(core, {
         bindGroupLayoutMap: new Map(soul.bindGroups),
+        immediatesMap: new Map(soul.immediates),
         vertexLayoutMap: new Map(soul.vertexBuffers),
         indexBuffer: soul.indexBuffer,
         stencilReference: soul.stencilReference,
@@ -76,6 +79,8 @@ class TgpuRenderPipelineImpl {
                     soul.usedVertexLayouts = memo.usedVertexLayouts;
                     soul.fragmentOut = memo.fragmentOut;
                     soul.bindGroups = collectBindGroupPairs(memo.usedBindGroupLayouts, memo.catchall, priors.bindGroupLayoutMap);
+                    soul.usedImmediate = memo.usedImmediate;
+                    soul.immediates = [...(priors.immediatesMap ?? [])];
                     soul.vertexBuffers = collectVertexBufferPairs(memo.usedVertexLayouts, priors.vertexLayoutMap);
                     soul.indexBuffer = priors.indexBuffer;
                     soul.stencilReference = priors.stencilReference;
@@ -141,8 +146,16 @@ class TgpuRenderPipelineImpl {
                 ]),
             });
         }
+        if (isImmediateVar(first)) {
+            return this.#withPriors({
+                immediatesMap: new Map(internals.priors.immediatesMap).set(first, createImmediateSnapshot(first, resource)),
+            });
+        }
         throw new Error('Unsupported value passed into .with()');
     }
+    pipe(transform) {
+        return transform(this);
+    }
     withPerformanceCallback(callback) {
         const internals = this[$internal];
         if (internals.priors.timestampWrites) {
@@ -344,6 +357,7 @@ class RenderPipelineCore {
                     logResources,
                     usedVertexLayouts: connectedAttribs.usedVertexLayouts,
                     fragmentOut,
+                    usedImmediate: resolutionResult.usedImmediate,
                 };
                 this.#performanceTracker.measureCompile(device);
             })
@@ -370,6 +384,7 @@ class RenderPipelineCore {
             logResources,
             usedVertexLayouts: connectedAttribs.usedVertexLayouts,
             fragmentOut,
+            usedImmediate: resolutionResult.usedImmediate,
         };
         this.#performanceTracker.measureCompile(device);
     }
@@ -393,11 +408,12 @@ class RenderPipelineCore {
             shaderGenerator: root.shaderGeneratorClass ? new root.shaderGeneratorClass() : undefined,
             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, root) : 0;
         const module = device.createShaderModule({
             label: `${getName(this) ?? '<unnamed>'} - Shader`,
             code,
@@ -414,6 +430,7 @@ class RenderPipelineCore {
             layout: device.createPipelineLayout({
                 label: `${getName(this) ?? '<unnamed>'} - Pipeline Layout`,
                 bindGroupLayouts: usedBindGroupLayouts.map((l) => root.unwrap(l)),
+                immediateSize,
             }),
             vertex: {
                 module,

package/core/root/init.js

@@ -214,6 +214,9 @@ class TgpuRootImpl extends WithBindingImpl {
     get minify() {
         return this[$soul].minify;
     }
+    get enabledWgslLanguageFeatures() {
+        return navigator.gpu?.wgslLanguageFeatures ?? new Set();
+    }
     createBuffer(typeSchema, initialOrBuffer) {
         return INTERNAL_createBuffer(this, typeSchema, initialOrBuffer);
     }

package/core/root/rootTypes.d.ts

@@ -418,6 +418,17 @@ export interface TgpuRoot extends Unwrapper, WithBinding {
      * @returns A set of strings representing the enabled features.
      */
     get enabledFeatures(): ReadonlySet<GPUFeatureName>;
+    /**
+     * Retrieves a read-only list of WGSL language extensions supported in the
+     * current environment (`navigator.gpu.wgslLanguageFeatures`).
+     * Returns an empty set when WebGPU is unavailable.
+     *
+     * @example
+     * ```ts
+     * const canUseImmediates = root.enabledWgslLanguageFeatures.has('immediate_address_space');
+     * ```
+     */
+    get enabledWgslLanguageFeatures(): ReadonlySet<string>;
     /**
      * Destroys all underlying resources (i.e. buffers...) created through this root object.
      * If the object is created via `tgpu.init` instead of `tgpu.initFromDevice`,

package/core/slot/slotTypes.d.ts

@@ -7,6 +7,7 @@ import { $gpuValueOf, $internal, $providing, $soul } from '../../shared/symbols.
 import type { UnwrapRuntimeConstructor } from '../../tgpuBindGroupLayout.ts';
 import type { TgpuBufferBinding } from '../buffer/bufferBinding.ts';
 import type { TgpuConst } from '../constant/tgpuConstant.ts';
+import type { TgpuImmediateVar } from '../immediate/immediateVar.ts';
 import type { Withable } from '../root/rootTypes.ts';
 import type { TgpuTextureView } from '../texture/texture.ts';
 import type { TgpuVar, VariableScope } from '../variable/tgpuVariable.ts';
@@ -51,7 +52,7 @@ export interface TgpuAccessor<T extends BaseData = BaseData> extends TgpuNamable
     readonly $: InferGPU<T>;
     toString(): string;
 }
-type DataAccessorIn<T extends BaseData> = (() => DataAccessorIn<T>) | TgpuBufferBinding<T> | TgpuVar<VariableScope, T> | TgpuConst<T> | Infer<T>;
+type DataAccessorIn<T extends BaseData> = (() => DataAccessorIn<T>) | TgpuBufferBinding<T> | TgpuVar<VariableScope, T> | TgpuConst<T> | TgpuImmediateVar<T> | Infer<T>;
 type TextureAccessorIn<T extends WgslTexture | WgslStorageTexture> = (() => TextureAccessorIn<T>) | Infer<T> | TgpuTextureView<T>;
 export declare namespace TgpuAccessor {
     type In<T extends BaseData | ((count: number) => BaseData)> = UnwrapRuntimeConstructor<T> extends WgslTexture | WgslStorageTexture ? TextureAccessorIn<UnwrapRuntimeConstructor<T>> : DataAccessorIn<UnwrapRuntimeConstructor<T>>;

package/core/texture/texture.d.ts

@@ -13,6 +13,7 @@ import type { ResolutionCtx, SelfResolvable } from '../../types.ts';
 import type { ExperimentalTgpuRoot } from '../root/rootTypes.ts';
 import type { TextureProps } from './textureProps.ts';
 import type { AllowedUsages, LiteralToExtensionMap, RenderFlag, SampledFlag } from './usageExtension.ts';
+import { type TextureBlobWriteOptions, type TextureCopyOptions, type TextureRawWriteOptions, type TextureWriteOptions } from './textureWrite.ts';
 export type TextureInternals = {
     root: ExperimentalTgpuRoot;
     materialize(): GPUTexture;
@@ -38,17 +39,7 @@ type TextureViewInternals = {
     readonly aspect?: GPUTextureAspect | undefined;
 };
 export type TexelData = Vec4u | Vec4i | Vec4f;
-export type ExternalImageSource = HTMLCanvasElement | HTMLImageElement | HTMLVideoElement | ImageBitmap | ImageData | OffscreenCanvas | VideoFrame;
-export type TextureWriteFit = 'stretch';
-export type TextureWriteOptions = {
-    /**
-     * How to handle a source whose dimensions do not match the texture.
-     *
-     * By default, mismatched writes throw. Use `'stretch'` to resample the
-     * source to the texture's dimensions.
-     */
-    fit?: TextureWriteFit;
-};
+export type { TextureBlobWriteOptions, TextureChannel, TextureCopyOptions, TextureRawWriteOptions, TextureWriteFit, TextureWriteOptions, } from './textureWrite.ts';
 type TgpuTextureViewDescriptor = {
     /**
      * Which {@link GPUTextureAspect | aspect(s)} of the texture are accessible to the texture view.
@@ -106,6 +97,12 @@ type CopyCompatibleTexture<T extends TextureProps> = TgpuTexture<{
     format: T['format'];
     sampleCount?: T['sampleCount'];
 }>;
+type FormatCompatibleTexture<T extends TextureProps> = TgpuTexture<{
+    size: readonly number[];
+    format: T['format'];
+    dimension?: TextureProps['dimension'];
+    sampleCount?: T['sampleCount'];
+}>;
 export interface TgpuTexture<TProps extends TextureProps = any> extends TgpuNamable {
     readonly [$internal]: TextureInternals;
     readonly [$soul]: TgpuTextureSoul<TProps>;
@@ -123,11 +120,21 @@ export interface TgpuTexture<TProps extends TextureProps = any> extends TgpuNama
         sampleType?: T['sampleType'] extends F32 ? 'float' | 'unfilterable-float' : never;
     }): TgpuTextureView<T>;
     createView<T extends WgslStorageTexture>(schema: ValidateTextureViewSchema<this, T>, viewDescriptor?: TgpuTextureViewDescriptor): TgpuTextureView<T>;
+    /** Clears the texture to zeros */
     clear(mipLevel?: number | 'all'): void;
+    /** Clears the texture to `color`. Requires the `'render'` usage flag */
+    clear(color: readonly [number, number, number, number], mipLevel?: number | 'all'): void;
     generateMipmaps(baseMipLevel?: number, mipLevels?: number): void;
-    write(source: ExternalImageSource | ExternalImageSource[], options?: TextureWriteOptions): void;
-    write(source: ArrayBuffer | TypedArray | DataView, mipLevel?: number): void;
+    /** Writes image sources to the texture, one per array layer. Requires the `'render'` usage flag */
+    write(source: GPUCopyExternalImageSource | GPUCopyExternalImageSource[], options?: TextureWriteOptions): void;
+    /** Writes raw texel data to the texture */
+    write(source: ArrayBuffer | TypedArray | DataView, options?: number | TextureRawWriteOptions): void;
+    /** Decodes an image blob and writes it to the texture. Requires the `'render'` usage flag */
+    writeAsync(source: Blob, options?: TextureBlobWriteOptions): Promise<void>;
+    /** Copies the contents of a texture with a matching size and format */
     copyFrom<T extends CopyCompatibleTexture<TProps>>(source: T): void;
+    /** Copies a region between textures of the same format */
+    copyFrom<T extends FormatCompatibleTexture<TProps>>(source: T, options: TextureCopyOptions): void;
     destroy(): void;
 }
 export interface TgpuTextureView<TSchema extends WgslStorageTexture | WgslTexture = WgslStorageTexture | WgslTexture> extends TgpuNamable {
@@ -170,4 +177,3 @@ export declare class TgpuTextureRenderViewImpl implements TgpuTextureRenderView
     constructor(baseTexture: TgpuTexture, descriptor?: TgpuTextureViewDescriptor);
     get descriptor(): TgpuTextureViewDescriptor;
 }
-export {};