typegpu 0.12.6 → 0.12.7

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/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/pipeline/connectAttachmentToShader.d.ts

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

package/core/pipeline/connectAttachmentToShader.js

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

package/core/pipeline/connectTargetsToShader.d.ts

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

package/core/pipeline/connectTargetsToShader.js

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

package/core/pipeline/renderPipeline.d.ts

@@ -3,7 +3,7 @@ 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 AnyWgslData, 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 } 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';
@@ -18,6 +18,7 @@ import type { TgpuVertexFn } from '../function/tgpuVertexFn.ts';
 import type { ExperimentalTgpuRoot } from '../root/rootTypes.ts';
 import type { TgpuSlot } from '../slot/slotTypes.ts';
 import { type TgpuVertexLayout } from '../vertexLayout/vertexLayout.ts';
+import { type ConnectedTarget } from './connectTargetsToShader.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';
@@ -34,7 +35,7 @@ export interface RenderPipelineInternals {
 export interface TgpuRenderPipelineSoul extends TgpuDeviceOwningSoul<'render-pipeline', GPURenderPipeline> {
     usedBindGroupLayouts?: TgpuBindGroupLayout[] | undefined;
     usedVertexLayouts?: TgpuVertexLayout[] | undefined;
-    fragmentOut?: BaseData | undefined;
+    connectedTargets?: (ConnectedTarget | null)[] | undefined;
     bindGroups?: [TgpuBindGroupLayout, TgpuBindGroup | GPUBindGroup][] | undefined;
     usedImmediate?: TgpuImmediateVar | undefined;
     immediates?: [TgpuImmediateVar, ImmediateSnapshot][] | undefined;
@@ -221,7 +222,7 @@ type Memo = {
     catchall: [number, TgpuBindGroup] | undefined;
     logResources: LogResources | undefined;
     usedVertexLayouts: TgpuVertexLayout[];
-    fragmentOut: BaseData | undefined;
+    connectedTargets: (ConnectedTarget | null)[] | undefined;
     usedImmediate: TgpuImmediateVar | undefined;
 };
 declare class TgpuRenderPipelineImpl implements TgpuRenderPipeline {
@@ -280,8 +281,8 @@ declare class RenderPipelineCore implements SelfResolvable {
     resolveAndCreateShaderModule(): {
         resolutionResult: import("../../resolutionCtx.ts").ResolutionResult;
         descriptor: GPURenderPipelineDescriptor;
+        connectedTargets: (ConnectedTarget | null)[];
         connectedAttribs: import("../vertexLayout/connectAttributesToShader.ts").ConnectAttributesToShaderResult;
-        fragmentOut: WgslStruct<import("../function/ioSchema.ts").WithLocations<Record<string, BaseData>>>;
     };
 }
 /**

package/core/pipeline/renderPipeline.js

@@ -42,7 +42,7 @@ export function INTERNAL_restoreRenderPipeline(soul, ctx) {
         catchall: undefined,
         logResources: undefined,
         usedVertexLayouts: soul.usedVertexLayouts ?? [],
-        fragmentOut: soul.fragmentOut,
+        connectedTargets: soul.connectedTargets,
         usedImmediate: soul.usedImmediate,
     });
     const pipeline = new TgpuRenderPipelineImpl(core, {
@@ -77,7 +77,7 @@ class TgpuRenderPipelineImpl {
                     soul.raw = memo.pipeline;
                     soul.usedBindGroupLayouts = memo.usedBindGroupLayouts;
                     soul.usedVertexLayouts = memo.usedVertexLayouts;
-                    soul.fragmentOut = memo.fragmentOut;
+                    soul.connectedTargets = memo.connectedTargets;
                     soul.bindGroups = collectBindGroupPairs(memo.usedBindGroupLayouts, memo.catchall, priors.bindGroupLayoutMap);
                     soul.usedImmediate = memo.usedImmediate;
                     soul.immediates = [...(priors.immediatesMap ?? [])];
@@ -224,12 +224,10 @@ class TgpuRenderPipelineImpl {
     }
     #ownPassDescriptor() {
         const { core, priors } = this[$internal];
-        const { fragmentOut } = core.unwrap();
+        const { connectedTargets } = core.unwrap();
         return {
             label: getName(core) ?? '<unnamed>',
-            colorAttachments: fragmentOut
-                ? connectAttachmentToShader(fragmentOut, priors.colorAttachment ?? {})
-                : [],
+            colorAttachments: connectAttachmentToShader(connectedTargets, priors.colorAttachment ?? {}),
             depthStencilAttachment: priors.depthStencilAttachment,
             timestampWrites: priors.timestampWrites,
         };
@@ -345,7 +343,7 @@ class RenderPipelineCore {
         if (this.#initAsyncPromise === undefined) {
             // the pipeline did not start resolution & compilation
             const device = this.options.root.device;
-            const { resolutionResult, descriptor, connectedAttribs, fragmentOut } = this.resolveAndCreateShaderModule();
+            const { resolutionResult, descriptor, connectedTargets, connectedAttribs } = this.resolveAndCreateShaderModule();
             const { usedBindGroupLayouts, catchall, logResources } = resolutionResult;
             this.#initAsyncPromise = device
                 .createRenderPipelineAsync(descriptor)
@@ -356,7 +354,7 @@ class RenderPipelineCore {
                     catchall,
                     logResources,
                     usedVertexLayouts: connectedAttribs.usedVertexLayouts,
-                    fragmentOut,
+                    connectedTargets,
                     usedImmediate: resolutionResult.usedImmediate,
                 };
                 this.#performanceTracker.measureCompile(device);
@@ -375,7 +373,7 @@ class RenderPipelineCore {
             throw new Error("'pipeline.initAsync()' was called and is not yet resolved.");
         }
         const device = this.options.root.device;
-        const { resolutionResult, descriptor, connectedAttribs, fragmentOut } = this.resolveAndCreateShaderModule();
+        const { resolutionResult, descriptor, connectedTargets, connectedAttribs } = this.resolveAndCreateShaderModule();
         const { usedBindGroupLayouts, catchall, logResources } = resolutionResult;
         this.#memo = {
             pipeline: device.createRenderPipeline(descriptor),
@@ -383,7 +381,7 @@ class RenderPipelineCore {
             catchall,
             logResources,
             usedVertexLayouts: connectedAttribs.usedVertexLayouts,
-            fragmentOut,
+            connectedTargets,
             usedImmediate: resolutionResult.usedImmediate,
         };
         this.#performanceTracker.measureCompile(device);
@@ -444,7 +442,7 @@ class RenderPipelineCore {
         if (tgpuDescriptor.fragment) {
             descriptor.fragment = {
                 module,
-                targets: connectedTargets,
+                targets: connectedTargets.map((target) => (target ? target.target : null)),
             };
         }
         if (tgpuDescriptor.primitive) {
@@ -467,7 +465,7 @@ class RenderPipelineCore {
         if (tgpuDescriptor.multisample) {
             descriptor.multisample = tgpuDescriptor.multisample;
         }
-        return { resolutionResult, descriptor, connectedAttribs, fragmentOut };
+        return { resolutionResult, descriptor, connectedTargets, connectedAttribs };
     }
 }
 /**

package/core/resolve/namespace.js

@@ -1,4 +1,4 @@
-import { bannedTokens, builtins } from "../../nameUtils.js";
+import { bannedTokens, builtins, templateEnumerants } from "../../nameUtils.js";
 import { $internal } from "../../shared/symbols.js";
 import { ShelllessRepository } from "../../tgsl/shellless.js";
 class NamespaceImpl {
@@ -6,7 +6,7 @@ class NamespaceImpl {
     constructor(strategy) {
         this[$internal] = {
             strategy,
-            takenGlobalIdentifiers: new Set([...bannedTokens, ...builtins]),
+            takenGlobalIdentifiers: new Set([...bannedTokens, ...builtins, ...templateEnumerants]),
             shelllessRepo: new ShelllessRepository(),
             memoizedResolves: new WeakMap(),
             memoizedLazy: new WeakMap(),

package/core/root/rootTypes.d.ts

@@ -430,9 +430,13 @@ export interface TgpuRoot extends Unwrapper, WithBinding {
      */
     get enabledWgslLanguageFeatures(): ReadonlySet<string>;
     /**
-     * Destroys all underlying resources (i.e. buffers...) created through this root object.
+     * Releases internal resource caches (e.g. utility texture pipelines),
+     * letting the GC reclaim them.
+     *
+     * Buffers, textures and other resources created through the root are NOT destroyed.
+     *
      * If the object is created via `tgpu.init` instead of `tgpu.initFromDevice`,
-     * then the inner GPU device is destroyed as well.
+     * destroys the underlying WebGPU device as well.
      */
     destroy(): void;
     '~unstable': Pick<ExperimentalTgpuRoot, 'createCommandEncoder' | 'createComparisonSampler' | 'createGuardedComputePipeline' | 'createRenderBundleEncoder' | 'createSampler' | 'createTexture' | 'nameRegistrySetting' | 'shaderGeneratorClass' | 'pipe' | 'with'>;

package/core/slot/accessor.d.ts

@@ -1,5 +1,5 @@
 import { type AnyData } from '../../data/dataTypes.ts';
-import type { BaseData } from '../../data/wgslTypes.ts';
+import { type BaseData } from '../../data/wgslTypes.ts';
 import type { InferGPU } from '../../shared/repr.ts';
 import { $getNameForward, $gpuValueOf, $internal, $resolve, $soul } from '../../shared/symbols.ts';
 import type { UnwrapRuntimeConstructor } from '../../tgpuBindGroupLayout.ts';