typegpu 0.10.1 → 0.11.0-rc.1

package/data/numeric.js

@@ -0,0 +1,221 @@
+import { $internal } from "../shared/symbols.js";
+import { callableSchema } from "../core/function/createCallableSchema.js";
+//#region src/data/numeric.ts
+const abstractInt = {
+	[$internal]: {},
+	type: "abstractInt",
+	toString() {
+		return "abstractInt";
+	}
+};
+const abstractFloat = {
+	[$internal]: {},
+	type: "abstractFloat",
+	toString() {
+		return "abstractFloat";
+	}
+};
+const boolCast = callableSchema({
+	name: "bool",
+	schema: () => bool,
+	argTypes: (arg) => arg ? [arg] : [],
+	normalImpl(v) {
+		if (v === void 0) return false;
+		if (typeof v === "boolean") return v;
+		return !!v;
+	},
+	codegenImpl: (ctx, args) => ctx.gen.typeInstantiation(bool, args)
+});
+/**
+* A schema that represents a boolean value. (equivalent to `bool` in WGSL)
+*
+* Can also be called to cast a value to a bool in accordance with WGSL casting rules.
+*
+* @example
+* const value = bool(); // false
+* @example
+* const value = bool(0); // false
+* @example
+* const value = bool(-0); // false
+* @example
+* const value = bool(21.37); // true
+*/
+const bool = Object.assign(boolCast, {
+	[$internal]: {},
+	type: "bool"
+});
+const u32Cast = callableSchema({
+	name: "u32",
+	schema: () => u32,
+	argTypes: (arg) => arg ? [arg] : [],
+	normalImpl(v) {
+		if (v === void 0) return 0;
+		if (typeof v === "boolean") return v ? 1 : 0;
+		if (!Number.isInteger(v)) {
+			const truncated = Math.trunc(v);
+			if (truncated < 0) return 0;
+			if (truncated > 4294967295) return 4294967295;
+			return truncated;
+		}
+		return (v & 4294967295) >>> 0;
+	},
+	codegenImpl: (ctx, args) => ctx.gen.typeInstantiation(u32, args)
+});
+/**
+* A schema that represents an unsigned 32-bit integer value. (equivalent to `u32` in WGSL)
+*
+* Can also be called to cast a value to an u32 in accordance with WGSL casting rules.
+*
+* @example
+* const value = u32(); // 0
+* @example
+* const value = u32(7); // 7
+* @example
+* const value = u32(3.14); // 3
+* @example
+* const value = u32(-1); // 4294967295
+* @example
+* const value = u32(-3.1); // 0
+*/
+const u32 = Object.assign(u32Cast, {
+	[$internal]: {},
+	type: "u32"
+});
+const i32Cast = callableSchema({
+	name: "i32",
+	schema: () => i32,
+	argTypes: (arg) => arg ? [arg] : [],
+	normalImpl(v) {
+		if (v === void 0) return 0;
+		if (typeof v === "boolean") return v ? 1 : 0;
+		return v | 0;
+	},
+	codegenImpl: (ctx, args) => ctx.gen.typeInstantiation(i32, args)
+});
+const u16 = {
+	[$internal]: {},
+	type: "u16"
+};
+/**
+* A schema that represents a signed 32-bit integer value. (equivalent to `i32` in WGSL)
+*
+* Can also be called to cast a value to an i32 in accordance with WGSL casting rules.
+*
+* @example
+* const value = i32(); // 0
+* @example
+* const value = i32(3.14); // 3
+* @example
+* const value = i32(-3.9); // -3
+* @example
+* const value = i32(10000000000) // 1410065408
+*/
+const i32 = Object.assign(i32Cast, {
+	[$internal]: {},
+	type: "i32"
+});
+const f32Cast = callableSchema({
+	name: "f32",
+	schema: () => f32,
+	argTypes: (arg) => arg ? [arg] : [],
+	normalImpl(v) {
+		if (v === void 0) return 0;
+		if (typeof v === "boolean") return v ? 1 : 0;
+		return Math.fround(v);
+	},
+	codegenImpl: (ctx, args) => ctx.gen.typeInstantiation(f32, args)
+});
+/**
+* A schema that represents a 32-bit float value. (equivalent to `f32` in WGSL)
+*
+* Can also be called to cast a value to an f32.
+*
+* @example
+* const value = f32(); // 0
+* @example
+* const value = f32(1.23); // 1.23
+* @example
+* const value = f32(true); // 1
+*/
+const f32 = Object.assign(f32Cast, {
+	[$internal]: {},
+	type: "f32"
+});
+const buf32 = /* @__PURE__ */ new ArrayBuffer(4);
+const f32arr = new Float32Array(buf32);
+const u32arr = new Uint32Array(buf32);
+/**
+* Convert a JavaScript number (treated as float32) to **binary16** bit pattern.
+* @param x 32-bit floating-point value
+* @returns 16-bit half-precision encoding (stored in a JS number)
+*/
+function toHalfBits(x) {
+	f32arr[0] = x;
+	const bits = u32arr[0];
+	const sign = bits >>> 31 & 1;
+	let exp = bits >>> 23 & 255;
+	let mant = bits & 8388607;
+	if (exp === 255) return sign << 15 | 31744 | (mant ? 512 : 0);
+	exp = exp - 127 + 15;
+	if (exp <= 0) {
+		if (exp < -10) return sign << 15;
+		mant = (mant | 8388608) >> 1 - exp;
+		mant = mant + 4096 >> 13;
+		return sign << 15 | mant;
+	}
+	if (exp >= 31) return sign << 15 | 31744;
+	mant = mant + 4096;
+	if (mant & 8388608) {
+		mant = 0;
+		++exp;
+		if (exp >= 31) return sign << 15 | 31744;
+	}
+	return sign << 15 | exp << 10 | mant >> 13;
+}
+/**
+* Convert a **binary16** encoded bit pattern back to JavaScript number.
+* @param h 16-bit half-precision bits
+* @returns JavaScript number (64-bit float) with same numerical value
+*/
+function fromHalfBits(h) {
+	const sign = h & 32768 ? -1 : 1;
+	const exp = h >> 10 & 31;
+	const mant = h & 1023;
+	if (exp === 0) return mant ? sign * mant * 2 ** -24 : sign * 0;
+	if (exp === 31) return mant ? NaN : sign === 1 ? Number.POSITIVE_INFINITY : Number.NEGATIVE_INFINITY;
+	return sign * (1 + mant / 1024) * 2 ** (exp - 15);
+}
+function roundToF16(x) {
+	return fromHalfBits(toHalfBits(x));
+}
+const f16Cast = callableSchema({
+	name: "f16",
+	schema: () => f16,
+	argTypes: (arg) => arg ? [arg] : [],
+	normalImpl(v) {
+		if (v === void 0) return 0;
+		if (typeof v === "boolean") return v ? 1 : 0;
+		return roundToF16(v);
+	},
+	codegenImpl: (ctx, args) => ctx.gen.typeInstantiation(f16, args)
+});
+/**
+* A schema that represents a 16-bit float value. (equivalent to `f16` in WGSL)
+*
+* Can also be called to cast a value to an f16.
+*
+* @example
+* const value = f16(); // 0
+* @example
+* const value = f32(1.23); // 1.23
+* @example
+* const value = f16(true); // 1
+* @example
+* const value = f16(21877.5); // 21872
+*/
+const f16 = Object.assign(f16Cast, {
+	[$internal]: {},
+	type: "f16"
+});
+//#endregion
+export { abstractFloat, abstractInt, bool, f16, f32, i32, u16, u32 };

package/data/offsetUtils.d.ts

@@ -0,0 +1,33 @@
+import { BaseData } from "./wgslTypes.js";
+import { Infer } from "../shared/repr.js";
+
+//#region src/data/offsetUtils.d.ts
+/**
+ * Interface containing information about the offset and the available contiguous after a selected primitive.
+ */
+interface PrimitiveOffsetInfo {
+  /** The byte offset of the primitive within the buffer. */
+  offset: number;
+  /** The number of contiguous bytes available from the offset. */
+  contiguous: number;
+}
+/**
+ * A function that retrieves offset and information for a specific primitive within a data schema.
+ * Example usage:
+ * ```ts
+ * const Boid = d.struct({
+ *  position: d.vec3f,
+ *  velocity: d.vec3f,
+ * });
+ * const memLayout = d.memoryLayoutOf(Boid, (b) => b.velocity.y);
+ * console.log(memLayout.offset); // Byte offset of velocity.y within Boid (here 20 bytes)
+ * console.log(memLayout.contiguous); // Contiguous bytes available from that offset (here 8 bytes)
+ * ```
+ *
+ * @param schema - The data schema to analyze.
+ * @param accessor - Optional function that accesses a specific element within the schema. If omitted, uses the root offset (0).
+ * @returns An object containing the offset and contiguous byte information.
+ */
+declare function memoryLayoutOf<T extends BaseData>(schema: T, accessor?: (proxy: Infer<T>) => unknown): PrimitiveOffsetInfo;
+//#endregion
+export { PrimitiveOffsetInfo, memoryLayoutOf };

package/data/offsetUtils.js

@@ -0,0 +1,165 @@
+import { isVec, isWgslArray, isWgslStruct } from "./wgslTypes.js";
+import { undecorate } from "./dataTypes.js";
+import { alignmentOf } from "./alignmentOf.js";
+import { roundUp } from "../mathUtils.js";
+import { sizeOf } from "./sizeOf.js";
+import { offsetsForProps } from "./offsets.js";
+import { isContiguous } from "./isContiguous.js";
+import { getLongestContiguousPrefix } from "./getLongestContiguousPrefix.js";
+//#region src/data/offsetUtils.ts
+const OFFSET_MARKER = Symbol("indirectOffset");
+const CONTIGUOUS_MARKER = Symbol("indirectContiguous");
+function isOffsetProxy(value) {
+	return typeof value === "object" && value !== null && OFFSET_MARKER in value && CONTIGUOUS_MARKER in value;
+}
+function scalarNode(offset, contiguous) {
+	return {
+		[OFFSET_MARKER]: offset,
+		[CONTIGUOUS_MARKER]: contiguous
+	};
+}
+function getMarker(target, prop) {
+	if (prop === OFFSET_MARKER) return target[OFFSET_MARKER];
+	if (prop === CONTIGUOUS_MARKER) return target[CONTIGUOUS_MARKER];
+}
+function makeProxy(schema, baseOffset, contiguous = sizeOf(schema)) {
+	const unwrapped = undecorate(schema);
+	const vecComponentCount = isVec(unwrapped) ? unwrapped.componentCount : void 0;
+	if (vecComponentCount !== void 0) {
+		const componentSize = sizeOf(unwrapped.primitive);
+		return makeVecProxy(scalarNode(baseOffset, contiguous), componentSize, vecComponentCount);
+	}
+	if (isWgslStruct(unwrapped)) return makeStructProxy(unwrapped, scalarNode(baseOffset, contiguous));
+	if (isWgslArray(unwrapped)) return makeArrayProxy(unwrapped, scalarNode(baseOffset, contiguous));
+	return scalarNode(baseOffset, contiguous);
+}
+function createOffsetProxy(schema, baseOffset = 0) {
+	return makeProxy(schema, baseOffset, sizeOf(schema));
+}
+function makeVecProxy(target, componentSize, componentCount) {
+	const baseOffset = target[OFFSET_MARKER];
+	return new Proxy(target, { get(t, prop) {
+		const marker = getMarker(t, prop);
+		if (marker !== void 0) 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) return;
+		const byteOffset = idx * componentSize;
+		const contiguous = Math.max(0, t[CONTIGUOUS_MARKER] - byteOffset);
+		return scalarNode(baseOffset + byteOffset, contiguous);
+	} });
+}
+function makeArrayProxy(array, target) {
+	const elementType = array.elementType;
+	const elementSize = sizeOf(elementType);
+	const stride = roundUp(elementSize, alignmentOf(elementType));
+	const hasPadding = stride > elementSize;
+	return new Proxy(target, { get(t, prop) {
+		const marker = getMarker(t, prop);
+		if (marker !== void 0) return marker;
+		if (prop === "length") return array.elementCount;
+		if (typeof prop !== "string") return;
+		const index = Number(prop);
+		if (!Number.isInteger(index) || index < 0 || index >= array.elementCount) return;
+		const elementOffset = index * stride;
+		const remainingFromHere = !isContiguous(elementType) ? elementSize + getLongestContiguousPrefix(elementType) : Math.max(0, t[CONTIGUOUS_MARKER] - elementOffset);
+		const childContiguous = hasPadding ? Math.min(remainingFromHere, elementSize) : remainingFromHere;
+		return makeProxy(elementType, t[OFFSET_MARKER] + elementOffset, childContiguous);
+	} });
+}
+function makeStructProxy(struct, target) {
+	const offsets = offsetsForProps(struct);
+	const propTypes = struct.propTypes;
+	const propNames = Object.keys(propTypes);
+	const meta = /* @__PURE__ */ 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;
+		const info = offsets[name];
+		const padding = info.padding ?? 0;
+		const typeContiguous = isContiguous(type);
+		if (!(i === propNames.length - 1 || padding > 0 || !typeContiguous)) 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
+			});
+		}
+		runStart = i + 1;
+	}
+	return new Proxy(target, { get(t, prop) {
+		const marker = getMarker(t, prop);
+		if (marker !== void 0) return marker;
+		if (typeof prop !== "string") return;
+		const m = meta.get(prop);
+		if (!m) return;
+		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) return;
+		return makeProxy(propSchema, t[OFFSET_MARKER] + m.offset, sizeOf(struct) === m.runEnd ? remainingFromHere : localLimit);
+	} });
+}
+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;
+			if (i === propNames.length - 1 || padding > 0) 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:
+* ```ts
+* const Boid = d.struct({
+*  position: d.vec3f,
+*  velocity: d.vec3f,
+* });
+* const memLayout = d.memoryLayoutOf(Boid, (b) => b.velocity.y);
+* console.log(memLayout.offset); // Byte offset of velocity.y within Boid (here 20 bytes)
+* console.log(memLayout.contiguous); // Contiguous bytes available from that offset (here 8 bytes)
+* ```
+*
+* @param schema - The data schema to analyze.
+* @param accessor - Optional function that accesses a specific element within the schema. If omitted, uses the root offset (0).
+* @returns An object containing the offset and contiguous byte information.
+*/
+function memoryLayoutOf(schema, accessor) {
+	if (!accessor) return {
+		offset: 0,
+		contiguous: getRootContiguous(schema)
+	};
+	const result = accessor(createOffsetProxy(schema));
+	if (isOffsetProxy(result)) return {
+		offset: result[OFFSET_MARKER],
+		contiguous: result[CONTIGUOUS_MARKER]
+	};
+	throw new Error("memoryLayoutOf: accessor did not return a schema element. Make sure the accessor navigates to a field or element of the schema (e.g. `(s) => s.position.x`).");
+}
+//#endregion
+export { memoryLayoutOf };

package/data/offsets.js

@@ -0,0 +1,34 @@
+import { isUnstruct } from "./dataTypes.js";
+import { alignmentOf, customAlignmentOf } from "./alignmentOf.js";
+import { roundUp } from "../mathUtils.js";
+import { sizeOf } from "./sizeOf.js";
+import alignIO from "./alignIO.js";
+import { Measurer } from "typed-binary";
+//#region src/data/offsets.ts
+const cachedOffsets = /* @__PURE__ */ new WeakMap();
+function offsetsForProps(struct) {
+	const cached = cachedOffsets.get(struct);
+	if (cached) return cached;
+	const measurer = new Measurer();
+	const offsets = {};
+	let lastEntry;
+	for (const key in struct.propTypes) {
+		const prop = struct.propTypes[key];
+		if (prop === void 0) throw new Error(`Property ${key} is undefined in struct`);
+		const beforeAlignment = measurer.size;
+		alignIO(measurer, isUnstruct(struct) ? customAlignmentOf(prop) : alignmentOf(prop));
+		if (lastEntry) lastEntry.padding = measurer.size - beforeAlignment;
+		const propSize = sizeOf(prop);
+		offsets[key] = {
+			offset: measurer.size,
+			size: propSize
+		};
+		lastEntry = offsets[key];
+		measurer.add(propSize);
+	}
+	if (lastEntry) lastEntry.padding = roundUp(sizeOf(struct), alignmentOf(struct)) - measurer.size;
+	cachedOffsets.set(struct, offsets);
+	return offsets;
+}
+//#endregion
+export { offsetsForProps };

package/data/partialIO.js

@@ -0,0 +1,113 @@
+import { isWgslArray, isWgslStruct } from "./wgslTypes.js";
+import { isDisarray, isUnstruct } from "./dataTypes.js";
+import { alignmentOf } from "./alignmentOf.js";
+import { roundUp } from "../mathUtils.js";
+import { sizeOf } from "./sizeOf.js";
+import { offsetsForProps } from "./offsets.js";
+import { getCompiledWriter } from "./compiledIO.js";
+import { writeData } from "./dataIO.js";
+import { BufferWriter, getSystemEndianness } from "typed-binary";
+//#region src/data/partialIO.ts
+/**
+* Converts `{idx, value}[]` sparse arrays into `Record<number, T>` format.
+*/
+function convertPartialToPatch(schema, data) {
+	if (data === void 0 || data === null) return data;
+	if (isWgslStruct(schema) || isUnstruct(schema)) {
+		const result = {};
+		const record = data;
+		for (const key of Object.keys(schema.propTypes)) {
+			const subSchema = schema.propTypes[key];
+			const value = record[key];
+			if (value !== void 0 && subSchema) result[key] = convertPartialToPatch(subSchema, value);
+		}
+		return result;
+	}
+	if (isWgslArray(schema) || isDisarray(schema)) {
+		const arrSchema = schema;
+		const result = {};
+		for (const { idx, value } of data) result[idx] = convertPartialToPatch(arrSchema.elementType, value);
+		return result;
+	}
+	return data;
+}
+const isLittleEndian = getSystemEndianness() === "little";
+function getPatchInstructions(schema, data, targetBuffer) {
+	const totalSize = sizeOf(schema);
+	if (totalSize === 0 || data === void 0 || data === null) return [];
+	const buf = targetBuffer ?? new ArrayBuffer(totalSize);
+	const writer = new BufferWriter(buf);
+	const compiledView = new DataView(buf);
+	const segments = [];
+	function collect(node, value, offset, padding) {
+		if (value === void 0 || value === null) return;
+		if (isWgslStruct(node) || isUnstruct(node)) {
+			const propOffsets = offsetsForProps(node);
+			for (const [key, propOffset] of Object.entries(propOffsets)) {
+				const childValue = value[key];
+				const subSchema = node.propTypes[key];
+				if (childValue !== void 0 && subSchema) collect(subSchema, childValue, offset + propOffset.offset, propOffset.padding ?? padding);
+			}
+			return;
+		}
+		if (isWgslArray(node) || isDisarray(node)) {
+			const arrSchema = node;
+			const elementSize = roundUp(sizeOf(arrSchema.elementType), alignmentOf(arrSchema.elementType));
+			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));
+				segments.push({
+					start: offset,
+					end: offset + copyLen,
+					padding
+				});
+				return;
+			}
+			if (Array.isArray(value)) {
+				for (let i = 0; i < Math.min(arrSchema.elementCount, value.length); i++) collect(arrSchema.elementType, value[i], offset + i * elementSize, elementPadding);
+				return;
+			}
+			const sparse = value;
+			for (const key of Object.keys(sparse)) {
+				const idx = Number(key);
+				if (!Number.isNaN(idx)) collect(arrSchema.elementType, sparse[key], offset + idx * elementSize, elementPadding);
+			}
+			return;
+		}
+		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);
+		}
+		segments.push({
+			start: offset,
+			end: offset + leafSize,
+			padding
+		});
+	}
+	collect(schema, data, 0);
+	const instructions = [];
+	let run = null;
+	for (const seg of segments) if (run && seg.start === run.end + (run.padding ?? 0)) run = {
+		start: run.start,
+		end: seg.end,
+		padding: seg.padding
+	};
+	else {
+		if (run) instructions.push({
+			gpuOffset: run.start,
+			data: new Uint8Array(buf, run.start, run.end - run.start).slice()
+		});
+		run = seg;
+	}
+	if (run) instructions.push({
+		gpuOffset: run.start,
+		data: new Uint8Array(buf, run.start, run.end - run.start).slice()
+	});
+	return instructions;
+}
+//#endregion
+export { convertPartialToPatch, getPatchInstructions };

package/data/ptr.d.ts

@@ -0,0 +1,11 @@
+import { Ptr, StorableData } from "./wgslTypes.js";
+
+//#region src/data/ptr.d.ts
+declare function ptrFn<T extends StorableData>(inner: T): Ptr<'function', T, 'read-write'>;
+declare function ptrPrivate<T extends StorableData>(inner: T): Ptr<'private', T, 'read-write'>;
+declare function ptrWorkgroup<T extends StorableData>(inner: T): Ptr<'workgroup', T, 'read-write'>;
+declare function ptrStorage<T extends StorableData, TAccess extends 'read' | 'read-write' = 'read'>(inner: T, access?: TAccess): Ptr<'storage', T, TAccess>;
+declare function ptrUniform<T extends StorableData>(inner: T): Ptr<'uniform', T, 'read'>;
+declare function ptrHandle<T extends StorableData>(inner: T): Ptr<'handle', T, 'read'>;
+//#endregion
+export { ptrFn, ptrHandle, ptrPrivate, ptrStorage, ptrUniform, ptrWorkgroup };

package/data/ptr.js

@@ -0,0 +1,44 @@
+import { $internal } from "../shared/symbols.js";
+import { originToPtrParams } from "./snippet.js";
+//#region src/data/ptr.ts
+function ptrFn(inner) {
+	return INTERNAL_createPtr("function", inner, "read-write");
+}
+function ptrPrivate(inner) {
+	return INTERNAL_createPtr("private", inner, "read-write");
+}
+function ptrWorkgroup(inner) {
+	return INTERNAL_createPtr("workgroup", inner, "read-write");
+}
+function ptrStorage(inner, access = "read") {
+	return INTERNAL_createPtr("storage", inner, access);
+}
+function ptrUniform(inner) {
+	return INTERNAL_createPtr("uniform", inner, "read");
+}
+function ptrHandle(inner) {
+	return INTERNAL_createPtr("handle", inner, "read");
+}
+function INTERNAL_createPtr(addressSpace, inner, access, implicit = false) {
+	return {
+		[$internal]: {},
+		type: "ptr",
+		addressSpace,
+		inner,
+		access,
+		implicit,
+		toString: () => `ptr<${addressSpace}, ${inner}, ${access}>`
+	};
+}
+function createPtrFromOrigin(origin, innerDataType) {
+	const ptrParams = originToPtrParams[origin];
+	if (ptrParams) return INTERNAL_createPtr(ptrParams.space, innerDataType, ptrParams.access);
+}
+function implicitFrom(ptr) {
+	return INTERNAL_createPtr(ptr.addressSpace, ptr.inner, ptr.access, true);
+}
+function explicitFrom(ptr) {
+	return INTERNAL_createPtr(ptr.addressSpace, ptr.inner, ptr.access, false);
+}
+//#endregion
+export { createPtrFromOrigin, explicitFrom, implicitFrom, ptrFn, ptrHandle, ptrPrivate, ptrStorage, ptrUniform, ptrWorkgroup };

package/data/ref.d.ts

@@ -0,0 +1,34 @@
+import { $internal } from "../shared/symbols.js";
+import { DualFn } from "../types.js";
+//#region src/data/ref.d.ts
+interface ref<T> {
+  readonly [$internal]: {
+    type: 'ref';
+  };
+  /**
+   * Derefences the reference, and gives access to the underlying value.
+   *
+   * @example ```ts
+   * const boid = Boid({ pos: d.vec3f(3, 2, 1) });
+   * const posRef = d.ref(boid.pos);
+   *
+   * // Actually updates `boid.pos`
+   * posRef.$ = d.vec3f(1, 2, 3);
+   * console.log(boid.pos); // Output: vec3f(1, 2, 3)
+   * ```
+   */
+  $: T;
+}
+/**
+ * A reference to a value `T`. Can be passed to other functions to give them
+ * mutable access to the underlying value.
+ *
+ * Conceptually, it represents a WGSL pointer.
+ */
+type _ref<T> = T extends object ? T & ref<T> : ref<T>;
+type RefFn = DualFn<(<T>(value: T) => _ref<T>)> & {
+  [$internal]: true;
+};
+declare const _ref: RefFn;
+//#endregion
+export { _ref };