typegpu 0.10.0 → 0.10.2

package/tgsl/consoleLog/logGenerator.js

@@ -0,0 +1,86 @@
+import { $internal } from "../../shared/symbols.js";
+import { Void } from "../../data/wgslTypes.js";
+import { UnknownData } from "../../data/dataTypes.js";
+import { snip } from "../../data/snippet.js";
+import { stitch } from "../../core/resolve/stitch.js";
+import { u32 } from "../../data/numeric.js";
+import { struct } from "../../data/struct.js";
+import { concretizeSnippets } from "../generationHelpers.js";
+import { shaderStageSlot } from "../../core/slot/internalSlots.js";
+import { arrayOf } from "../../data/array.js";
+import { atomic } from "../../data/atomic.js";
+import { createLoggingFunction } from "./serializers.js";
+import { supportedLogOps } from "./types.js";
+
+//#region src/tgsl/consoleLog/logGenerator.ts
+const defaultOptions = {
+	logCountLimit: 64,
+	logSizeLimit: 252,
+	messagePrefix: " GPU "
+};
+const fallbackSnippet = snip("/* console.log() */", Void, "runtime");
+var LogGeneratorNullImpl = class {
+	get logResources() {}
+	generateLog() {
+		console.warn("'console.log' is only supported when resolving pipelines.");
+		return fallbackSnippet;
+	}
+};
+var LogGeneratorImpl = class {
+	#options;
+	#logIdToMeta;
+	#firstUnusedId = 1;
+	#indexBuffer;
+	#dataBuffer;
+	constructor(root) {
+		this.#options = {
+			...defaultOptions,
+			...root[$internal].logOptions
+		};
+		this.#logIdToMeta = /* @__PURE__ */ new Map();
+		const SerializedLogData = struct({
+			id: u32,
+			serializedData: arrayOf(u32, Math.ceil(this.#options.logSizeLimit / 4))
+		}).$name("SerializedLogData");
+		this.#dataBuffer = root.createMutable(arrayOf(SerializedLogData, this.#options.logCountLimit)).$name("dataBuffer");
+		this.#indexBuffer = root.createMutable(atomic(u32)).$name("indexBuffer");
+	}
+	/**
+	* Generates all necessary resources for serializing arguments for logging purposes.
+	*
+	* @param ctx Resolution context.
+	* @param args Argument snippets. Snippets of UnknownType will be treated as string literals.
+	* @returns A snippet containing the call to the logging function.
+	*/
+	generateLog(ctx, op, args) {
+		if (shaderStageSlot.$ === "vertex") {
+			console.warn(`'console.${op}' is not supported in vertex shaders.`);
+			return fallbackSnippet;
+		}
+		if (!supportedLogOps.includes(op)) {
+			console.warn(`Unsupported log method '${op}'.`);
+			return fallbackSnippet;
+		}
+		const concreteArgs = concretizeSnippets(args);
+		const id = this.#firstUnusedId++;
+		const nonStringArgs = concreteArgs.filter((e) => e.dataType !== UnknownData);
+		const logFn = createLoggingFunction(id, nonStringArgs.map((e) => e.dataType), this.#dataBuffer, this.#indexBuffer, this.#options);
+		const argTypes = concreteArgs.map((e) => e.dataType === UnknownData ? e.value : e.dataType);
+		this.#logIdToMeta.set(id, {
+			op,
+			argTypes
+		});
+		return snip(stitch`${ctx.resolve(logFn).value}(${nonStringArgs})`, Void, "runtime");
+	}
+	get logResources() {
+		return this.#firstUnusedId === 1 ? void 0 : {
+			dataBuffer: this.#dataBuffer,
+			indexBuffer: this.#indexBuffer,
+			options: this.#options,
+			logIdToMeta: this.#logIdToMeta
+		};
+	}
+};
+
+//#endregion
+export { LogGeneratorImpl, LogGeneratorNullImpl };

package/tgsl/consoleLog/serializers.js

@@ -0,0 +1,225 @@
+import { getName } from "../../shared/meta.js";
+import { isWgslArray, isWgslStruct } from "../../data/wgslTypes.js";
+import { bool, f16, f32, i32, u32 } from "../../data/numeric.js";
+import { vec2b, vec2f, vec2h, vec2i, vec2u, vec3b, vec3f, vec3h, vec3i, vec3u, vec4b, vec4f, vec4h, vec4i, vec4u } from "../../data/vector.js";
+import { sizeOf } from "../../data/sizeOf.js";
+import { mat2x2f, mat3x3f, mat4x4f } from "../../data/matrix.js";
+import { fn } from "../../core/function/tgpuFn.js";
+import { slot } from "../../core/slot/slot.js";
+import { privateVar } from "../../core/variable/tgpuVariable.js";
+
+//#region src/tgsl/consoleLog/serializers.ts
+const dataBlockIndex = privateVar(u32, 0).$name("dataBlockIndex");
+const dataByteIndex = privateVar(u32, 0).$name("dataByteIndex");
+const dataBufferSlot = slot().$name("dataBuffer");
+const nextByteIndex = fn([], u32)`() {
+  let i = dataByteIndex;
+  dataByteIndex = dataByteIndex + 1u;
+  return i;
+}`.$uses({ dataByteIndex }).$name("nextByteIndex");
+const nextU32 = "dataBuffer[dataBlockIndex].serializedData[nextByteIndex()]";
+const serializerMap = {
+	f32: fn([f32])`(n) => {
+  ${nextU32} = bitcast<u32>(n);
+}`,
+	f16: fn([f16])`(n) => {
+  ${nextU32} = pack2x16float(vec2f(f32(n), 0.0));
+}`,
+	i32: fn([i32])`(n) => {
+  ${nextU32} = bitcast<u32>(n);
+}`,
+	u32: fn([u32])`(n) => {
+  ${nextU32} = n;
+}`,
+	bool: fn([bool])`(b) => {
+  ${nextU32} = u32(b);
+}`,
+	vec2f: fn([vec2f])`(v) => {
+  ${nextU32} = bitcast<u32>(v.x);
+  ${nextU32} = bitcast<u32>(v.y);
+}`,
+	vec3f: fn([vec3f])`(v) => {
+  ${nextU32} = bitcast<u32>(v.x);
+  ${nextU32} = bitcast<u32>(v.y);
+  ${nextU32} = bitcast<u32>(v.z);
+}`,
+	vec4f: fn([vec4f])`(v) => {
+  ${nextU32} = bitcast<u32>(v.x);
+  ${nextU32} = bitcast<u32>(v.y);
+  ${nextU32} = bitcast<u32>(v.z);
+  ${nextU32} = bitcast<u32>(v.w);
+}`,
+	vec2h: fn([vec2h])`(v) => {
+  ${nextU32} = pack2x16float(vec2f(f32(v.x), f32(v.y)));
+}`,
+	vec3h: fn([vec3h])`(v) => {
+  ${nextU32} = pack2x16float(vec2f(f32(v.x), f32(v.y)));
+  ${nextU32} = pack2x16float(vec2f(f32(v.z), 0.0));
+}`,
+	vec4h: fn([vec4h])`(v) => {
+  ${nextU32} = pack2x16float(vec2f(f32(v.x), f32(v.y)));
+  ${nextU32} = pack2x16float(vec2f(f32(v.z), f32(v.w)));
+}`,
+	vec2i: fn([vec2i])`(v) => {
+  ${nextU32} = bitcast<u32>(v.x);
+  ${nextU32} = bitcast<u32>(v.y);
+}`,
+	vec3i: fn([vec3i])`(v) => {
+  ${nextU32} = bitcast<u32>(v.x);
+  ${nextU32} = bitcast<u32>(v.y);
+  ${nextU32} = bitcast<u32>(v.z);
+}`,
+	vec4i: fn([vec4i])`(v) => {
+  ${nextU32} = bitcast<u32>(v.x);
+  ${nextU32} = bitcast<u32>(v.y);
+  ${nextU32} = bitcast<u32>(v.z);
+  ${nextU32} = bitcast<u32>(v.w);
+}`,
+	vec2u: fn([vec2u])`(v) => {
+  ${nextU32} = v.x;
+  ${nextU32} = v.y;
+}`,
+	vec3u: fn([vec3u])`(v) => {
+  ${nextU32} = v.x;
+  ${nextU32} = v.y;
+  ${nextU32} = v.z;
+}`,
+	vec4u: fn([vec4u])`(v) => {
+  ${nextU32} = v.x;
+  ${nextU32} = v.y;
+  ${nextU32} = v.z;
+  ${nextU32} = v.w;
+}`,
+	"vec2<bool>": fn([vec2b])`(v) => {
+  ${nextU32} = u32(v.x);
+  ${nextU32} = u32(v.y);
+}`,
+	"vec3<bool>": fn([vec3b])`(v) => {
+  ${nextU32} = u32(v.x);
+  ${nextU32} = u32(v.y);
+  ${nextU32} = u32(v.z);
+}`,
+	"vec4<bool>": fn([vec4b])`(v) => {
+  ${nextU32} = u32(v.x);
+  ${nextU32} = u32(v.y);
+  ${nextU32} = u32(v.z);
+  ${nextU32} = u32(v.w);
+}`,
+	mat2x2f: fn([mat2x2f])`(m) => {
+  ${nextU32} = bitcast<u32>(m[0][0]);
+  ${nextU32} = bitcast<u32>(m[0][1]);
+  ${nextU32} = bitcast<u32>(m[1][0]);
+  ${nextU32} = bitcast<u32>(m[1][1]);
+}`,
+	mat3x3f: fn([mat3x3f])`(m) => {
+  ${nextU32} = bitcast<u32>(m[0][0]);
+  ${nextU32} = bitcast<u32>(m[0][1]);
+  ${nextU32} = bitcast<u32>(m[0][2]);
+  ${nextU32} = 0u;
+  ${nextU32} = bitcast<u32>(m[1][0]);
+  ${nextU32} = bitcast<u32>(m[1][1]);
+  ${nextU32} = bitcast<u32>(m[1][2]);
+  ${nextU32} = 0u;
+  ${nextU32} = bitcast<u32>(m[2][0]);
+  ${nextU32} = bitcast<u32>(m[2][1]);
+  ${nextU32} = bitcast<u32>(m[2][2]);
+  ${nextU32} = 0u;
+}`,
+	mat4x4f: fn([mat4x4f])`(m) => {
+  ${nextU32} = bitcast<u32>(m[0][0]);
+  ${nextU32} = bitcast<u32>(m[0][1]);
+  ${nextU32} = bitcast<u32>(m[0][2]);
+  ${nextU32} = bitcast<u32>(m[0][3]);
+  ${nextU32} = bitcast<u32>(m[1][0]);
+  ${nextU32} = bitcast<u32>(m[1][1]);
+  ${nextU32} = bitcast<u32>(m[1][2]);
+  ${nextU32} = bitcast<u32>(m[1][3]);
+  ${nextU32} = bitcast<u32>(m[2][0]);
+  ${nextU32} = bitcast<u32>(m[2][1]);
+  ${nextU32} = bitcast<u32>(m[2][2]);
+  ${nextU32} = bitcast<u32>(m[2][3]);
+  ${nextU32} = bitcast<u32>(m[3][0]);
+  ${nextU32} = bitcast<u32>(m[3][1]);
+  ${nextU32} = bitcast<u32>(m[3][2]);
+  ${nextU32} = bitcast<u32>(m[3][3]);
+}`
+};
+for (const [name, serializer] of Object.entries(serializerMap)) serializer.$name(`serialize${name[0].toLocaleUpperCase()}${name.slice(1)}`).$uses({
+	dataBlockIndex,
+	nextByteIndex,
+	dataBuffer: dataBufferSlot
+});
+function generateHeader(argTypes) {
+	return `(${argTypes.map((_, i) => `_arg_${i}`).join(", ")})`;
+}
+/**
+* Returns a serializer TGPU function for a given WGSL data type.
+* If the data type is a base type, one of the preexisting functions (with the `dataBufferSlot` filled) is returned.
+* Otherwise, a new function is generated.
+*
+* @param dataType - The WGSL data type descriptor to return a serializer for
+* @param dataBuffer - A buffer to store serialized log call data (a necessary external for the returned function)
+*/
+function getSerializer(dataType, dataBuffer) {
+	const maybeSerializer = serializerMap[dataType.type];
+	if (maybeSerializer) return maybeSerializer.with(dataBufferSlot, dataBuffer);
+	if (isWgslStruct(dataType)) {
+		const props = Object.keys(dataType.propTypes);
+		const propsSerializer = createCompoundSerializer(Object.values(dataType.propTypes), dataBuffer);
+		return fn([dataType])`(arg) {\n  propsSerializer(${props.map((prop) => `arg.${prop}`).join(", ")});\n}`.$uses({ propsSerializer }).$name(`${getName(dataType) ?? "struct"}Serializer`);
+	}
+	if (isWgslArray(dataType)) {
+		const elementType = dataType.elementType;
+		const length = dataType.elementCount;
+		const elementSerializer = getSerializer(elementType, dataBuffer);
+		return fn([dataType])`(arg) {\n${Array.from({ length }, (_, i) => `  elementSerializer(arg[${i}]);`).join("\n")}\n}`.$uses({ elementSerializer }).$name("arraySerializer");
+	}
+	throw new Error(`Cannot serialize data of type ${dataType.type}`);
+}
+/**
+* Creates a compound serializer TGPU function that serializes multiple arguments of different types to the data buffer.
+*
+* @param dataTypes - Array of WGSL data types that define the types of arguments to be serialized
+* @param dataBuffer - A buffer to store serialized log call data (a necessary external for the returned function)
+*/
+function createCompoundSerializer(dataTypes, dataBuffer) {
+	const usedSerializers = {};
+	return fn(dataTypes)`${generateHeader(dataTypes)} {\n${dataTypes.map((arg, i) => {
+		usedSerializers[`serializer${i}`] = getSerializer(arg, dataBuffer);
+		return `  serializer${i}(_arg_${i});`;
+	}).join("\n")}\n}`.$uses(usedSerializers).$name("compoundSerializer");
+}
+/**
+* Creates a TGPU function that serializes data to the log buffer.
+*
+* @param id - Identifier for this logging function instance
+* @param dataTypes - Array of WGSL data types that will be logged by this function
+* @param dataBuffer - Mutable buffer array to store serialized log call data
+* @param indexBuffer - Atomic counter buffer to track the next available log data slot
+* @param logOptions - Configuration options
+*/
+function createLoggingFunction(id, dataTypes, dataBuffer, indexBuffer, logOptions) {
+	const serializedSize = dataTypes.map(sizeOf).reduce((a, b) => a + b, 0);
+	if (serializedSize > logOptions.logSizeLimit) throw new Error(`Logged data needs to fit in ${logOptions.logSizeLimit} bytes (one of the logs requires ${serializedSize} bytes). Consider increasing the limit by passing appropriate options to tgpu.init().`);
+	const compoundSerializer = createCompoundSerializer(dataTypes, dataBuffer).$name(`log${id}serializer`);
+	const header = generateHeader(dataTypes);
+	return fn(dataTypes)`${header} {
+  dataBlockIndex = atomicAdd(&indexBuffer, 1);
+  if (dataBlockIndex >= ${logOptions.logCountLimit}) {
+    return;
+  }
+  dataBuffer[dataBlockIndex].id = ${id};
+  dataByteIndex = 0;
+
+  compoundSerializer${header};
+}`.$uses({
+		indexBuffer,
+		dataBuffer,
+		dataBlockIndex,
+		dataByteIndex,
+		compoundSerializer
+	}).$name(`log${id}`);
+}
+
+//#endregion
+export { createLoggingFunction };

package/tgsl/consoleLog/types.d.ts

@@ -0,0 +1,54 @@
+import "../../data/snippet.js";
+import { TgpuMutable } from "../../core/buffer/bufferShorthand.js";
+import "../generationHelpers.js";
+import { AnyWgslData, Atomic, U32, WgslArray, WgslStruct } from "../../data/wgslTypes.js";
+
+//#region src/tgsl/consoleLog/types.d.ts
+/**
+ * Options for configuring GPU log generation.
+ */
+interface LogGeneratorOptions {
+  /**
+   * The maximum number of logs that appear during a single draw/dispatch call.
+   * If this number is exceeded, a warning containing the total number of calls is logged and further logs are dropped.
+   * @default 64
+   */
+  logCountLimit?: number;
+  /**
+   * The total number of bytes reserved for each log call.
+   * If this number is exceeded, an exception is thrown during resolution.
+   * @default 252
+   */
+  logSizeLimit?: number;
+  /**
+   * The prefix attached to each log call.
+   * @default ' GPU '
+   */
+  messagePrefix?: string;
+}
+type SerializedLogCallData = WgslStruct<{
+  id: U32;
+  serializedData: WgslArray<U32>;
+}>;
+interface LogMeta {
+  op: SupportedLogOps;
+  argTypes: (string | AnyWgslData)[];
+}
+/**
+ * The resources required for logging via console.log within TypeGPU functions.
+ *
+ * @property indexBuffer - A buffer used for indexing log entries. Needs to be cleared after each dispatch/draw.
+ * @property dataBuffer - A buffer containing an array of serialized log call data.
+ * @property options - The configuration options for the LogGenerator.
+ * @property logIdToMeta - A mapping from log identifiers to an object containing the corresponding log op and argument types.
+ */
+interface LogResources {
+  indexBuffer: TgpuMutable<Atomic<U32>>;
+  dataBuffer: TgpuMutable<WgslArray<SerializedLogCallData>>;
+  options: Required<LogGeneratorOptions>;
+  logIdToMeta: Map<number, LogMeta>;
+}
+declare const supportedLogOps: readonly ["log", "debug", "info", "warn", "error", "clear"];
+type SupportedLogOps = (typeof supportedLogOps)[number];
+//#endregion
+export { LogGeneratorOptions, LogResources };

package/tgsl/consoleLog/types.js

@@ -0,0 +1,12 @@
+//#region src/tgsl/consoleLog/types.ts
+const supportedLogOps = [
+	"log",
+	"debug",
+	"info",
+	"warn",
+	"error",
+	"clear"
+];
+
+//#endregion
+export { supportedLogOps };

package/tgsl/conversion.js

@@ -0,0 +1,200 @@
+import { DEV, TEST } from "../shared/env.js";
+import { isMat, isPtr, isVec } from "../data/wgslTypes.js";
+import { UnknownData, undecorate } from "../data/dataTypes.js";
+import { snip } from "../data/snippet.js";
+import { WgslTypeError, invariant } from "../errors.js";
+import { stitch } from "../core/resolve/stitch.js";
+import { RefOperator, derefSnippet } from "../data/ref.js";
+import { schemaCallWrapperGPU } from "../data/schemaCallWrapper.js";
+import { safeStringify } from "../shared/stringify.js";
+import { assertExhaustive } from "../shared/utilityTypes.js";
+
+//#region src/tgsl/conversion.ts
+const INFINITE_RANK = {
+	rank: Number.POSITIVE_INFINITY,
+	action: "none"
+};
+function getAutoConversionRank(src, dest) {
+	const trueSrc = undecorate(src);
+	const trueDst = undecorate(dest);
+	if (trueSrc.type === trueDst.type) return {
+		rank: 0,
+		action: "none"
+	};
+	if (trueSrc.type === "abstractFloat") {
+		if (trueDst.type === "f32") return {
+			rank: 1,
+			action: "none"
+		};
+		if (trueDst.type === "f16") return {
+			rank: 2,
+			action: "none"
+		};
+	}
+	if (trueSrc.type === "abstractInt") {
+		if (trueDst.type === "i32") return {
+			rank: 3,
+			action: "none"
+		};
+		if (trueDst.type === "u32") return {
+			rank: 4,
+			action: "none"
+		};
+		if (trueDst.type === "abstractFloat") return {
+			rank: 5,
+			action: "none"
+		};
+		if (trueDst.type === "f32") return {
+			rank: 6,
+			action: "none"
+		};
+		if (trueDst.type === "f16") return {
+			rank: 7,
+			action: "none"
+		};
+	}
+	if (isVec(trueSrc) && isVec(trueDst) && trueSrc.type[3] === trueDst.type[3]) return getAutoConversionRank(trueSrc.primitive, trueDst.primitive);
+	if (isMat(trueSrc) && isMat(trueDst) && trueSrc.type[3] === trueDst.type[3]) return {
+		rank: 0,
+		action: "none"
+	};
+	return INFINITE_RANK;
+}
+function getImplicitConversionRank(src, dest) {
+	const trueSrc = undecorate(src);
+	const trueDst = undecorate(dest);
+	if (isPtr(trueSrc) && trueSrc.implicit && getAutoConversionRank(trueSrc.inner, trueDst).rank < Number.POSITIVE_INFINITY) return {
+		rank: 0,
+		action: "deref"
+	};
+	if (isPtr(trueDst) && getAutoConversionRank(trueSrc, trueDst.inner).rank < Number.POSITIVE_INFINITY) return {
+		rank: 1,
+		action: "ref"
+	};
+	const primitivePreference = {
+		f32: 0,
+		f16: 1,
+		i32: 2,
+		u32: 3,
+		bool: 4
+	};
+	if (trueSrc.type in primitivePreference && trueDst.type in primitivePreference) {
+		const srcType = trueSrc.type;
+		const destType = trueDst.type;
+		if (srcType !== destType) {
+			const srcPref = primitivePreference[srcType];
+			return {
+				rank: primitivePreference[destType] < srcPref ? 10 : 20,
+				action: "cast",
+				targetType: trueDst
+			};
+		}
+	}
+	if (trueSrc.type === "abstractFloat") {
+		if (trueDst.type === "u32") return {
+			rank: 2,
+			action: "cast",
+			targetType: trueDst
+		};
+		if (trueDst.type === "i32") return {
+			rank: 1,
+			action: "cast",
+			targetType: trueDst
+		};
+	}
+	return INFINITE_RANK;
+}
+function getConversionRank(src, dest, allowImplicit) {
+	const autoRank = getAutoConversionRank(src, dest);
+	if (autoRank.rank < Number.POSITIVE_INFINITY) return autoRank;
+	if (allowImplicit) return getImplicitConversionRank(src, dest);
+	return INFINITE_RANK;
+}
+function findBestType(types, uniqueTypes, allowImplicit) {
+	let bestResult;
+	for (const targetType of uniqueTypes) {
+		const details = [];
+		let sum = 0;
+		for (const sourceType of types) {
+			const conversion = getConversionRank(sourceType, targetType, allowImplicit);
+			sum += conversion.rank;
+			if (conversion.rank === Number.POSITIVE_INFINITY) break;
+			details.push(conversion);
+		}
+		if (sum < (bestResult?.sum ?? Number.POSITIVE_INFINITY)) bestResult = {
+			type: targetType,
+			details,
+			sum
+		};
+	}
+	if (!bestResult) return;
+	const actions = bestResult.details.map((detail, index) => ({
+		sourceIndex: index,
+		action: detail.action,
+		...detail.action === "cast" && { targetType: detail.targetType }
+	}));
+	return {
+		targetType: bestResult.type,
+		actions,
+		hasImplicitConversions: actions.some((action) => action.action === "cast")
+	};
+}
+function getBestConversion(types, targetTypes) {
+	if (types.length === 0) return void 0;
+	const uniqueTargetTypes = [...new Set((targetTypes || types).map(undecorate))];
+	const explicitResult = findBestType(types, uniqueTargetTypes, false);
+	if (explicitResult) return explicitResult;
+	const implicitResult = findBestType(types, uniqueTargetTypes, true);
+	if (implicitResult) return implicitResult;
+}
+function applyActionToSnippet(ctx, snippet, action, targetType) {
+	if (action.action === "none") return snip(snippet.value, targetType, snippet.origin);
+	switch (action.action) {
+		case "ref": return snip(new RefOperator(snippet, targetType), targetType, snippet.origin);
+		case "deref": return derefSnippet(snippet);
+		case "cast": return schemaCallWrapperGPU(ctx, targetType, snippet);
+		default: assertExhaustive(action.action, "applyActionToSnippet");
+	}
+}
+function unify(inTypes, restrictTo) {
+	if (inTypes.some((type) => type === UnknownData)) return;
+	const conversion = getBestConversion(inTypes, restrictTo);
+	if (!conversion) return;
+	return inTypes.map((type) => isVec(type) || isMat(type) ? type : conversion.targetType);
+}
+function convertToCommonType(ctx, values, restrictTo, verbose = true) {
+	const types = values.map((value) => value.dataType);
+	if (types.some((type) => type === UnknownData)) return;
+	if (DEV && Array.isArray(restrictTo) && restrictTo.length === 0) console.warn("convertToCommonType was called with an empty restrictTo array, which prevents any conversions from being made. If you intend to allow all conversions, pass undefined instead. If this was intended call the function conditionally since the result will always be undefined.");
+	const conversion = getBestConversion(types, restrictTo);
+	if (!conversion) return;
+	if ((TEST || DEV) && verbose && conversion.hasImplicitConversions) console.warn(`Implicit conversions from [\n${values.map((v) => `  ${v.value}: ${safeStringify(v.dataType)}`).join(",\n")}\n] to ${conversion.targetType.type} are supported, but not recommended.
+Consider using explicit conversions instead.`);
+	return values.map((value, index) => {
+		const action = conversion.actions[index];
+		invariant(action, "Action should not be undefined");
+		return applyActionToSnippet(ctx, value, action, conversion.targetType);
+	});
+}
+function tryConvertSnippet(ctx, snippet, targetDataTypes, verbose = true) {
+	const targets = Array.isArray(targetDataTypes) ? targetDataTypes : [targetDataTypes];
+	const { value, dataType, origin } = snippet;
+	if (targets.length === 1) {
+		const target = targets[0];
+		if (target === dataType) return snip(value, target, origin);
+		if (dataType === UnknownData) return snip(stitch`${snip(value, target, origin)}`, target, origin);
+	}
+	const converted = convertToCommonType(ctx, [snippet], targets, verbose);
+	if (converted) return converted[0];
+	throw new WgslTypeError(`Cannot convert value of type '${String(dataType)}' to any of the target types: [${targets.map((t) => t.type).join(", ")}]`);
+}
+function convertStructValues(ctx, structType, values) {
+	return Object.entries(structType.propTypes).map(([key, targetType]) => {
+		const val = values[key];
+		if (!val) throw new Error(`Missing property ${key}`);
+		return convertToCommonType(ctx, [val], [targetType])?.[0] ?? val;
+	});
+}
+
+//#endregion
+export { convertStructValues, convertToCommonType, getBestConversion, tryConvertSnippet, unify };

package/tgsl/forOfUtils.js

@@ -0,0 +1,45 @@
+import { $gpuCallable } from "../shared/symbols.js";
+import { isPtr, isVec, isWgslArray } from "../data/wgslTypes.js";
+import { UnknownData } from "../data/dataTypes.js";
+import { isEphemeralSnippet, snip } from "../data/snippet.js";
+import { WgslTypeError, invariant } from "../errors.js";
+import { stitch } from "../core/resolve/stitch.js";
+import { createPtrFromOrigin, implicitFrom } from "../data/ptr.js";
+import { u32 } from "../data/numeric.js";
+import { ArrayExpression, concretize } from "./generationHelpers.js";
+import { accessIndex } from "./accessIndex.js";
+import { arrayLength } from "../std/array.js";
+
+//#region src/tgsl/forOfUtils.ts
+function getLoopVarKind(elementSnippet) {
+	return elementSnippet.origin === "constant-tgpu-const-ref" ? "const" : "let";
+}
+function getElementSnippet(iterableSnippet, index) {
+	const elementSnippet = accessIndex(iterableSnippet, index);
+	if (!elementSnippet) throw new WgslTypeError("`for ... of ...` loops only support array or vector iterables");
+	return elementSnippet;
+}
+function getElementType(elementSnippet, iterableSnippet) {
+	let elementType = elementSnippet.dataType;
+	if (elementType === UnknownData) throw new WgslTypeError(stitch`The elements in iterable ${iterableSnippet} are of unknown type`);
+	if (isEphemeralSnippet(elementSnippet) || elementSnippet.origin === "constant-tgpu-const-ref" || elementSnippet.origin === "runtime-tgpu-const-ref") return elementType;
+	if (!isPtr(elementType)) {
+		const ptrType = createPtrFromOrigin(elementSnippet.origin, concretize(elementType));
+		invariant(ptrType !== void 0, `Creating pointer type from origin ${elementSnippet.origin}`);
+		elementType = ptrType;
+	}
+	return implicitFrom(elementType);
+}
+function getElementCountSnippet(ctx, iterableSnippet, unroll = false) {
+	const { value, dataType } = iterableSnippet;
+	if (isWgslArray(dataType)) return dataType.elementCount > 0 ? snip(dataType.elementCount, u32, "constant") : arrayLength[$gpuCallable].call(ctx, [iterableSnippet]);
+	if (isVec(dataType)) return snip(dataType.componentCount, u32, "constant");
+	if (unroll) {
+		if (Array.isArray(value)) return snip(value.length, u32, "constant");
+		if (value instanceof ArrayExpression) return snip(value.elements.length, u32, "constant");
+	}
+	throw new WgslTypeError("`for ... of ...` loops only support array or vector iterables");
+}
+
+//#endregion
+export { getElementCountSnippet, getElementSnippet, getElementType, getLoopVarKind };

package/tgsl/generationHelpers.d.ts

@@ -0,0 +1,37 @@
+import { Snippet } from "../data/snippet.js";
+import { ShelllessRepository } from "./shellless.js";
+import { FunctionScopeLayer, ResolutionCtx } from "../types.js";
+import { BaseData } from "../data/wgslTypes.js";
+
+//#region src/tgsl/generationHelpers.d.ts
+type GenerationCtx = ResolutionCtx & {
+  readonly pre: string;
+  /**
+   * Used by `typedExpression` to signal downstream
+   * expression resolution what type is expected of them.
+   *
+   * It is used exclusively for inferring the types of structs and arrays.
+   * It is modified exclusively by `typedExpression` function.
+   */
+  expectedType: (BaseData | BaseData[]) | undefined;
+  readonly topFunctionScope: FunctionScopeLayer | undefined;
+  readonly topFunctionReturnType: BaseData | undefined;
+  indent(): string;
+  dedent(): string;
+  pushBlockScope(): void;
+  popBlockScope(): void;
+  generateLog(op: string, args: Snippet[]): Snippet;
+  getById(id: string): Snippet | null;
+  defineVariable(id: string, snippet: Snippet): void;
+  setBlockExternals(externals: Record<string, Snippet>): void;
+  clearBlockExternals(): void;
+  /**
+   * Types that are used in `return` statements are
+   * reported using this function, and used to infer
+   * the return type of the owning function.
+   */
+  reportReturnType(dataType: BaseData): void;
+  readonly shelllessRepo: ShelllessRepository;
+};
+//#endregion
+export { GenerationCtx };