typegpu 0.12.5 → 0.12.7

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/common/writeSoA.js

@@ -5,6 +5,7 @@ import { undecorate } from "../data/dataTypes.js";
 import { offsetsForProps } from "../data/offsets.js";
 import { sizeOf } from "../data/sizeOf.js";
 import { isAtomic, isMat, isMat2x2f, isMat3x3f, isWgslArray } from "../data/wgslTypes.js";
+import { getName } from "../shared/meta.js";
 function packedSchemaOf(schema) {
     const unpackedSchema = undecorate(schema);
     return isAtomic(unpackedSchema) ? unpackedSchema.inner : unpackedSchema;
@@ -92,6 +93,17 @@ function scatterSoA(target, arraySchema, soaData, startOffset, endOffset) {
         }
     }
 }
+// Mirrors the check in `buffer.write()`. That check only runs after the data has been
+// scattered into `buffer.arrayBuffer`, so we check up front to leave it untouched on failure.
+function assertAlignedWrite(buffer, startOffset, endOffset) {
+    // Writes that reach the end of the schema also cover the padding up to a multiple of 4
+    const paddedEndOffset = endOffset === sizeOf(buffer.dataType) ? roundUp(endOffset, 4) : endOffset;
+    if (startOffset % 4 !== 0 || (paddedEndOffset - startOffset) % 4 !== 0) {
+        throw new Error(`Cannot write to bytes ${startOffset}-${endOffset} of buffer '${getName(buffer) ?? '<unnamed>'}'. ` +
+            'WebGPU requires writes to start and end at a multiple of 4 bytes. ' +
+            'Align the range to 4 bytes, write the whole buffer, or use 4-byte elements (e.g. d.u32 instead of d.u16).');
+    }
+}
 export function writeSoA(buffer, data, options) {
     const arrayBuffer = buffer.arrayBuffer;
     const startOffset = options?.startOffset ?? 0;
@@ -99,6 +111,10 @@ export function writeSoA(buffer, data, options) {
     const naturalSize = computeSoAByteLength(buffer.dataType, data);
     const endOffset = options?.endOffset ??
         (naturalSize === undefined ? bufferSize : Math.min(startOffset + naturalSize, bufferSize));
+    // Writes to mapped memory have no alignment rules
+    if (buffer.buffer.mapState !== 'mapped') {
+        assertAlignedWrite(buffer, startOffset, endOffset);
+    }
     scatterSoA(new Uint8Array(arrayBuffer), buffer.dataType, data, startOffset, endOffset);
     buffer.write(arrayBuffer, { startOffset, endOffset });
 }

package/core/buffer/buffer.js

@@ -1,6 +1,7 @@
 import { getCompiledWriter } from "../../data/compiledIO.js";
 import { convertPartialToPatch, getPatchInstructions } from "../../data/partialIO.js";
 import { sizeOf } from "../../data/sizeOf.js";
+import { roundUp } from "../../mathUtils.js";
 import { isWgslData } from "../../data/wgslTypes.js";
 import { getName, setName } from "../../shared/meta.js";
 import { $internal, $soul } from "../../shared/symbols.js";
@@ -10,6 +11,14 @@ import { patchArrayBuffer } from "../../data/partialIO.js";
 import { mutable, readonly, uniform, } from "./bufferBinding.js";
 import { warnIfNotUniformAligned } from "../pipeline/webgpuLimitations.js";
 const usageToUsageConstructor = { uniform, mutable, readonly };
+/**
+ * WebGPU requires buffer sizes, writes, copies and mappings
+ * to be multiples of 4 bytes. Schemas like `arrayOf(u16, 3)` can have a smaller logical
+ * size, so the underlying allocation gets padded up to the next multiple of 4.
+ */
+function physicalSizeOf(schema) {
+    return roundUp(sizeOf(schema), 4);
+}
 export function INTERNAL_createBuffer(group, typeSchema, initialOrBuffer) {
     if (!isWgslData(typeSchema)) {
         return new TgpuBufferImpl(group, typeSchema, initialOrBuffer, ['storage', 'uniform']);
@@ -32,7 +41,7 @@ class TgpuBufferImpl {
     #destroyed = false;
     #internalBuffer;
     get #hostBuffer() {
-        return (this.#internalBuffer ??= new ArrayBuffer(sizeOf(this.dataType)));
+        return (this.#internalBuffer ??= new ArrayBuffer(physicalSizeOf(this.dataType)));
     }
     #mappedRange;
     #initialCallback;
@@ -76,7 +85,7 @@ class TgpuBufferImpl {
                 const soul = this[$soul];
                 if (!soul.raw) {
                     soul.raw = soul.device.createBuffer({
-                        size: sizeOf(soul.dataType),
+                        size: physicalSizeOf(soul.dataType),
                         usage: soul.flags,
                         mappedAtCreation: !!this.initial || !!this.#initialCallback,
                         label: getName(this) ?? '<unnamed>',
@@ -195,15 +204,31 @@ class TgpuBufferImpl {
             writeToArrayBuffer(mapped, this.dataType, data, options);
             return;
         }
+        const { startOffset, endOffset } = calculateOffsets(options, this.dataType, data);
+        const size = this.#alignedWriteSize(startOffset, endOffset);
         // If the caller already wrote directly into #hostBuffer via
         // arrayBuffer, skip the redundant copy, the data is already in place.
         if (!(data instanceof ArrayBuffer && data === this.#hostBuffer)) {
             writeToArrayBuffer(this.#hostBuffer, this.dataType, data, options);
         }
-        const { startOffset, endOffset } = calculateOffsets(options, this.dataType, data);
-        const size = endOffset - startOffset;
         this[$soul].device.queue.writeBuffer(gpuBuffer, startOffset, this.#hostBuffer, startOffset, size);
     }
+    /**
+     * Returns the number of bytes to upload when writing to `[startOffset, endOffset)`.
+     * Writes that reach the end of the schema also cover the trailing padding (see {@link physicalSizeOf}).
+     * Other writes have to be 4-byte aligned already, since filling in the neighboring bytes
+     * from the host could overwrite data that was changed on the GPU.
+     */
+    #alignedWriteSize(startOffset, endOffset) {
+        const paddedEndOffset = endOffset === sizeOf(this.dataType) ? physicalSizeOf(this.dataType) : endOffset;
+        const size = paddedEndOffset - startOffset;
+        if (startOffset % 4 !== 0 || size % 4 !== 0) {
+            throw new Error(`Cannot write to bytes ${startOffset}-${endOffset} of buffer '${getName(this) ?? '<unnamed>'}'. ` +
+                'WebGPU requires writes to start and end at a multiple of 4 bytes. ' +
+                'Align the range to 4 bytes, write the whole buffer, or use 4-byte elements (e.g. d.u32 instead of d.u16).');
+        }
+        return size;
+    }
     /** @deprecated Use {@link patch} instead. */
     writePartial(data) {
         this.patch(convertPartialToPatch(this.dataType, data));
@@ -214,9 +239,19 @@ class TgpuBufferImpl {
             patchArrayBuffer(this.#getMappedRange(), this.dataType, data);
         }
         else {
-            const instructions = getPatchInstructions(this.dataType, data, this.#hostBuffer);
-            for (const { data, gpuOffset } of instructions) {
-                this[$soul].device.queue.writeBuffer(gpuBuffer, gpuOffset, data);
+            // Every range is validated before the patch touches #hostBuffer, so a failing patch
+            // is neither uploaded halfway nor left behind in `arrayBuffer`
+            const instructions = getPatchInstructions(this.dataType, data, this.#hostBuffer, (start, end) => this.#alignedWriteSize(start, end));
+            for (const { data, gpuOffset, uploadSize } of instructions) {
+                if (uploadSize === data.byteLength) {
+                    this[$soul].device.queue.writeBuffer(gpuBuffer, gpuOffset, data);
+                }
+                else {
+                    // Extending the write into the trailing padding (see physicalSizeOf)
+                    const padded = new Uint8Array(uploadSize);
+                    padded.set(data);
+                    this[$soul].device.queue.writeBuffer(gpuBuffer, gpuOffset, padded);
+                }
             }
         }
     }
@@ -238,7 +273,7 @@ class TgpuBufferImpl {
         if (this.buffer.mapState === 'mapped') {
             throw new Error('Cannot copy to a mapped buffer.');
         }
-        const size = sizeOf(this.dataType);
+        const size = physicalSizeOf(this.dataType);
         if (encoder) {
             encoder[$internal].rawEncoder.copyBufferToBuffer(srcBuffer.buffer, 0, this.buffer, 0, size);
             return;
@@ -258,14 +293,15 @@ class TgpuBufferImpl {
             this.#unmapBuffer();
             return res;
         }
+        const size = physicalSizeOf(this.dataType);
         const stagingBuffer = this[$soul].device.createBuffer({
-            size: sizeOf(this.dataType),
+            size,
             usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
         });
         const commandEncoder = this[$soul].device.createCommandEncoder();
-        commandEncoder.copyBufferToBuffer(gpuBuffer, 0, stagingBuffer, 0, sizeOf(this.dataType));
+        commandEncoder.copyBufferToBuffer(gpuBuffer, 0, stagingBuffer, 0, size);
         this[$soul].device.queue.submit([commandEncoder.finish()]);
-        await stagingBuffer.mapAsync(GPUMapMode.READ, 0, sizeOf(this.dataType));
+        await stagingBuffer.mapAsync(GPUMapMode.READ, 0, size);
         const res = readFromArrayBuffer(stagingBuffer.getMappedRange(), this.dataType);
         stagingBuffer.unmap();
         stagingBuffer.destroy();

package/core/commandEncoder/attachments.js

@@ -1,16 +1,19 @@
+import { WeakMemo } from "../../memo.js";
 import { $internal } from "../../shared/symbols.js";
 import { isQuerySet } from "../querySet/querySet.js";
 import { isGPUCanvasContext } from "../pipeline/typeGuards.js";
 import { isTexture, isTextureView, } from "../texture/texture.js";
+// Canvas contexts return the same texture within a frame, so its identity is enough to cache views
+const defaultAttachmentViews = new WeakMemo((texture) => texture.createView());
 export function unwrapAttachmentView(root, view) {
     if (isTexture(view)) {
-        return root.unwrap(view).createView();
+        return defaultAttachmentViews.getOrMake(root.unwrap(view));
     }
     if (isTextureView(view)) {
         return root.unwrap(view);
     }
     if (isGPUCanvasContext(view)) {
-        return view.getCurrentTexture().createView();
+        return defaultAttachmentViews.getOrMake(view.getCurrentTexture());
     }
     return view;
 }

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/function/autoIO.js

@@ -39,7 +39,8 @@ export class AutoFragmentFn {
             setName(impl, 'fragmentFn');
         }
         this.#core = createFnCore(impl, 'fragment');
-        this.autoIn = new AutoStruct({ ...builtinFragmentIn, ...varyings }, undefined, locations);
+        this.autoIn = new AutoStruct({ ...builtinFragmentIn, ...varyings }, undefined, locations, 
+        /* autoInterpolateIntegers */ true);
         setName(this.autoIn, 'FragmentIn');
         this.autoOut = new AutoStruct(builtinFragmentOut, vec4f);
         setName(this.autoOut, 'FragmentOut');
@@ -68,7 +69,8 @@ export class AutoVertexFn {
         this.#core = createFnCore(impl, 'vertex');
         this.autoIn = new AutoStruct({ ...builtinVertexIn, ...attribs }, undefined, locations);
         setName(this.autoIn, 'VertexIn');
-        this.autoOut = new AutoStruct(builtinVertexOut, undefined);
+        this.autoOut = new AutoStruct(builtinVertexOut, undefined, undefined, 
+        /* autoInterpolateIntegers */ true);
         setName(this.autoOut, 'VertexOut');
     }
     toString() {

package/core/function/ioSchema.d.ts

@@ -7,7 +7,12 @@ export type WithLocations<T extends Record<string, BaseData>> = {
 export type IOLayoutToSchema<T> = T extends BaseData ? HasCustomLocation<T> extends true ? T : Decorate<T, Location<0>> : T extends Record<string, BaseData> ? WgslStruct<WithLocations<T>> : T extends {
     type: 'void';
 } ? void : never;
-export declare function withLocations<T extends BaseData>(members: Record<string, T> | undefined, locations?: Record<string, number>): Record<string, BaseData>;
+export declare function withLocations<T extends BaseData>(members: Record<string, T> | undefined, locations?: Record<string, number>, autoInterpolateIntegers?: boolean): Record<string, BaseData>;
 export declare function separateBuiltins(schema: Record<string, BaseData>, locations?: Record<string, number>): SeparatedEntryArgs;
 export declare function separateAllAsPositional(schema: Record<string, BaseData>): SeparatedEntryArgs;
-export declare function createIoSchema<T extends BaseData | Record<string, BaseData>>(layout: T, locations?: Record<string, number>): IOLayoutToSchema<T>;
+export declare function createIoSchema<T extends BaseData | Record<string, BaseData>>(layout: T, locations?: Record<string, number>, autoInterpolateIntegers?: boolean): IOLayoutToSchema<T>;
+/**
+ * WGSL requires integer inter-stage values to be flat interpolated. Interpolation is only
+ * inferred for shellless entry functions, so shells have to specify it explicitly.
+ */
+export declare function assertIntegerVaryingsInterpolated(layout: BaseData | Record<string, BaseData> | undefined, location: string): void;

package/core/function/ioSchema.js

@@ -1,9 +1,9 @@
-import { location, } from "../../data/attributes.js";
+import { interpolate, location, } from "../../data/attributes.js";
 import { isBuiltin } from "../../data/attributes.js";
 import { getCustomLocation, isData } from "../../data/dataTypes.js";
 import { INTERNAL_createStruct } from "../../data/struct.js";
-import { isVoid } from "../../data/wgslTypes.js";
-export function withLocations(members, locations = {}) {
+import { isDecorated, isInteger, isIntegerVec, isInterpolateAttrib, isVoid, } from "../../data/wgslTypes.js";
+export function withLocations(members, locations = {}, autoInterpolateIntegers = false) {
     let nextLocation = 0;
     const usedCustomLocations = new Set();
     return Object.fromEntries(Object.entries(members ?? {})
@@ -15,7 +15,10 @@ export function withLocations(members, locations = {}) {
             }
             usedCustomLocations.add(customLocation);
         }
-        return [key, member];
+        return [
+            key,
+            autoInterpolateIntegers ? withFlatInterpolationForInteger(member) : member,
+        ];
     })
         .map(([key, member]) => {
         if (isBuiltin(member)) {
@@ -57,15 +60,38 @@ export function separateAllAsPositional(schema) {
     const positionalArgs = Object.entries(withLocs).map(([key, type]) => ({ schemaKey: key, type }));
     return { dataSchema: undefined, positionalArgs };
 }
-export function createIoSchema(layout, locations = {}) {
-    return (isData(layout)
-        ? isVoid(layout)
-            ? layout
-            : isBuiltin(layout)
-                ? layout
-                : getCustomLocation(layout) !== undefined
-                    ? layout
-                    : location(0, layout)
-        : INTERNAL_createStruct(withLocations(layout, locations), 
-        /* isAbstruct */ false));
+export function createIoSchema(layout, locations = {}, autoInterpolateIntegers = false) {
+    if (isData(layout)) {
+        if (isVoid(layout) || isBuiltin(layout)) {
+            return layout;
+        }
+        return (getCustomLocation(layout) !== undefined ? layout : location(0, layout));
+    }
+    return INTERNAL_createStruct(withLocations(layout, locations, autoInterpolateIntegers), 
+    /* isAbstruct */ false);
+}
+function needsFlatInterpolation(data) {
+    if (isBuiltin(data) || (isDecorated(data) && data.attribs.some(isInterpolateAttrib))) {
+        return false;
+    }
+    const inner = isDecorated(data) ? data.inner : data;
+    return isInteger(inner) || isIntegerVec(inner);
+}
+function withFlatInterpolationForInteger(data) {
+    return needsFlatInterpolation(data) ? interpolate('flat', data) : data;
+}
+/**
+ * WGSL requires integer inter-stage values to be flat interpolated. Interpolation is only
+ * inferred for shellless entry functions, so shells have to specify it explicitly.
+ */
+export function assertIntegerVaryingsInterpolated(layout, location) {
+    if (layout === undefined || isData(layout)) {
+        // A single value is either a builtin or a fragment output, neither are varyings
+        return;
+    }
+    for (const [key, member] of Object.entries(layout)) {
+        if (needsFlatInterpolation(member)) {
+            throw new Error(`Integer value "${key}" in ${location} requires flat interpolation. Wrap its schema in d.interpolate('flat', ...) or d.interpolate('flat, either', ...).`);
+        }
+    }
 }

package/core/function/tgpuFragmentFn.d.ts

@@ -13,7 +13,7 @@ export type VertexOutToVarying<T> = OmitBuiltins<{
     [K in keyof T]: InstanceToSchema<T[K]>;
 }>;
 type FragmentColorValue = Vec4f | Vec4i | Vec4u;
-export type FragmentOutConstrained = IOLayout<FragmentColorValue | Decorated<FragmentColorValue, (Location | Interpolate)[]> | AnyFragmentOutputBuiltin>;
+export type FragmentOutConstrained = IOLayout<FragmentColorValue | Decorated<FragmentColorValue, Location[]> | AnyFragmentOutputBuiltin>;
 /**
  * Describes a fragment entry function signature (its arguments, return type and targets)
  */

package/core/function/tgpuFragmentFn.js

@@ -3,7 +3,7 @@ import { $getNameForward, $internal, $resolve } from "../../shared/symbols.js";
 import { addReturnTypeToExternals } from "../resolve/externals.js";
 import { shaderStageSlot } from "../slot/internalSlots.js";
 import { createFnCore } from "./fnCore.js";
-import { createIoSchema, separateBuiltins } from "./ioSchema.js";
+import { assertIntegerVaryingsInterpolated, createIoSchema, separateBuiltins, } from "./ioSchema.js";
 import { stripTemplate } from "./templateUtils.js";
 /**
  * Creates a shell of a typed entry function for the fragment shader stage. Any function
@@ -55,6 +55,7 @@ function createFragmentFn(shell, implementation) {
             return this;
         },
         [$resolve](ctx) {
+            assertIntegerVaryingsInterpolated(shell.in, `fragmentFn (${getName(this) ?? '<unnamed>'}) input`);
             const entryInput = separateBuiltins(shell.in ?? {}, ctx.varyingLocations ?? {});
             if (entryInput.dataSchema && isNamable(entryInput.dataSchema)) {
                 entryInput.dataSchema.$name(`${getName(this) ?? ''}_Input`);

package/core/function/tgpuVertexFn.js

@@ -2,7 +2,7 @@ import { getName, setName } from "../../shared/meta.js";
 import { $getNameForward, $internal, $resolve } from "../../shared/symbols.js";
 import { shaderStageSlot } from "../slot/internalSlots.js";
 import { createFnCore } from "./fnCore.js";
-import { createIoSchema, separateAllAsPositional } from "./ioSchema.js";
+import { assertIntegerVaryingsInterpolated, createIoSchema, separateAllAsPositional, } from "./ioSchema.js";
 import { stripTemplate } from "./templateUtils.js";
 /**
  * Creates a shell of a typed entry function for the vertex shader stage. Any function
@@ -50,6 +50,7 @@ function createVertexFn(shell, implementation) {
             return this;
         },
         [$resolve](ctx) {
+            assertIntegerVaryingsInterpolated(shell.out, `vertexFn (${getName(this) ?? '<unnamed>'}) output`);
             const outputWithLocation = createIoSchema(shell.out, ctx.varyingLocations).$name(`${getName(this) ?? ''}_Output`);
             if (typeof implementation === 'string') {
                 core.setExternals('out', { Out: outputWithLocation });

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