typegpu 0.12.6 → 0.12.8

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

@@ -4,10 +4,17 @@ import type { InferPatch } from '../shared/repr.ts';
 export interface WriteInstruction {
     data: Uint8Array<ArrayBuffer>;
     gpuOffset: number;
+    /** How many bytes to upload. Can be larger than `data`, e.g. to cover trailing padding. */
+    uploadSize: number;
 }
 /**
  * Converts `{idx, value}[]` sparse arrays into `Record<number, T>` format.
  */
 export declare function convertPartialToPatch(schema: wgsl.BaseData, data: unknown): unknown;
-export declare function getPatchInstructions<TData extends wgsl.BaseData>(schema: TData, data: unknown, targetBuffer?: ArrayBuffer): WriteInstruction[];
+/**
+ * @param validateRange Called for every byte range that is about to be written, before any data
+ *   is written into `targetBuffer`. Returns how many bytes to upload for that range.
+ *   Throwing from it leaves `targetBuffer` untouched.
+ */
+export declare function getPatchInstructions<TData extends wgsl.BaseData>(schema: TData, data: unknown, targetBuffer?: ArrayBuffer, validateRange?: (start: number, end: number) => number): WriteInstruction[];
 export declare function patchArrayBuffer<T extends BaseData>(buffer: ArrayBuffer, schema: T, data: InferPatch<T>): void;

package/data/partialIO.js

@@ -37,7 +37,12 @@ export function convertPartialToPatch(schema, data) {
     return data;
 }
 const isLittleEndian = getSystemEndianness() === 'little';
-export function getPatchInstructions(schema, data, targetBuffer) {
+/**
+ * @param validateRange Called for every byte range that is about to be written, before any data
+ *   is written into `targetBuffer`. Returns how many bytes to upload for that range.
+ *   Throwing from it leaves `targetBuffer` untouched.
+ */
+export function getPatchInstructions(schema, data, targetBuffer, validateRange) {
     const totalSize = sizeOf(schema);
     if (totalSize === 0 || data === undefined || data === null) {
         return [];
@@ -46,6 +51,8 @@ export function getPatchInstructions(schema, data, targetBuffer) {
     const writer = new BufferWriter(buf);
     const compiledView = new DataView(buf);
     const segments = [];
+    // Deferred until every range is validated
+    const pendingWrites = [];
     function collect(node, value, offset, padding) {
         if (value === undefined || value === null) {
             return;
@@ -67,7 +74,9 @@ export function getPatchInstructions(schema, data, targetBuffer) {
             const elementPadding = elementSize - sizeOf(arrSchema.elementType);
             if (ArrayBuffer.isView(value)) {
                 const copyLen = Math.min(value.byteLength, arrSchema.elementCount * elementSize);
-                new Uint8Array(buf, offset, copyLen).set(new Uint8Array(value.buffer, value.byteOffset, copyLen));
+                pendingWrites.push(() => {
+                    new Uint8Array(buf, offset, copyLen).set(new Uint8Array(value.buffer, value.byteOffset, copyLen));
+                });
                 segments.push({ start: offset, end: offset + copyLen, padding });
                 return;
             }
@@ -88,17 +97,19 @@ export function getPatchInstructions(schema, data, targetBuffer) {
         }
         const leafSize = sizeOf(node);
         const compiledWriter = getCompiledWriter(node);
-        if (compiledWriter) {
-            compiledWriter(compiledView, offset, value, isLittleEndian, offset + leafSize);
-        }
-        else {
-            writer.seekTo(offset);
-            writeData(writer, node, value);
-        }
+        pendingWrites.push(() => {
+            if (compiledWriter) {
+                compiledWriter(compiledView, offset, value, isLittleEndian, offset + leafSize);
+            }
+            else {
+                writer.seekTo(offset);
+                writeData(writer, node, value);
+            }
+        });
         segments.push({ start: offset, end: offset + leafSize, padding });
     }
     collect(schema, data, 0);
-    const instructions = [];
+    const runs = [];
     let run = null;
     for (const seg of segments) {
         if (run && seg.start === run.end + (run.padding ?? 0)) {
@@ -106,21 +117,27 @@ export function getPatchInstructions(schema, data, targetBuffer) {
         }
         else {
             if (run) {
-                instructions.push({
-                    gpuOffset: run.start,
-                    data: new Uint8Array(buf, run.start, run.end - run.start).slice(),
-                });
+                runs.push(run);
             }
             run = seg;
         }
     }
     if (run) {
-        instructions.push({
-            gpuOffset: run.start,
-            data: new Uint8Array(buf, run.start, run.end - run.start).slice(),
-        });
+        runs.push(run);
+    }
+    const uploads = runs.map(({ start, end }) => ({
+        start,
+        end,
+        uploadSize: validateRange?.(start, end) ?? end - start,
+    }));
+    for (const write of pendingWrites) {
+        write();
     }
-    return instructions;
+    return uploads.map(({ start, end, uploadSize }) => ({
+        gpuOffset: start,
+        data: new Uint8Array(buf, start, end - start).slice(),
+        uploadSize,
+    }));
 }
 export function patchArrayBuffer(buffer, schema, data) {
     const instructions = getPatchInstructions(schema, data, buffer);

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 { isAlias, 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 (isAlias(value) && isNaturallyEphemeral(value.dataType)) {
+            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);
 }