typegpu 0.11.8 → 0.12.0

package/core/rawCodeSnippet/tgpuRawCodeSnippet.js

@@ -1,96 +1,93 @@
-import { $gpuValueOf, $internal, $ownSnippet, $resolve } from "../../shared/symbols.js";
 import { snip } from "../../data/snippet.js";
-import { inCodegenMode } from "../../execMode.js";
-import { valueProxyHandler } from "../valueProxyUtils.js";
-import { mergeExternals, replaceExternalsInWgsl } from "../resolve/externals.js";
-
-//#region src/core/rawCodeSnippet/tgpuRawCodeSnippet.ts
+import { makeDereferenceable } from "../../tgsl/makeDereferenceable.js";
+import { makeResolvable } from "../../tgsl/makeResolvable.js";
+import { $gpuValueOf, $internal } from "../../shared/symbols.js";
+import { replaceExternalsInWgsl } from "../resolve/externals.js";
 /**
-* An advanced API that creates a typed shader expression which
-* can be injected into the final shader bundle upon use.
-*
-* @param expression The code snippet that will be injected in place of `foo.$`
-* @param type The type of the expression
-* @param [origin='runtime'] Where the value originates from.
-*
-* **-- Which origin to choose?**
-*
-* Usually 'runtime' (the default) is a safe bet, but if you're sure that the expression or
-* computation is constant (either a reference to a constant, a numeric literal,
-* or an operation on constants), then pass 'constant' as it might lead to better
-* optimizations.
-*
-* If what the expression is a direct reference to an existing value (e.g. a uniform, a
-* storage binding, ...), then choose from 'uniform', 'mutable', 'readonly', 'workgroup',
-* 'private' or 'handle' depending on the address space of the referred value.
-*
-* @example
-* ```ts
-* // An identifier that we know will be in the
-* // final shader bundle, but we cannot
-* // refer to it in any other way.
-* const existingGlobal = tgpu['~unstable']
-*   .rawCodeSnippet('EXISTING_GLOBAL', d.f32, 'constant');
-*
-* const foo = () => {
-*   'use gpu';
-*   return existingGlobal.$ * 2;
-* };
-*
-* const wgsl = tgpu.resolve([foo]);
-* // fn foo() -> f32 {
-* //   return EXISTING_GLOBAL * 2;
-* // }
-* ```
-*/
-function rawCodeSnippet(expression, type, origin = "runtime") {
-	return new TgpuRawCodeSnippetImpl(expression, type, origin);
+ * An advanced API that creates a typed shader expression which
+ * can be injected into the final shader bundle upon use.
+ *
+ * @param expression The code snippet that will be injected in place of `foo.$`
+ * @param type The type of the expression
+ * @param [origin='runtime'] Where the value originates from.
+ * @param [possibleSideEffects=true] Whether generating this snippet may produce a WGSL expression with observable side-effects (e.g. calling a barrier, discarding a fragment, or writing to memory).
+ *
+ * **-- Which origin to choose?**
+ *
+ * Usually 'runtime' (the default) is a safe bet, but if you're sure that the expression or
+ * computation is constant (either a reference to a constant, a numeric literal,
+ * or an operation on constants), then pass 'constant' as it might lead to better
+ * optimizations.
+ *
+ * If what the expression is a direct reference to an existing value (e.g. a uniform, a
+ * storage binding, ...), then choose from 'uniform', 'mutable', 'readonly', 'workgroup',
+ * 'private' or 'handle' depending on the address space of the referred value.
+ *
+ * @example
+ * ```ts
+ * // An identifier that we know will be in the
+ * // final shader bundle, but we cannot
+ * // refer to it in any other way.
+ * const existingGlobal = tgpu['~unstable']
+ *   .rawCodeSnippet('EXISTING_GLOBAL', d.f32, 'constant', false);
+ *
+ * const foo = () => {
+ *   'use gpu';
+ *   return existingGlobal.$ * 2;
+ * };
+ *
+ * const wgsl = tgpu.resolve([foo]);
+ * // fn foo() -> f32 {
+ * //   return EXISTING_GLOBAL * 2;
+ * // }
+ * ```
+ */
+export function rawCodeSnippet(expression, type, origin = 'runtime', possibleSideEffects = true) {
+    return new TgpuRawCodeSnippetImpl(expression, type, origin, possibleSideEffects);
+}
+// --------------
+// Implementation
+// --------------
+class TgpuRawCodeSnippetImpl {
+    dataType;
+    origin;
+    possibleSideEffects;
+    #expression;
+    #externals;
+    static {
+        TgpuRawCodeSnippetImpl.prototype[$internal] = true;
+        makeDereferenceable(makeResolvable(TgpuRawCodeSnippetImpl.prototype, {
+            asString() {
+                return `raw(${String(this.dataType)}): "${this.#expression}"`;
+            },
+            resolve(ctx) {
+                const replacedExpression = replaceExternalsInWgsl(ctx, this.#externals ?? {}, this.#expression);
+                return snip(replacedExpression, this.dataType, this.origin, this.possibleSideEffects);
+            },
+        }), {
+            codegenMode: {
+                getBaseSnippet(trackingProxy) {
+                    return snip(trackingProxy, this.dataType, this.origin, this.possibleSideEffects);
+                },
+            },
+            normalMode: {
+                get() {
+                    throw new Error('Raw code snippets can only be used on the GPU.');
+                },
+            },
+        });
+    }
+    constructor(expression, type, origin, possibleSideEffects) {
+        this.dataType = type;
+        this.origin = origin;
+        this.possibleSideEffects = possibleSideEffects;
+        this.#expression = expression;
+    }
+    $uses(dependencyMap) {
+        if (this.#externals !== undefined) {
+            throw new Error("Cannot call '$uses' multiple times. If you wish to override dependencies, use slots or accessors instead.");
+        }
+        this.#externals = dependencyMap;
+        return this;
+    }
 }
-var TgpuRawCodeSnippetImpl = class {
-	[$internal];
-	dataType;
-	origin;
-	#expression;
-	#externalsToApply;
-	constructor(expression, type, origin) {
-		this[$internal] = true;
-		this.dataType = type;
-		this.origin = origin;
-		this.#expression = expression;
-		this.#externalsToApply = [];
-	}
-	$uses(dependencyMap) {
-		this.#externalsToApply.push(dependencyMap);
-		return this;
-	}
-	[$resolve](ctx) {
-		const externalMap = {};
-		for (const externals of this.#externalsToApply) mergeExternals(externalMap, externals);
-		return snip(replaceExternalsInWgsl(ctx, externalMap, this.#expression), this.dataType, this.origin);
-	}
-	toString() {
-		return `raw(${String(this.dataType)}): "${this.#expression}"`;
-	}
-	get [$gpuValueOf]() {
-		const dataType = this.dataType;
-		const origin = this.origin;
-		return new Proxy({
-			[$internal]: true,
-			get [$ownSnippet]() {
-				return snip(this, dataType, origin);
-			},
-			[$resolve]: (ctx) => ctx.resolve(this),
-			toString: () => `raw(${String(this.dataType)}): "${this.#expression}".$`
-		}, valueProxyHandler);
-	}
-	get $() {
-		if (!inCodegenMode()) throw new Error("Raw code snippets can only be used on the GPU.");
-		return this[$gpuValueOf];
-	}
-	get value() {
-		return this.$;
-	}
-};
-
-//#endregion
-export { rawCodeSnippet };

package/core/resolve/externals.d.ts

@@ -1,11 +1,29 @@
-import "../../types.js";
-
-//#region src/core/resolve/externals.d.ts
-
+import { type ResolutionCtx } from '../../types.ts';
+import type { FnExternals } from '../function/fnCore.ts';
 /**
  * A key-value mapping where keys represent identifiers within shader code,
  * and values can either be another ExternalMap, or be any type that can be resolved to a code string.
  */
-type ExternalMap = Record<string, unknown>;
-//#endregion
-export { ExternalMap };
+export type ExternalMap = Record<string, unknown>;
+/**
+ * Merges function externals into one map.
+ */
+export declare function mergeFunctionExternals(fnExternals: FnExternals): ExternalMap;
+export declare function addArgTypesToExternals(implementation: string, argTypes: unknown[], core: {
+    setExternals: (key: 'args', externals: ExternalMap) => void;
+}): void;
+export declare function addReturnTypeToExternals(implementation: string, returnType: unknown, core: {
+    setExternals: (key: 'out', externals: ExternalMap) => void;
+}): void;
+export declare const anyIdent: RegExp;
+export declare const boundedPropChain: RegExp;
+/**
+ * Replaces all occurrences of external names in WGSL code with their resolved values.
+ * It adds all necessary definitions to the resolution context.
+ * @param ctx - The resolution context.
+ * @param externalMap - The external map. Assumes that keys don't contain dots.
+ * @param wgsl - The WGSL code.
+ *
+ * @returns The WGSL code with all external names replaced with their resolved values.
+ */
+export declare function replaceExternalsInWgsl(ctx: ResolutionCtx, externalMap: ExternalMap, wgsl: string): string;

package/core/resolve/externals.js

@@ -1,72 +1,89 @@
-import { isWgslStruct } from "../../data/wgslTypes.js";
-import { getName, hasTinyestMetadata, setName } from "../../shared/meta.js";
 import { isLooseData } from "../../data/dataTypes.js";
+import { isWgslStruct } from "../../data/wgslTypes.js";
+import { getName, hasTinyestMetadata, isNamable, setName } from "../../shared/meta.js";
+import { logger } from "../../tgpuLogger.js";
 import { isWgsl } from "../../types.js";
-
-//#region src/core/resolve/externals.ts
 function isResolvable(value) {
-	return isWgsl(value) || isLooseData(value) || hasTinyestMetadata(value);
+    return isWgsl(value) || isLooseData(value) || hasTinyestMetadata(value);
 }
 /**
-* Merges two external maps into one.
-* If the external value is a namable object, it is given a name if it does not already have one.
-* @param existing - The existing external map.
-* @param newExternals - The new external map.
-*
-* NOTE:
-* This function attempts to avoid accidental reference modification
-* by performing a shallow copy before each modification,
-* but it cannot avoid `existing` modification.
-* Make sure that `existing` is created internally, instead of being passed in by users.
-*/
-function mergeExternals(existing, newExternals) {
-	for (const [key, value] of Object.entries(newExternals)) {
-		const existingValue = existing[key];
-		if (existingValue !== null && typeof existingValue === "object" && value !== null && typeof value === "object" && !isResolvable(existingValue) && !isResolvable(value)) {
-			const copiedValue = { ...existingValue };
-			mergeExternals(copiedValue, value);
-			existing[key] = copiedValue;
-		} else existing[key] = value;
-		if (value && (typeof value === "object" || typeof value === "function") && getName(value) === void 0) setName(value, key);
-	}
-}
-function addArgTypesToExternals(implementation, argTypes, applyExternals) {
-	const argTypeNames = [...implementation.matchAll(/:\s*(?<arg>.*?)\s*[,)]/g)].map((found) => found ? found[1] : void 0);
-	applyExternals(Object.fromEntries(argTypes.flatMap((argType, i) => {
-		const argTypeName = argTypeNames ? argTypeNames[i] : void 0;
-		return isWgslStruct(argType) && argTypeName !== void 0 ? [[argTypeName, argType]] : [];
-	})));
+ * Merges function externals into one map.
+ */
+export function mergeFunctionExternals(fnExternals) {
+    const base = fnExternals.pluginProvided ?? fnExternals.userProvided ?? {};
+    // avoid calling any of the getters
+    const result = Object.defineProperties({}, Object.getOwnPropertyDescriptors(base));
+    for (const flatExternal of [fnExternals.args, fnExternals.out].filter((e) => e !== undefined)) {
+        for (const [key, value] of Object.entries(flatExternal)) {
+            if (key in result && result[key] !== value) {
+                throw new Error(`Key '${key}' appears in externals despite already being used for argument/return type. Please rename this external.`);
+            }
+            result[key] = value;
+        }
+    }
+    return result;
 }
-function addReturnTypeToExternals(implementation, returnType, applyExternals) {
-	const matched = implementation.match(/->\s(?<output>[\w\d_]+)\s{/);
-	const outputName = matched ? matched[1]?.trim() : void 0;
-	if (isWgslStruct(returnType) && outputName && !/\s/g.test(outputName)) applyExternals({ [outputName]: returnType });
+export function addArgTypesToExternals(implementation, argTypes, core) {
+    const argTypeNames = [...implementation.matchAll(/:\s*(?<arg>.*?)\s*[,)]/g)].map((found) => found?.[1]);
+    const args = Object.fromEntries(argTypes.flatMap((argType, i) => {
+        const argTypeName = argTypeNames?.[i];
+        return isWgslStruct(argType) && argTypeName !== undefined ? [[argTypeName, argType]] : [];
+    }));
+    core.setExternals('args', args);
 }
-function identifierRegex(name) {
-	return new RegExp(`(?<![\\w\\$_.])${name.replaceAll(".", "\\.").replaceAll("$", "\\$")}(?![\\w\\$_])`, "g");
+export function addReturnTypeToExternals(implementation, returnType, core) {
+    const matched = implementation.match(/->\s(?<output>[\w\d_]+)\s{/);
+    const outputName = matched ? matched[1]?.trim() : undefined;
+    if (isWgslStruct(returnType) && outputName && !/\s/g.test(outputName)) {
+        core.setExternals('out', { [outputName]: returnType });
+    }
 }
+export const anyIdent = /([$_\p{XID_Start}][$\p{XID_Continue}]*)/u; // WGSL ident, modified to include $
+const anyPropChain = new RegExp(`(${anyIdent.source})(\\.${anyIdent.source})*`, 'ug');
+export const boundedPropChain = new RegExp(`(?<![\\p{XID_Continue}\\$.])${anyPropChain.source}(?![\\p{XID_Continue}\\$])`, 'ug');
 /**
-* Replaces all occurrences of external names in WGSL code with their resolved values.
-* It adds all necessary definitions to the resolution context.
-* @param ctx - The resolution context.
-* @param externalMap - The external map.
-* @param wgsl - The WGSL code.
-*
-* @returns The WGSL code with all external names replaced with their resolved values.
-*/
-function replaceExternalsInWgsl(ctx, externalMap, wgsl) {
-	return Object.entries(externalMap).reduce((acc, [externalName, external]) => {
-		const externalRegex = identifierRegex(externalName);
-		if (wgsl && externalName !== "Out" && externalName !== "in" && !externalRegex.test(wgsl)) console.warn(`The external '${externalName}' wasn't used in the resolved template.`);
-		if (isResolvable(external)) return acc.replaceAll(externalRegex, ctx.resolve(external).value);
-		if (external !== null && typeof external === "object") {
-			const foundProperties = [...wgsl.matchAll(new RegExp(`${externalName.replaceAll(".", "\\.").replaceAll("$", "\\$")}\\.(?<prop>.*?)(?![\\w\\$_])`, "g"))].map((found) => found[1]);
-			return [...new Set(foundProperties)].reduce((innerAcc, prop) => prop && prop in external ? replaceExternalsInWgsl(ctx, { [`${externalName}.${prop}`]: external[prop] }, innerAcc) : innerAcc, acc);
-		}
-		console.warn(`During resolution, the external '${externalName}' has been omitted. Only TGPU resources, 'use gpu' functions, primitives, and plain JS objects can be used as externals.`);
-		return acc;
-	}, wgsl);
+ * Replaces all occurrences of external names in WGSL code with their resolved values.
+ * It adds all necessary definitions to the resolution context.
+ * @param ctx - The resolution context.
+ * @param externalMap - The external map. Assumes that keys don't contain dots.
+ * @param wgsl - The WGSL code.
+ *
+ * @returns The WGSL code with all external names replaced with their resolved values.
+ */
+export function replaceExternalsInWgsl(ctx, externalMap, wgsl) {
+    const keys = Object.keys(externalMap);
+    if (keys.length === 0) {
+        return wgsl;
+    }
+    const maybeInvalidKey = keys.find((key) => key.includes('.'));
+    if (maybeInvalidKey) {
+        throw new Error(`External key '${maybeInvalidKey}' contains invalid character '.'`);
+    }
+    return wgsl.replaceAll(boundedPropChain, (match) => {
+        const chain = match.split('.');
+        if (!Object.hasOwn(externalMap, chain.at(0))) {
+            // this prop access does not start with an external
+            return match;
+        }
+        let currentItem = externalMap;
+        let suffix = '';
+        for (const [i, elem] of chain.entries()) {
+            currentItem = currentItem[elem];
+            if (isResolvable(currentItem) || typeof currentItem === 'string') {
+                suffix = chain
+                    .slice(i + 1)
+                    .map((s) => `.${s}`)
+                    .join('');
+                if (isNamable(currentItem) && getName(currentItem) === undefined) {
+                    setName(currentItem, chain.slice(0, i + 1).join('_'));
+                }
+                break;
+            }
+            if (typeof currentItem !== 'object' || currentItem === null || i === chain.length - 1) {
+                logger.warn('external-omitted', `During resolution, the external '${chain.slice(0, i + 1).join('.')}' has been omitted. Only TGPU resources, 'use gpu' functions, primitives, and plain JS objects can be used as externals.`);
+                return match;
+            }
+        }
+        return ctx.resolve(currentItem).value + suffix;
+    });
 }
-
-//#endregion
-export { addArgTypesToExternals, addReturnTypeToExternals, mergeExternals, replaceExternalsInWgsl };

package/core/resolve/namespace.d.ts

@@ -1,29 +1,26 @@
-import { $internal } from "../../shared/symbols.js";
-import { ResolvedSnippet } from "../../data/snippet.js";
-import { ShelllessRepository } from "../../tgsl/shellless.js";
-import { TgpuLazy, TgpuSlot } from "../slot/slotTypes.js";
-
-//#region src/core/resolve/namespace.d.ts
+import type { ResolvedSnippet } from '../../data/snippet.ts';
+import { $internal } from '../../shared/symbols.ts';
+import { ShelllessRepository } from '../../tgsl/shellless.ts';
+import type { TgpuLazy, TgpuSlot } from '../slot/slotTypes.ts';
 type SlotToValueMap = Map<TgpuSlot<unknown>, unknown>;
-interface NamespaceInternal {
-  readonly takenGlobalIdentifiers: Set<string>;
-  readonly shelllessRepo: ShelllessRepository;
-  readonly strategy: 'random' | 'strict';
-  memoizedResolves: WeakMap<object, {
-    slotToValueMap: SlotToValueMap;
-    result: ResolvedSnippet;
-  }[]>;
-  memoizedLazy: WeakMap<TgpuLazy<unknown>, {
-    slotToValueMap: SlotToValueMap;
-    result: unknown;
-  }[]>;
+export interface NamespaceInternal {
+    readonly takenGlobalIdentifiers: Set<string>;
+    readonly shelllessRepo: ShelllessRepository;
+    readonly strategy: 'random' | 'strict';
+    memoizedResolves: WeakMap<object, {
+        slotToValueMap: SlotToValueMap;
+        result: ResolvedSnippet;
+    }[]>;
+    memoizedLazy: WeakMap<TgpuLazy<unknown>, {
+        slotToValueMap: SlotToValueMap;
+        result: unknown;
+    }[]>;
 }
-interface Namespace {
-  readonly [$internal]: NamespaceInternal;
+export interface Namespace {
+    readonly [$internal]: NamespaceInternal;
 }
-interface NamespaceOptions {
-  names?: 'random' | 'strict' | undefined;
+export interface NamespaceOptions {
+    names?: 'random' | 'strict' | undefined;
 }
-declare function namespace(options?: NamespaceOptions): Namespace;
-//#endregion
-export { Namespace, namespace };
+export declare function namespace(options?: NamespaceOptions): Namespace;
+export {};

package/core/resolve/namespace.js

@@ -1,24 +1,19 @@
-import { $internal } from "../../shared/symbols.js";
 import { bannedTokens, builtins } from "../../nameUtils.js";
+import { $internal } from "../../shared/symbols.js";
 import { ShelllessRepository } from "../../tgsl/shellless.js";
-
-//#region src/core/resolve/namespace.ts
-var NamespaceImpl = class {
-	[$internal];
-	constructor(strategy) {
-		this[$internal] = {
-			strategy,
-			takenGlobalIdentifiers: new Set([...bannedTokens, ...builtins]),
-			shelllessRepo: new ShelllessRepository(),
-			memoizedResolves: /* @__PURE__ */ new WeakMap(),
-			memoizedLazy: /* @__PURE__ */ new WeakMap()
-		};
-	}
-};
-function namespace(options) {
-	const { names = "strict" } = options ?? {};
-	return new NamespaceImpl(names);
+class NamespaceImpl {
+    [$internal];
+    constructor(strategy) {
+        this[$internal] = {
+            strategy,
+            takenGlobalIdentifiers: new Set([...bannedTokens, ...builtins]),
+            shelllessRepo: new ShelllessRepository(),
+            memoizedResolves: new WeakMap(),
+            memoizedLazy: new WeakMap(),
+        };
+    }
+}
+export function namespace(options) {
+    const { names = 'strict' } = options ?? {};
+    return new NamespaceImpl(names);
 }
-
-//#endregion
-export { namespace };

package/core/resolve/resolvableString.d.ts

@@ -0,0 +1,7 @@
+import { $internal, $resolve } from '../../shared/symbols.ts';
+export declare class ResolvableString {
+    #private;
+    [$internal]: boolean;
+    constructor(value: string);
+    [$resolve](): import("../../internal.ts").Snippet;
+}

package/core/resolve/resolvableString.js

@@ -0,0 +1,13 @@
+import { UnknownData } from "../../data/dataTypes.js";
+import { snip } from "../../data/snippet.js";
+import { $internal, $resolve } from "../../shared/symbols.js";
+export class ResolvableString {
+    [$internal] = true;
+    #value;
+    constructor(value) {
+        this.#value = value;
+    }
+    [$resolve]() {
+        return snip(this.#value, UnknownData, 'runtime', true);
+    }
+}

package/core/resolve/resolveData.d.ts

@@ -0,0 +1,10 @@
+import { type AnyData } from '../../data/dataTypes.ts';
+import type { ResolutionCtx } from '../../types.ts';
+/**
+ * Resolves a WGSL data-type schema to a string.
+ * @param ctx - The resolution context.
+ * @param data - The data-type to resolve.
+ *
+ * @returns The resolved data-type string.
+ */
+export declare function resolveData(ctx: ResolutionCtx, data: AnyData): string;