typegpu 0.12.7 → 0.12.8

package/data/dataIO.js

@@ -4,7 +4,7 @@ import { alignmentOf, customAlignmentOf } from "./alignmentOf.js";
 import { mat2x2f, mat3x3f, mat4x4f } from "./matrix.js";
 import { sizeOf } from "./sizeOf.js";
 import { vec2f, vec2h, vec2i, vec2u, vec3f, vec3h, vec3i, vec3u, vec4f, vec4h, vec4i, vec4u, } from "./vector.js";
-import { isWgslArray } from "./wgslTypes.js";
+import * as wgsl from "./wgslTypes.js";
 import { getCompiledWriter } from "./compiledIO.js";
 import { getName } from "../shared/meta.js";
 import { roundUp } from "../mathUtils.js";
@@ -104,8 +104,18 @@ const dataWriters = {
         }
     },
     mat3x3f(output, _, value) {
-        for (let i = 0; i < value.length; ++i) {
-            output.writeFloat32(value[i]);
+        if (value instanceof Float32Array || wgsl.isMatInstance(value)) {
+            for (let i = 0; i < value.length; ++i) {
+                output.writeFloat32(value[i]);
+            }
+        }
+        else {
+            for (let i = 0; i < 3; ++i) {
+                for (let j = 0; j < 3; ++j) {
+                    output.writeFloat32(value[3 * i + j]);
+                }
+                output.writeFloat32(0);
+            }
         }
     },
     mat4x4f(output, _, value) {
@@ -607,7 +617,7 @@ export function calculateOffsets(options, schema, data) {
     const bufferSize = sizeOf(schema);
     const startOffset = options?.startOffset ?? 0;
     let naturalSize = undefined;
-    if (isWgslArray(schema) && Array.isArray(data)) {
+    if (wgsl.isWgslArray(schema) && Array.isArray(data)) {
         const arrayData = data;
         naturalSize =
             arrayData.length * roundUp(sizeOf(schema.elementType), alignmentOf(schema.elementType));
@@ -619,6 +629,11 @@ export function calculateOffsets(options, schema, data) {
     const endOffset = options?.endOffset ?? naturalEndOffset ?? bufferSize;
     return { startOffset, endOffset };
 }
+/**
+ * A function for filling in buffers with data based on TypeGPU schemas.
+ * When schema instances or JS arrays are passed, the padding is applied automatically.
+ * ArrayBuffers are expected to be already padded.
+ */
 export function writeToArrayBuffer(buffer, schema, data, options) {
     const { startOffset, endOffset } = calculateOffsets(options, schema, data);
     // Fast path: raw byte copy, user guarantees the padded layout

package/data/dataTypes.d.ts

@@ -3,7 +3,6 @@ import type { Infer, InferGPURecord, InferInput, InferInputRecord, InferPatch, I
 import type { $gpuRepr, $inRepr, $invalidSchemaReason, $memIdent, $repr, $reprPartial, $reprPatch, $validVertexSchema } from '../shared/symbols.ts';
 import type { Prettify } from '../shared/utilityTypes.ts';
 import type { WgslExternalTexture, WgslStorageTexture, WgslTexture } from './texture.ts';
-import type { Snippet } from './snippet.ts';
 import type { PackedData } from './vertexFormatData.ts';
 import * as wgsl from './wgslTypes.ts';
 import type { WgslComparisonSampler, WgslSampler } from './sampler.ts';
@@ -130,8 +129,4 @@ export type AnyData = wgsl.AnyWgslData | AnyLooseData;
 export type AnyConcreteData = Exclude<AnyData, wgsl.AbstractInt | wgsl.AbstractFloat | wgsl.Void | WgslTexture | WgslStorageTexture | WgslExternalTexture | WgslSampler | WgslComparisonSampler>;
 export declare const UnknownData: unique symbol;
 export type UnknownData = typeof UnknownData;
-export declare class MatrixColumnsAccess {
-    readonly matrix: Snippet;
-    constructor(matrix: Snippet);
-}
 export {};

package/data/dataTypes.js

@@ -73,9 +73,3 @@ export function isData(value) {
     return wgsl.isWgslData(value) || isLooseData(value);
 }
 export const UnknownData = Symbol('UNKNOWN');
-export class MatrixColumnsAccess {
-    matrix;
-    constructor(matrix) {
-        this.matrix = matrix;
-    }
-}

package/data/matrixColumnsAccess.d.ts

@@ -0,0 +1,8 @@
+import { $comptimeValueOf } from '../shared/symbols.ts';
+import { type ComptimeValue, type WithComptimeValue } from '../types.ts';
+import type { Snippet } from './snippet.ts';
+export declare class MatrixColumnsAccess implements WithComptimeValue {
+    readonly matrix: Snippet;
+    constructor(matrix: Snippet);
+    [$comptimeValueOf](): ComptimeValue;
+}

package/data/matrixColumnsAccess.js

@@ -0,0 +1,15 @@
+import { $comptimeValueOf } from "../shared/symbols.js";
+import { asComptime } from "../types.js";
+export class MatrixColumnsAccess {
+    matrix;
+    constructor(matrix) {
+        this.matrix = matrix;
+    }
+    [$comptimeValueOf]() {
+        // Same as accessing `.columns` on a matrix in JS
+        const known = asComptime(this.matrix);
+        return known
+            ? { comptime: true, value: known.value.columns }
+            : { comptime: false };
+    }
+}

package/data/offsetUtils.js

@@ -4,10 +4,26 @@ import { offsetsForProps } from "./offsets.js";
 import { sizeOf } from "./sizeOf.js";
 import { isContiguous } from "./isContiguous.js";
 import { getLongestContiguousPrefix } from "./getLongestContiguousPrefix.js";
-import { isVec, isWgslArray, isWgslStruct } from "./wgslTypes.js";
-import { undecorate } from "./dataTypes.js";
+import { isMat, isVec, isWgslArray, isWgslStruct } from "./wgslTypes.js";
+import { isDisarray, isUnstruct, undecorate } from "./dataTypes.js";
+import { vec2f, vec3f, vec4f } from "./vector.js";
+/**
+ * The absolute byte offset of the node, counted from the start of the root schema.
+ */
 const OFFSET_MARKER = Symbol('indirectOffset');
+/**
+ * The number of contiguous data bytes starting at the node's offset.
+ * The run is not limited to the node itself: it continues into the data that follows,
+ * until the first padding byte or the end of the root schema.
+ * NaN means the run reaches a contiguous runtime-sized array, so its end is unknown.
+ *
+ * @remarks The parent computes this value as if the node had no padding inside.
+ * Non-contiguous nodes have to correct it (e.g. cap it at their own padding) before using it.
+ */
 const CONTIGUOUS_MARKER = Symbol('indirectContiguous');
+function minContiguous(a, b) {
+    return Number.isNaN(a) ? b : Math.min(a, b);
+}
 function isOffsetProxy(value) {
     return (typeof value === 'object' &&
         value !== null &&
@@ -26,12 +42,19 @@ function getMarker(target, prop) {
     }
     return undefined;
 }
-function makeProxy(schema, baseOffset, contiguous = sizeOf(schema)) {
+function throwIfLoose(schema) {
+    if (isUnstruct(schema) || isDisarray(schema)) {
+        throw new Error(`memoryLayoutOf: loose schemas are not supported (encountered '${schema.type}').`);
+    }
+}
+function makeProxy(schema, baseOffset, contiguous) {
     const unwrapped = undecorate(schema);
-    const vecComponentCount = isVec(unwrapped) ? unwrapped.componentCount : undefined;
-    if (vecComponentCount !== undefined) {
-        const componentSize = sizeOf(unwrapped.primitive);
-        return makeVecProxy(scalarNode(baseOffset, contiguous), componentSize, vecComponentCount);
+    throwIfLoose(unwrapped);
+    if (isVec(unwrapped)) {
+        return makeVecProxy(unwrapped, scalarNode(baseOffset, contiguous));
+    }
+    if (isMat(unwrapped)) {
+        return makeMatProxy(unwrapped, scalarNode(baseOffset, contiguous));
     }
     if (isWgslStruct(unwrapped)) {
         return makeStructProxy(unwrapped, scalarNode(baseOffset, contiguous));
@@ -42,100 +65,190 @@ function makeProxy(schema, baseOffset, contiguous = sizeOf(schema)) {
     return scalarNode(baseOffset, contiguous);
 }
 export function createOffsetProxy(schema, baseOffset = 0) {
-    return makeProxy(schema, baseOffset, sizeOf(schema));
+    return makeProxy(schema, baseOffset, sizeOf(undecorate(schema)));
 }
-function makeVecProxy(target, componentSize, componentCount) {
-    const baseOffset = target[OFFSET_MARKER];
-    return new Proxy(target, {
+const vecPropToIndex = {
+    x: 0,
+    y: 1,
+    z: 2,
+    w: 3,
+    r: 0,
+    g: 1,
+    b: 2,
+    a: 3,
+    '0': 0,
+    '1': 1,
+    '2': 2,
+    '3': 3,
+};
+function makeVecProxy(vec, parent) {
+    const baseOffset = parent[OFFSET_MARKER];
+    const componentCount = vec.componentCount;
+    const componentSize = sizeOf(vec.primitive);
+    return new Proxy(parent, {
         get(t, prop) {
             const marker = getMarker(t, prop);
             if (marker !== undefined) {
                 return marker;
             }
-            const idx = prop === 'x' || prop === '0'
-                ? 0
-                : prop === 'y' || prop === '1'
-                    ? 1
-                    : prop === 'z' || prop === '2'
-                        ? 2
-                        : prop === 'w' || prop === '3'
-                            ? 3
-                            : -1;
-            if (idx < 0 || idx >= componentCount) {
+            if (typeof prop !== 'string') {
+                return undefined;
+            }
+            const index = vecPropToIndex[prop] ?? -1;
+            if (index < 0 || index >= componentCount) {
                 return undefined;
             }
-            const byteOffset = idx * componentSize;
+            const byteOffset = index * componentSize;
             const contiguous = Math.max(0, t[CONTIGUOUS_MARKER] - byteOffset);
             return scalarNode(baseOffset + byteOffset, contiguous);
         },
     });
 }
-function makeArrayProxy(array, target) {
+function makeMatProxy(mat, parent) {
+    const [columnCount, columnSchema] = mat.type === 'mat2x2f' ? [2, vec2f] : mat.type === 'mat3x3f' ? [3, vec3f] : [4, vec4f];
+    const elementSize = 4;
+    const columnSize = columnCount * elementSize;
+    const columnStride = columnCount === 2 ? 8 : 16;
+    const hasPadding = columnCount === 3;
+    const remainingFromParent = parent[CONTIGUOUS_MARKER];
+    const ownProxy = !hasPadding
+        ? parent
+        : scalarNode(parent[OFFSET_MARKER], minContiguous(remainingFromParent, columnSize));
+    const columns = new Proxy(ownProxy, {
+        get(t, prop) {
+            const marker = getMarker(t, prop);
+            if (marker !== undefined) {
+                return marker;
+            }
+            if (typeof prop !== 'string') {
+                return undefined;
+            }
+            if (prop === 'length') {
+                return columnCount;
+            }
+            const idx = Number(prop);
+            if (!Number.isInteger(idx) || idx < 0 || idx >= columnCount) {
+                return undefined;
+            }
+            const columnOffset = idx * columnStride;
+            const contiguous = hasPadding ? columnSize : Math.max(0, remainingFromParent - columnOffset);
+            return makeVecProxy(columnSchema, scalarNode(parent[OFFSET_MARKER] + columnOffset, contiguous));
+        },
+    });
+    return new Proxy(ownProxy, {
+        get(t, prop) {
+            const marker = getMarker(t, prop);
+            if (marker !== undefined) {
+                return marker;
+            }
+            if (typeof prop !== 'string') {
+                return undefined;
+            }
+            if (prop === 'columns') {
+                return columns;
+            }
+            const index = Number(prop);
+            if (!Number.isInteger(index) ||
+                index < 0 ||
+                index * elementSize >= columnCount * columnStride) {
+                return undefined;
+            }
+            const byteOffset = elementSize * index;
+            if (byteOffset % columnStride === columnSize) {
+                return undefined;
+            }
+            const remaining = Math.max(0, remainingFromParent - byteOffset);
+            const columnEnd = Math.floor(byteOffset / columnStride) * columnStride + columnSize;
+            const localRemaining = columnEnd - byteOffset;
+            return scalarNode(t[OFFSET_MARKER] + byteOffset, hasPadding ? localRemaining : remaining);
+        },
+    });
+}
+function makeArrayProxy(array, parent) {
     const elementType = array.elementType;
     const elementSize = sizeOf(elementType);
     const stride = roundUp(elementSize, alignmentOf(elementType));
     const hasPadding = stride > elementSize;
-    return new Proxy(target, {
+    const elementLCP = getLongestContiguousPrefix(elementType);
+    const remainingFromParent = parent[CONTIGUOUS_MARKER];
+    const ownProxy = isContiguous(array)
+        ? parent
+        : scalarNode(parent[OFFSET_MARKER], minContiguous(remainingFromParent, getLongestContiguousPrefix(array)));
+    return new Proxy(ownProxy, {
         get(t, prop) {
             const marker = getMarker(t, prop);
             if (marker !== undefined) {
                 return marker;
             }
-            if (prop === 'length') {
-                return array.elementCount;
-            }
             if (typeof prop !== 'string') {
                 return undefined;
             }
+            if (prop === 'length') {
+                return array.elementCount;
+            }
             const index = Number(prop);
             if (!Number.isInteger(index) || index < 0 || index >= array.elementCount) {
                 return undefined;
             }
             const elementOffset = index * stride;
-            const remainingFromHere = !isContiguous(elementType)
-                ? elementSize + getLongestContiguousPrefix(elementType) // it is too much, but we correct it later
-                : Math.max(0, t[CONTIGUOUS_MARKER] - elementOffset);
-            const childContiguous = hasPadding
-                ? Math.min(remainingFromHere, elementSize)
-                : remainingFromHere;
+            const remaining = Math.max(0, remainingFromParent - elementOffset);
+            let childContiguous;
+            if (hasPadding) {
+                childContiguous = minContiguous(remaining, elementSize);
+            }
+            else if (!isContiguous(elementType) && index < array.elementCount - 1) {
+                childContiguous = elementSize + elementLCP;
+            }
+            else {
+                childContiguous = remaining;
+            }
             return makeProxy(elementType, t[OFFSET_MARKER] + elementOffset, childContiguous);
         },
     });
 }
-function makeStructProxy(struct, target) {
+function makeStructProxy(struct, parent) {
     const offsets = offsetsForProps(struct);
     const propTypes = struct.propTypes;
-    const propNames = Object.keys(propTypes);
+    const props = Object.entries(propTypes);
+    const structSize = sizeOf(struct);
+    const remainingFromParent = parent[CONTIGUOUS_MARKER];
+    const ownProxy = isContiguous(struct)
+        ? parent
+        : scalarNode(parent[OFFSET_MARKER], minContiguous(remainingFromParent, getLongestContiguousPrefix(struct)));
     const meta = new Map();
-    let runStart = 0;
-    for (let i = 0; i < propNames.length; i++) {
-        const name = propNames[i];
-        if (!name) {
-            continue;
-        }
-        const type = propTypes[name];
-        if (!type) {
-            continue;
-        }
+    let nextPropLocalRemainingData = 0;
+    let nextPropRunReachesEnd = false;
+    for (let i = props.length - 1; i >= 0; i--) {
+        const [name, type] = props[i];
         const info = offsets[name];
-        const padding = info.padding ?? 0;
-        const typeContiguous = isContiguous(type);
-        const isRunEnd = i === propNames.length - 1 || padding > 0 || !typeContiguous;
-        if (!isRunEnd) {
-            continue;
-        }
-        const runEnd = info.offset + (typeContiguous ? info.size : getLongestContiguousPrefix(type));
-        for (let j = runStart; j <= i; j++) {
-            const runName = propNames[j];
-            if (!runName) {
-                continue;
-            }
-            const runInfo = offsets[runName];
-            meta.set(runName, { offset: runInfo.offset, runEnd });
+        const dataSize = sizeOf(undecorate(type));
+        const noGapAfter = (info.padding ?? 0) === 0 && sizeOf(type) === dataSize;
+        let dataAfter = 0;
+        let runReachesEnd = false;
+        if (noGapAfter) {
+            if (i === props.length - 1) {
+                runReachesEnd = true;
+            }
+            else {
+                const [, nextType] = props[i + 1];
+                if (isContiguous(nextType)) {
+                    dataAfter = sizeOf(nextType) + nextPropLocalRemainingData;
+                    runReachesEnd = nextPropRunReachesEnd;
+                }
+                else {
+                    dataAfter = getLongestContiguousPrefix(nextType);
+                }
+            }
         }
-        runStart = i + 1;
+        meta.set(name, {
+            offset: info.offset,
+            localRemaining: dataSize + dataAfter,
+            runReachesEnd,
+        });
+        nextPropLocalRemainingData = dataAfter;
+        nextPropRunReachesEnd = runReachesEnd;
     }
-    return new Proxy(target, {
+    return new Proxy(ownProxy, {
         get(t, prop) {
             const marker = getMarker(t, prop);
             if (marker !== undefined) {
@@ -145,52 +258,17 @@ function makeStructProxy(struct, target) {
                 return undefined;
             }
             const m = meta.get(prop);
-            if (!m) {
-                return undefined;
-            }
-            const remainingFromHere = Math.max(0, t[CONTIGUOUS_MARKER] - m.offset);
-            const localLimit = Math.max(0, m.runEnd - m.offset);
             const propSchema = propTypes[prop];
-            if (!propSchema) {
+            if (!m || !propSchema) {
                 return undefined;
             }
-            return makeProxy(propSchema, t[OFFSET_MARKER] + m.offset, sizeOf(struct) === m.runEnd ? remainingFromHere : localLimit);
+            const childContiguous = m.runReachesEnd
+                ? m.localRemaining + Math.max(0, remainingFromParent - structSize)
+                : m.localRemaining;
+            return makeProxy(propSchema, t[OFFSET_MARKER] + m.offset, childContiguous);
         },
     });
 }
-function getRootContiguous(schema) {
-    const unwrapped = undecorate(schema);
-    if (isWgslStruct(unwrapped)) {
-        const offsets = offsetsForProps(unwrapped);
-        const propTypes = unwrapped.propTypes;
-        const propNames = Object.keys(propTypes);
-        for (let i = 0; i < propNames.length; i++) {
-            const name = propNames[i];
-            if (!name) {
-                continue;
-            }
-            const info = offsets[name];
-            const padding = info.padding ?? 0;
-            const runEnd = info.offset + info.size;
-            const isRunEnd = i === propNames.length - 1 || padding > 0;
-            if (isRunEnd) {
-                return runEnd;
-            }
-        }
-        return 0;
-    }
-    if (isWgslArray(unwrapped)) {
-        const elementType = unwrapped.elementType;
-        const elementSize = sizeOf(elementType);
-        const stride = roundUp(elementSize, alignmentOf(elementType));
-        const totalSize = sizeOf(schema);
-        if (!Number.isFinite(totalSize)) {
-            return elementSize;
-        }
-        return stride > elementSize ? elementSize : totalSize;
-    }
-    return sizeOf(schema);
-}
 /**
  * A function that retrieves offset and information for a specific primitive within a data schema.
  * Example usage:
@@ -209,10 +287,11 @@ function getRootContiguous(schema) {
  * @returns An object containing the offset and contiguous byte information.
  */
 export function memoryLayoutOf(schema, accessor) {
+    throwIfLoose(undecorate(schema));
     if (!accessor) {
         return {
             offset: 0,
-            contiguous: getRootContiguous(schema),
+            contiguous: getLongestContiguousPrefix(schema),
         };
     }
     const proxy = createOffsetProxy(schema);

package/data/ref.d.ts

@@ -1,5 +1,5 @@
-import { $internal, $ownSnippet, $resolve } from '../shared/symbols.ts';
-import type { DualFn, SelfResolvable } from '../types.ts';
+import { $comptimeValueOf, $internal, $ownSnippet, $resolve } from '../shared/symbols.ts';
+import type { ComptimeValue, DualFn, SelfResolvable, WithComptimeValue } from '../types.ts';
 import { type ResolvedSnippet, type Snippet } from './snippet.ts';
 import { type Ptr } from './wgslTypes.ts';
 interface ref<T> {
@@ -38,12 +38,19 @@ export declare function INTERNAL_createRef<T>(value: T): ref<T>;
  * generating shader code can check if the value of a snippet is
  * an instance of `RefOperator`, and act accordingly.
  */
-export declare class RefOperator implements SelfResolvable {
-    #private;
+export declare class RefOperator implements SelfResolvable, WithComptimeValue {
     readonly [$internal]: true;
     readonly snippet: Snippet;
-    constructor(snippet: Snippet, ptrType: Ptr | undefined);
+    readonly ptrType: Ptr;
+    constructor(snippet: Snippet, ptrType: Ptr);
+    /**
+     * Whether `snippet` refers to an existing value in memory. If not (e.g. `d.ref(42)`),
+     * the ref has to be stored in a variable (`const life = d.ref(42)`) before it can be used.
+     */
+    get addressable(): boolean;
     get [$ownSnippet](): Snippet;
+    toString(): string;
+    [$comptimeValueOf](): ComptimeValue;
     [$resolve](): ResolvedSnippet;
 }
 export declare function derefSnippet(snippet: Snippet): Snippet;

package/data/ref.js

@@ -1,11 +1,13 @@
 import { stitch } from "../core/resolve/stitch.js";
+import { concretize } from "../tgsl/generationHelpers.js";
+import { stringifySnippet } from "../tgsl/stringifySnippet.js";
 import { WgslTypeError } from "../errors.js";
 import { setName } from "../shared/meta.js";
-import { $gpuCallable, $internal, $ownSnippet, $resolve } from "../shared/symbols.js";
+import { $comptimeValueOf, $gpuCallable, $internal, $ownSnippet, $resolve, } from "../shared/symbols.js";
 import { UnknownData } from "./dataTypes.js";
-import { createPtrFromOrigin, explicitFrom } from "./ptr.js";
-import { isStoredInMemory, snip, withDataType, } from "./snippet.js";
-import { isNaturallyEphemeral, isPtr } from "./wgslTypes.js";
+import { createPtrFromOrigin, explicitFrom, ptrFn } from "./ptr.js";
+import { isAddressableOrigin, isStoredInMemory, snip, withDataType, } from "./snippet.js";
+import { isNaturallyEphemeral, isPtr, isVoid } from "./wgslTypes.js";
 export const _ref = (() => {
     const impl = ((value) => INTERNAL_createRef(value));
     setName(impl, 'ref');
@@ -14,20 +16,20 @@ export const _ref = (() => {
     impl[$gpuCallable] = {
         call(ctx, [value]) {
             if (value.origin === 'argument') {
-                throw new WgslTypeError(stitch `d.ref(${value}) is illegal, cannot take a reference of an argument. Copy the value first, and take a reference of the copy.`);
+                throw new WgslTypeError(`d.ref(${stringifySnippet(value)}) is illegal, cannot take a reference of an argument. Copy the value first, and take a reference of the copy.`);
             }
             if (value.origin === 'constant-immutable-def' || value.origin === 'runtime-immutable-def') {
                 const typeStr = ctx.resolve(value.dataType).value;
-                throw new WgslTypeError(stitch `d.ref(${value}) is illegal, cannot take a reference to a constant.
+                throw new WgslTypeError(`d.ref(${stringifySnippet(value)}) is illegal, cannot take a reference to a constant.
 -----
-- Try 'd.ref(${typeStr}(${value}));' instead to create a new referencable value.
+- Try 'd.ref(${typeStr}(${stringifySnippet(value)}));' instead to create a new referencable value.
 -----`);
             }
             if (isStoredInMemory(value) && isNaturallyEphemeral(value.dataType)) {
                 const typeStr = ctx.resolve(value.dataType).value;
-                throw new WgslTypeError(stitch `d.ref(${value}) is illegal, cannot take a reference to a scalar value.
+                throw new WgslTypeError(`d.ref(${stringifySnippet(value)}) is illegal, cannot take a reference to a scalar value.
 -----
-- Try 'd.ref(${typeStr}(${value}));' instead to create a new referencable scalar.
+- Try 'd.ref(${typeStr}(${stringifySnippet(value)}));' instead to create a new referencable scalar.
 -----`);
             }
             if (isPtr(value.dataType)) {
@@ -35,17 +37,23 @@ export const _ref = (() => {
                 // made by assigning a reference to a `const`.
                 return withDataType(explicitFrom(value.dataType), value);
             }
+            if (value.dataType === UnknownData || isVoid(value.dataType)) {
+                throw new WgslTypeError(`d.ref(${stringifySnippet(value)}) is illegal, cannot determine the WGSL type of '${stringifySnippet(value)}'.`);
+            }
             /**
-             * Pointer type only exists if the ref was created from a reference (buttery-butter).
+             * The value is addressable only if the ref was created from a reference (buttery-butter).
              *
              * @example
              * ```ts
-             * const life = ref(42); // created from a value
+             * const life = ref(42); // created from a value, has to be stored in a variable
              * const boid = ref(layout.$.boids[0]); // created from a reference
              * ```
              */
-            const ptrType = createPtrFromOrigin(value.origin, value.dataType);
-            return snip(new RefOperator(value, ptrType), ptrType ?? UnknownData, 
+            const ptrType = createPtrFromOrigin(value.origin, value.dataType) ??
+                // Values that are not addressable become addressable once stored in a
+                // function-scope variable (`const life = d.ref(42)`), so that's the type they get.
+                ptrFn(concretize(value.dataType));
+            return snip(new RefOperator(value, ptrType), ptrType, 
             /* origin */ 'runtime', value.possibleSideEffects);
         },
     };
@@ -108,23 +116,38 @@ export function INTERNAL_createRef(value) {
 export class RefOperator {
     [$internal];
     snippet;
-    #ptrType;
+    ptrType;
     constructor(snippet, ptrType) {
         this[$internal] = true;
         this.snippet = snippet;
-        this.#ptrType = ptrType;
+        this.ptrType = ptrType;
+    }
+    /**
+     * Whether `snippet` refers to an existing value in memory. If not (e.g. `d.ref(42)`),
+     * the ref has to be stored in a variable (`const life = d.ref(42)`) before it can be used.
+     */
+    get addressable() {
+        return isAddressableOrigin(this.snippet.origin);
     }
     get [$ownSnippet]() {
-        if (!this.#ptrType) {
-            throw new Error(stitch `Cannot take a reference of ${this.snippet}`);
-        }
-        return snip(this, this.#ptrType, this.snippet.origin, this.snippet.possibleSideEffects);
+        return snip(this, this.ptrType, this.snippet.origin, this.snippet.possibleSideEffects);
+    }
+    toString() {
+        return `d.ref(${stringifySnippet(this.snippet)})`;
+    }
+    [$comptimeValueOf]() {
+        // References only exist in the generated shader code
+        return { comptime: false };
     }
     [$resolve]() {
-        if (!this.#ptrType) {
-            throw new Error(stitch `Cannot take a reference of ${this.snippet}`);
+        if (!this.addressable) {
+            const valueStr = stringifySnippet(this.snippet);
+            throw new WgslTypeError(`d.ref(${valueStr}) has to be stored in a variable before use, since '${valueStr}' is not an existing value that can be referenced.
+-----
+- Try 'const ref = d.ref(${valueStr});', and use 'ref' instead.
+-----`);
         }
-        return snip(stitch `(&${this.snippet})`, this.#ptrType, this.snippet.origin, this.snippet.possibleSideEffects);
+        return snip(stitch `(&${this.snippet})`, this.ptrType, this.snippet.origin, this.snippet.possibleSideEffects);
     }
 }
 export function derefSnippet(snippet) {
@@ -133,7 +156,11 @@ export function derefSnippet(snippet) {
     }
     const innerType = snippet.dataType.inner;
     if (snippet.value instanceof RefOperator) {
-        return snip(stitch `${snippet.value.snippet}`, innerType, snippet.origin, snippet.possibleSideEffects);
+        // Dereferencing gives back the value the ref was created from, along with its origin.
+        // For non-addressable refs (e.g. `d.ref(1)`), that makes the result a non-reference,
+        // which in turn disallows mutating it (e.g. `d.ref(1).$ = 2`).
+        const inner = snippet.value.snippet;
+        return snip(stitch `${inner}`, innerType, inner.origin, snippet.possibleSideEffects);
     }
     return snip(stitch `(*${snippet})`, innerType, snippet.origin, snippet.possibleSideEffects);
 }

package/data/snippet.d.ts

@@ -62,7 +62,14 @@ export declare const originToPtrParams: {
     };
 };
 export type OriginToPtrParams = typeof originToPtrParams;
+/**
+ * Whether values of this origin can have their address taken.
+ */
 export declare function isAddressableOrigin(origin: Origin): origin is keyof OriginToPtrParams;
+/**
+ * Whether values of this origin can be mutated.
+ */
+export declare function isMutableOrigin(origin: Origin): boolean;
 export interface Snippet {
     readonly value: unknown;
     /**