typegpu 0.11.4 → 0.11.6

package/tgsl/wgslGenerator.js

@@ -7,7 +7,7 @@ import { ResolutionError, WgslTypeError, invariant } from "../errors.js";
 import { isGPUCallable, isKnownAtComptime } from "../types.js";
 import { stitch } from "../core/resolve/stitch.js";
 import { createPtrFromOrigin, implicitFrom, ptrFn } from "../data/ptr.js";
-import { RefOperator } from "../data/ref.js";
+import { RefOperator, _ref } from "../data/ref.js";
 import { safeStringify } from "../shared/stringify.js";
 import { convertStructValues, convertToCommonType, tryConvertSnippet } from "./conversion.js";
 import { bool, i32, u32 } from "../data/numeric.js";
@@ -23,7 +23,7 @@ import { isGenericFn } from "../core/function/tgpuFn.js";
 import { arrayOf } from "../data/array.js";
 import { pow } from "../std/numeric.js";
 import { resolveData } from "../core/resolve/resolveData.js";
-import { UnrollableIterable } from "../core/unroll/tgpuUnroll.js";
+import { UnrollableIterable, unroll } from "../core/unroll/tgpuUnroll.js";
 import { mathToStd, supportedLogOps } from "./jsPolyfills.js";
 import { isTgpuRange } from "../std/range.js";
 import { getElementSnippet, getElementType, getLoopVarKind, getRangeSnippets } from "./forOfUtils.js";
@@ -165,8 +165,11 @@ ${this.ctx.pre}}`;
 			this.ctx.popBlockScope();
 		}
 	}
+	_blockStatement(block, externalMap) {
+		return `${this.ctx.pre}${this._block(block, externalMap)}`;
+	}
 	refVariable(id, dataType) {
-		const varName = this.ctx.makeNameValid(id);
+		const varName = this.ctx.makeUniqueIdentifier(id, "block");
 		const ptrType = ptrFn(dataType);
 		const snippet = snip(new RefOperator(snip(varName, dataType, "function"), ptrType), ptrType, "function");
 		this.ctx.defineVariable(id, snippet);
@@ -181,10 +184,14 @@ ${this.ctx.pre}}`;
 		else if (!naturallyEphemeral) varOrigin = isEphemeralOrigin(origin) ? "this-function" : origin;
 		else if (origin === "constant" && varType === "const") varOrigin = "constant";
 		else varOrigin = "runtime";
-		const snippet = snip(this.ctx.makeNameValid(id), dataType, varOrigin);
+		const snippet = snip(this.ctx.makeUniqueIdentifier(id, "block"), dataType, varOrigin);
 		this.ctx.defineVariable(id, snippet);
 		return snippet;
 	}
+	/**
+	* Creates a variable declaration string.
+	* `keyword` may be a placeholder filled in later.
+	*/
 	emitVarDecl(pre, keyword, name, _dataType, rhsStr) {
 		return `${pre}${keyword} ${name} = ${rhsStr};`;
 	}
@@ -252,22 +259,14 @@ ${this.ctx.pre}}`;
 			const rhsStr = this.ctx.resolve(convRhs.value, convRhs.dataType).value;
 			const type = operatorToType(convLhs.dataType, op, convRhs.dataType);
 			if (exprType === NODE.assignmentExpr) {
-				if (convLhs.origin === "constant" || convLhs.origin === "constant-tgpu-const-ref" || convLhs.origin === "runtime-tgpu-const-ref") {
-					if (isKnownAtComptime(convLhs)) throw new WgslTypeError(`'${stringifyNode(expression)}' is invalid, because the left side is defined outside of the shader, and therefore is immutable during its execution. Try using tgpu.privateVar or buffers.`);
-					throw new WgslTypeError(`'${stringifyNode(expression)}' is invalid, because the left side is a constant.`);
-				}
-				if (lhsExpr.origin === "argument") throw new WgslTypeError(`'${stringifyNode(expression)}' is invalid, because non-pointer arguments cannot be mutated.`);
+				validateSnippetMutation(convLhs, expression);
+				this.tryMarkModified(lhs);
 				if (op === "=" && rhsExpr.origin === "argument" && !isNaturallyEphemeral(rhsExpr.dataType)) throw new WgslTypeError(`'${stringifyNode(expression)}' is invalid, because argument references cannot be assigned.\n-----\nTry '${stringifyNode(lhs)} = ${this.ctx.resolve(rhsExpr.dataType).value}(${stringifyNode(rhs)})' to copy the value instead.\n-----`);
 				if (op === "=" && !isEphemeralSnippet(rhsExpr)) throw new WgslTypeError(`'${stringifyNode(expression)}' is invalid, because references cannot be assigned.\n-----\nTry '${stringifyNode(lhs)} = ${this.ctx.resolve(rhsExpr.dataType).value}(${stringifyNode(rhs)})' to copy the value instead.\n-----`);
 			}
 			return snip(parenthesizedOps.includes(op) ? `(${lhsStr} ${OP_MAP[op] ?? op} ${rhsStr})` : `${lhsStr} ${OP_MAP[op] ?? op} ${rhsStr}`, type, "runtime");
 		}
-		if (expression[0] === NODE.postUpdate) {
-			const [_, op, arg] = expression;
-			const argExpr = this._expression(arg);
-			const argStr = this.ctx.resolve(argExpr.value, argExpr.dataType).value;
-			return snip(`${argStr}${op}`, argExpr.dataType, "runtime");
-		}
+		if (expression[0] === NODE.postUpdate) throw new Error(`'${stringifyNode(expression)}' is invalid because update is only allowed as a statement.`);
 		if (expression[0] === NODE.unaryExpr) {
 			const [_, op, arg] = expression;
 			const argExpr = this._expression(arg);
@@ -320,6 +319,7 @@ ${this.ctx.pre}}`;
 				const rhs = this._expression(argNodes[0]);
 				return callee.value.operator(this.ctx, [callee.value.lhs, rhs]);
 			}
+			if ((callee.value === _ref || callee.value === unroll) && argNodes[0]) this.tryMarkModified(argNodes[0]);
 			if (isGPUCallable(callee.value)) {
 				const callable = callee.value[$gpuCallable];
 				const strictSignature = callable.strictSignature;
@@ -423,7 +423,14 @@ ${this.ctx.pre}}`;
 		assertExhaustive(expression);
 	}
 	functionDefinition(options) {
-		const body = this._block(options.body);
+		let body = this._block(options.body);
+		const scope = this.ctx.topFunctionScope;
+		invariant(scope, "Expected function scope to be present");
+		const replacements = Object.fromEntries([...scope.placeholderForVariable.entries()].map(([variable, placeholder]) => [placeholder, scope.modifiedVariables.has(variable) ? "var" : "let"]));
+		if (Object.keys(replacements).length > 0) {
+			const regex = new RegExp(Object.keys(replacements).join("|"), "gi");
+			body = body.replace(regex, (match) => replacements[match] ?? "#ERR");
+		}
 		const returnType = options.determineReturnType();
 		const argList = options.args.filter((arg) => arg.used || options.functionType === "normal").map((arg) => {
 			return `${getAttributesString(arg.decoratedType)}${arg.name}: ${this.ctx.resolve(arg.decoratedType).value}`;
@@ -481,7 +488,7 @@ Try 'return ${typeStr}(${str});' instead.
 				if (!Array.isArray(node)) node = blockifySingleStatement(node);
 				if (node[0] === NODE.block && node[1].length === 1 && node[1][0][0] === NODE.if) return this._statement(node[1][0]);
 				if (node[0] === NODE.if) return this._statement(node);
-				return `${this.ctx.pre}${this._block(blockifySingleStatement(node))}`;
+				return this._blockStatement(blockifySingleStatement(node));
 			}
 			const consequent = this._block(blockifySingleStatement(consNode));
 			const alternate = !altNode ? void 0 : this._block(blockifySingleStatement(altNode));
@@ -491,7 +498,7 @@ ${this.ctx.pre}if (${condition}) ${consequent}
 ${this.ctx.pre}else ${alternate}`;
 		}
 		if (statement[0] === NODE.let || statement[0] === NODE.const) {
-			let varType = "var";
+			let varType = "<deferred>";
 			const [stmtType, rawId, rawValue] = statement;
 			const eq = rawValue !== void 0 ? this._expression(rawValue) : void 0;
 			if (!eq) throw new Error(`'${stringifyNode(statement)}' is invalid because all variables need initializers.`);
@@ -523,7 +530,10 @@ ${this.ctx.pre}else ${alternate}`;
 						invariant(ptrType !== void 0, `Creating pointer type from origin ${eq.origin}`);
 						dataType = ptrType;
 					}
-					if (!(eq.value instanceof RefOperator)) dataType = implicitFrom(dataType);
+					if (!(eq.value instanceof RefOperator)) {
+						dataType = implicitFrom(dataType);
+						this.tryMarkModified(rawValue);
+					}
 				}
 			} else if (stmtType === NODE.const) {
 				if (eq.origin === "argument") varType = "let";
@@ -542,9 +552,16 @@ ${this.ctx.pre}else ${alternate}`;
 			const snippet = this.blockVariable(varType, rawId, concretize(dataType), eq.origin);
 			const rhsSnippet = tryConvertSnippet(this.ctx, eq, dataType, false);
 			const rhsStr = this.ctx.resolve(rhsSnippet.value, rhsSnippet.dataType).value;
-			return this.emitVarDecl(this.ctx.pre, varType, snippet.value, concretize(dataType), rhsStr);
+			let emittedVarType;
+			if (varType === "<deferred>") {
+				const scope = this.ctx.topFunctionScope;
+				invariant(scope, `Expected function scope to be present for ${rawId}`);
+				emittedVarType = `#VAR_${scope.placeholderForVariable.size}#`;
+				scope.placeholderForVariable.set(snippet, emittedVarType);
+			} else emittedVarType = varType;
+			return this.emitVarDecl(this.ctx.pre, emittedVarType, snippet.value, concretize(dataType), rhsStr);
 		}
-		if (statement[0] === NODE.block) return `${this.ctx.pre}${this._block(statement)}`;
+		if (statement[0] === NODE.block) return this._blockStatement(statement);
 		if (statement[0] === NODE.for) {
 			const [_, init, condition, update, body] = statement;
 			const prevUnrollingFlag = this.#unrolling;
@@ -581,6 +598,7 @@ ${this.ctx.pre}else ${alternate}`;
 		if (statement[0] === NODE.forOf) {
 			const [_, loopVar, iterable, body] = statement;
 			if (loopVar[0] !== NODE.const) throw new WgslTypeError("Only `for (const ... of ... )` loops are supported");
+			this.tryMarkModified(iterable);
 			let ctxIndent = false;
 			const prevUnrollingFlag = this.#unrolling;
 			try {
@@ -599,21 +617,21 @@ ${this.ctx.pre}else ${alternate}`;
 					const { value } = iterableSnippet;
 					const elements = isTgpuRange(value) ? value.map((i) => coerceToSnippet(i)) : value instanceof ArrayExpression ? value.elements : Array.from({ length }, (_$1, i) => getElementSnippet(iterableSnippet, snip(i, u32, "constant")));
 					if (isEphemeralSnippet(elements[0]) && !isNaturallyEphemeral(elements[0]?.dataType)) throw new WgslTypeError(`Cannot unroll '${stringifyNode(iterable)}'. The elements of iterable are constructed in place but are not value types.`);
-					return elements.map((e, i) => `${this.ctx.pre}// unrolled iteration #${i}\n${this.ctx.pre}${this._block(blockified, { [originalLoopVarName]: e })}`).join("\n");
+					return elements.map((e, i) => `${this.ctx.pre}// unrolled iteration #${i}\n${this._blockStatement(blockified, { [originalLoopVarName]: e })}`).join("\n");
 				}
 				this.#unrolling = false;
-				const index = this.ctx.makeNameValid("i");
+				const index = this.ctx.makeUniqueIdentifier("i", "block");
 				const forHeaderStr = stitch`${this.ctx.pre}for (var ${index} = ${range.start}; ${index} ${range.comparison} ${range.end}; ${index} += ${range.step})`;
 				let bodyStr = "";
 				if (isTgpuRange(iterableSnippet.value)) bodyStr = this._block(blockified, { [originalLoopVarName]: snip(index, range.start.dataType, "runtime") });
 				else {
 					this.ctx.indent();
 					ctxIndent = true;
-					const loopVarName = this.ctx.makeNameValid(originalLoopVarName);
+					const loopVarName = this.ctx.makeUniqueIdentifier(originalLoopVarName, "block");
 					const elementSnippet = getElementSnippet(iterableSnippet, snip(index, u32, "runtime"));
 					const loopVarKind = getLoopVarKind(elementSnippet);
 					const elementType = getElementType(elementSnippet, iterableSnippet);
-					bodyStr = `{\n${stitch`${this.ctx.pre}${loopVarKind} ${loopVarName} = ${tryConvertSnippet(this.ctx, elementSnippet, elementType, false)};`}\n${this.ctx.pre}${this._block(blockified, { [originalLoopVarName]: snip(loopVarName, elementType, elementSnippet.origin) })}\n`;
+					bodyStr = `{\n${stitch`${this.ctx.pre}${loopVarKind} ${loopVarName} = ${tryConvertSnippet(this.ctx, elementSnippet, elementType, false)};`}\n${this._blockStatement(blockified, { [originalLoopVarName]: snip(loopVarName, elementType, elementSnippet.origin) })}\n`;
 					this.ctx.dedent();
 					bodyStr += `${this.ctx.pre}}`;
 					ctxIndent = false;
@@ -625,6 +643,14 @@ ${this.ctx.pre}else ${alternate}`;
 				this.ctx.popBlockScope();
 			}
 		}
+		if (statement[0] === NODE.postUpdate) {
+			const [_, op, arg] = statement;
+			const argExpr = this._expression(arg);
+			const argStr = this.ctx.resolve(argExpr.value, argExpr.dataType).value;
+			validateSnippetMutation(argExpr, statement);
+			this.tryMarkModified(arg);
+			return `${this.ctx.pre}${argStr}${op};`;
+		}
 		if (statement[0] === NODE.continue) {
 			if (this.#unrolling) throw new WgslTypeError("Cannot unroll loop containing `continue`");
 			return `${this.ctx.pre}continue;`;
@@ -637,7 +663,35 @@ ${this.ctx.pre}else ${alternate}`;
 		const resolved = expr.value && this.ctx.resolve(expr.value).value;
 		return resolved ? `${this.ctx.pre}${resolved};` : "";
 	}
+	/**
+	* Attempts a member access lookup to mark a variable as modified.
+	* @example
+	* // given `let a; a = 1;`
+	* tryMarkModified('a') // `a` is marked in the function scope
+	*
+	* // given `const obj; obj.prop = 1;`
+	* tryMarkModified('obj.prop') // `obj` is marked in the function scope
+	*
+	* // given `this.buffer.$;`
+	* tryMarkModified('this.buffer.$') // `this` is not marked, since there is no placeholder for it
+	*/
+	tryMarkModified(expr) {
+		if (!expr) return;
+		const maybeObject = extractObject(expr);
+		if (maybeObject !== void 0) {
+			const snippet = this.ctx.getById(maybeObject);
+			const scope = this.ctx.topFunctionScope;
+			if (snippet && scope && scope.placeholderForVariable.has(snippet)) scope.modifiedVariables.add(snippet);
+		}
+	}
 };
+function validateSnippetMutation(mutated, expr) {
+	if (mutated.origin === "constant" || mutated.origin === "constant-tgpu-const-ref" || mutated.origin === "runtime-tgpu-const-ref") {
+		if (isKnownAtComptime(mutated)) throw new WgslTypeError(`'${stringifyNode(expr)}' is invalid, because the left side is defined outside of the shader, and therefore is immutable during its execution. Try using tgpu.privateVar or buffers.`);
+		throw new WgslTypeError(`'${stringifyNode(expr)}' is invalid, because the left side is a constant.`);
+	}
+	if (mutated.origin === "argument") throw new WgslTypeError(`'${stringifyNode(expr)}' is invalid, because non-pointer arguments cannot be mutated.`);
+}
 function assertExhaustive(value) {
 	throw new Error(`'${safeStringify(value)}' was not handled by the WGSL generator.`);
 }
@@ -649,6 +703,11 @@ function parseNumericString(str) {
 function blockifySingleStatement(statement) {
 	return typeof statement !== "object" || statement[0] !== NODE.block ? [NODE.block, [statement]] : statement;
 }
+function extractObject(expr) {
+	let object = expr;
+	while (Array.isArray(object) && (object[0] === NODE.memberAccess || object[0] === NODE.indexAccess)) object = object[1];
+	if (typeof object === "string") return object;
+}
 const wgslGenerator = new WgslGenerator();
 var wgslGenerator_default = wgslGenerator;
 

package/types.d.ts

@@ -70,6 +70,14 @@ type FunctionScopeLayer = {
    * All types used in `return` statements.
    */
   reportedReturnTypes: Set<BaseData>;
+  /**
+   * Maps variables to their modifier placeholders
+   */
+  placeholderForVariable: Map<Snippet, string>;
+  /**
+   * Local variables that need `var` modifier.
+   */
+  modifiedVariables: Set<Snippet>;
 };
 type SlotBindingLayer = {
   type: 'slotBinding';
@@ -77,6 +85,7 @@ type SlotBindingLayer = {
 };
 type BlockScopeLayer = {
   type: 'blockScope';
+  takenLocalIdentifiers: Set<string>;
   declarations: Map<string, Snippet>;
   externals: Map<string, Snippet>;
 };
@@ -84,6 +93,7 @@ type StackLayer = ItemLayer | SlotBindingLayer | FunctionScopeLayer | BlockScope
 interface ItemStateStack {
   readonly itemDepth: number;
   readonly topItem: ItemLayer;
+  readonly topBlockScope: BlockScopeLayer | undefined;
   readonly topFunctionScope: FunctionScopeLayer | undefined;
   pushItem(): void;
   pushSlotBindings(pairs: SlotValuePair[]): void;
@@ -237,8 +247,25 @@ interface ResolutionCtx {
    * @param name the temporary name to assign to the item (if missing, just returns `callback()`)
    */
   withRenamed<T>(item: object, name: string | undefined, callback: () => T): T;
-  getUniqueName(resource: object): string;
-  makeNameValid(name: string): string;
+  /**
+   * @param primer The basis for the unique identifier. Depending on the strategy, or
+   *               the names already taken, this may be modified to ensure uniqueness.
+   * @param scope The scope in which to generate the identifier. 'global' means
+   *              the identifier is meant to be unique across the entire program, while
+   *              'block' means it cannot shadow any existing identifiers visible from
+   *              within the current block. After the block is popped, any identifiers
+   *              defined within it are no longer visible.
+   * @returns an identifier that is unique within the given scope
+   */
+  makeUniqueIdentifier(primer: string | undefined, scope: 'global' | 'block'): string;
+  isIdentifierTaken(name: string): boolean;
+  /**
+   * Makes sure the given identifier cannot be generated by {@link makeUniqueIdentifier}
+   * within the given scope.
+   * @param name The name to reserve
+   * @param scope See {@link makeUniqueIdentifier} for a description of the scope parameter.
+   */
+  reserveIdentifier(name: string, scope: 'global' | 'block'): void;
 }
 /**
  * Houses a method on the symbol '$resolve` that returns a

package/nameRegistry.d.ts

@@ -1,30 +0,0 @@
-//#region src/nameRegistry.d.ts
-interface NameRegistry {
-  /**
-   * Creates a valid WGSL identifier, each guaranteed to be unique
-   * in the lifetime of a single resolution process
-   * (excluding non-global identifiers from popped scopes).
-   * Should append "_" to primer, followed by some id.
-   * @param primer Used in the generation process, makes the identifier more recognizable.
-   * @param global Whether the name should be registered in the global scope (true), or in the current function scope (false)
-   */
-  makeUnique(primer: string | undefined, global: boolean): string;
-  /**
-   * Creates a valid WGSL identifier.
-   * Renames identifiers that are WGSL reserved words.
-   * @param primer Used in the generation process.
-   *
-   * @example
-   * makeValid("notAKeyword"); // "notAKeyword"
-   * makeValid("struct"); // makeUnique("struct")
-   * makeValid("struct_1"); // makeUnique("struct_1") (to avoid potential name collisions)
-   * makeValid("_"); // ERROR (too difficult to make valid to care)
-   */
-  makeValid(primer: string): string;
-  pushFunctionScope(): void;
-  popFunctionScope(): void;
-  pushBlockScope(): void;
-  popBlockScope(): void;
-}
-//#endregion
-export { NameRegistry };