typegpu 0.11.8 → 0.12.0

package/core/function/comptime.js

@@ -1,56 +1,64 @@
-import { $getNameForward, $gpuCallable, $internal } from "../../shared/symbols.js";
-import { setName } from "../../shared/meta.js";
 import { WgslTypeError } from "../../errors.js";
-import { NormalState, isKnownAtComptime } from "../../types.js";
+import { setName } from "../../shared/meta.js";
+import { $getNameForward, $gpuCallable, $internal } from "../../shared/symbols.js";
 import { coerceToSnippet } from "../../tgsl/generationHelpers.js";
-
-//#region src/core/function/comptime.ts
+import { isKnownAtComptime, NormalState } from "../../types.js";
+export function isComptimeFn(value) {
+    return !!value?.[$internal]?.isComptime;
+}
 /**
-* Creates a version of `func` that can called safely in a TypeGPU function to
-* precompute and inject a value into the final shader code.
-*
-* Note how the function passed into `comptime` doesn't have to be marked with
-* 'use gpu'. That's because the function doesn't execute on the GPU, it gets
-* executed before the shader code gets sent to the GPU.
-*
-* @example
-* ```ts
-* const color = tgpu.comptime((int: number) => {
-*   const r = (int >> 16) & 0xff;
-*   const g = (int >> 8) & 0xff;
-*   const b = int & 0xff;
-*   return d.vec3f(r / 255, g / 255, b / 255);
-* });
-*
-* const material = (diffuse: d.v3f): d.v3f => {
-*   'use gpu';
-*   const albedo = color(0xff00ff);
-*   return albedo.mul(diffuse);
-* };
-* ```
-*/
-function comptime(func) {
-	const impl = ((...args) => {
-		return func(...args);
-	});
-	impl.toString = () => "comptime";
-	impl[$getNameForward] = func;
-	impl[$gpuCallable] = { call(ctx, args) {
-		if (!args.every((s) => isKnownAtComptime(s))) throw new WgslTypeError(`Called comptime function with runtime-known values: ${args.filter((s) => !isKnownAtComptime(s)).map((s) => `'${s.value}'`).join(", ")}`);
-		ctx.pushMode(new NormalState());
-		try {
-			return coerceToSnippet(func(...args.map((s) => s.value)));
-		} finally {
-			ctx.popMode();
-		}
-	} };
-	impl.$name = (label) => {
-		setName(func, label);
-		return impl;
-	};
-	Object.defineProperty(impl, $internal, { value: { isComptime: true } });
-	return impl;
+ * Creates a version of `func` that can called safely in a TypeGPU function to
+ * precompute and inject a value into the final shader code.
+ *
+ * Note how the function passed into `comptime` doesn't have to be marked with
+ * 'use gpu'. That's because the function doesn't execute on the GPU, it gets
+ * executed before the shader code gets sent to the GPU.
+ *
+ * @example
+ * ```ts
+ * const color = tgpu.comptime((int: number) => {
+ *   const r = (int >> 16) & 0xff;
+ *   const g = (int >> 8) & 0xff;
+ *   const b = int & 0xff;
+ *   return d.vec3f(r / 255, g / 255, b / 255);
+ * });
+ *
+ * const material = (diffuse: d.v3f): d.v3f => {
+ *   'use gpu';
+ *   const albedo = color(0xff00ff);
+ *   return albedo.mul(diffuse);
+ * };
+ * ```
+ */
+export function comptime(func) {
+    const impl = ((...args) => {
+        return func(...args);
+    });
+    impl.toString = () => 'comptime';
+    impl[$getNameForward] = func;
+    impl[$gpuCallable] = {
+        call(ctx, args) {
+            if (!args.every((s) => isKnownAtComptime(s))) {
+                throw new WgslTypeError(`Called comptime function with runtime-known values: ${args
+                    .filter((s) => !isKnownAtComptime(s))
+                    .map((s) => `'${s.value}'`)
+                    .join(', ')}`);
+            }
+            ctx.pushMode(new NormalState());
+            try {
+                return coerceToSnippet(func(...args.map((s) => s.value)));
+            }
+            finally {
+                ctx.popMode();
+            }
+        },
+    };
+    impl.$name = (label) => {
+        setName(func, label);
+        return impl;
+    };
+    Object.defineProperty(impl, $internal, {
+        value: { isComptime: true },
+    });
+    return impl;
 }
-
-//#endregion
-export { comptime };

package/core/function/createCallableSchema.d.ts

@@ -0,0 +1,16 @@
+import { type MapValueToSnippet, type ResolvedSnippet } from '../../data/snippet.ts';
+import { type BaseData } from '../../data/wgslTypes.ts';
+import { type DualFn, type ResolutionCtx } from '../../types.ts';
+import type { AnyFn } from './fnTypes.ts';
+type MapValueToDataType<T> = {
+    [K in keyof T]: BaseData;
+};
+interface CallableSchemaOptions<T extends AnyFn> {
+    readonly name: string;
+    readonly schema: () => BaseData;
+    readonly normalImpl: T;
+    readonly codegenImpl: (ctx: ResolutionCtx, args: MapValueToSnippet<Parameters<T>>) => ResolvedSnippet;
+    readonly argTypes: (...inArgTypes: MapValueToDataType<Parameters<T>>) => (BaseData | BaseData[])[];
+}
+export declare function callableSchema<T extends AnyFn>(options: CallableSchemaOptions<T>): DualFn<T>;
+export {};

package/core/function/createCallableSchema.js

@@ -1,44 +1,54 @@
-import { $gpuCallable } from "../../shared/symbols.js";
+import { noSideEffects, snip, } from "../../data/snippet.js";
 import { isPtr } from "../../data/wgslTypes.js";
 import { setName } from "../../shared/meta.js";
-import { noSideEffects, snip } from "../../data/snippet.js";
-import { NormalState, isKnownAtComptime } from "../../types.js";
+import { $gpuCallable } from "../../shared/symbols.js";
 import { tryConvertSnippet } from "../../tgsl/conversion.js";
-
-//#region src/core/function/createCallableSchema.ts
-function callableSchema(options) {
-	const impl = ((...args) => {
-		return options.normalImpl(...args);
-	});
-	setName(impl, options.name);
-	impl.toString = () => options.name;
-	impl[$gpuCallable] = {
-		get strictSignature() {},
-		call(ctx, args) {
-			const argTypes = options.argTypes(...args.map((s) => {
-				if (isPtr(s.dataType) && s.dataType.implicit) return s.dataType.inner;
-				return s.dataType;
-			}));
-			const converted = args.map((s, idx) => {
-				const argType = argTypes[idx];
-				if (!argType) throw new Error("Function called with invalid arguments");
-				return tryConvertSnippet(ctx, s, argType, false);
-			});
-			let result;
-			if (converted.every((s) => isKnownAtComptime(s))) {
-				ctx.pushMode(new NormalState());
-				try {
-					result = snip(options.normalImpl(...converted.map((s) => s.value)), options.schema(), "constant");
-				} finally {
-					ctx.popMode("normal");
-				}
-			} else result = options.codegenImpl(ctx, converted);
-			if (!args.some((a) => a.possibleSideEffects)) return noSideEffects(result);
-			return result;
-		}
-	};
-	return impl;
+import { isKnownAtComptime, NormalState } from "../../types.js";
+export function callableSchema(options) {
+    const impl = ((...args) => {
+        return options.normalImpl(...args);
+    });
+    setName(impl, options.name);
+    impl.toString = () => options.name;
+    impl[$gpuCallable] = {
+        get strictSignature() {
+            return undefined;
+        },
+        call(ctx, args) {
+            const argTypes = options.argTypes(...args.map((s) => {
+                // Dereference implicit pointers
+                if (isPtr(s.dataType) && s.dataType.implicit) {
+                    return s.dataType.inner;
+                }
+                return s.dataType;
+            }));
+            const converted = args.map((s, idx) => {
+                const argType = argTypes[idx];
+                if (!argType) {
+                    throw new Error('Function called with invalid arguments');
+                }
+                return tryConvertSnippet(ctx, s, argType, false);
+            });
+            let result;
+            if (converted.every((s) => isKnownAtComptime(s))) {
+                ctx.pushMode(new NormalState());
+                try {
+                    result = snip(options.normalImpl(...converted.map((s) => s.value)), options.schema(), 
+                    // Functions give up ownership of their return value
+                    /* origin */ 'constant');
+                }
+                finally {
+                    ctx.popMode('normal');
+                }
+            }
+            else {
+                result = options.codegenImpl(ctx, converted);
+            }
+            if (!args.some((a) => a.possibleSideEffects)) {
+                return noSideEffects(result);
+            }
+            return result;
+        },
+    };
+    return impl;
 }
-
-//#endregion
-export { callableSchema };

package/core/function/dualImpl.d.ts

@@ -0,0 +1,44 @@
+import { type MapValueToSnippet } from '../../data/snippet.ts';
+import { type DualFn, type ResolutionCtx } from '../../types.ts';
+import { type BaseData } from '../../data/wgslTypes.ts';
+type MapValueToDataType<T> = {
+    [K in keyof T]: BaseData;
+};
+type AnyFn = (...args: never[]) => unknown;
+interface DualImplOptions<T extends AnyFn> {
+    readonly name: string | undefined;
+    readonly normalImpl: T | string;
+    readonly codegenImpl: (ctx: ResolutionCtx, args: MapValueToSnippet<Parameters<T>>, returnType: BaseData) => string;
+    readonly signature: {
+        argTypes: (BaseData | BaseData[])[];
+        returnType: BaseData;
+    } | ((...inArgTypes: MapValueToDataType<Parameters<T>>) => {
+        argTypes: (BaseData | BaseData[])[];
+        returnType: BaseData;
+    });
+    /**
+     * Whether the function should skip trying to execute the "normal" implementation if
+     * all arguments are known at compile time.
+     * @default false
+     */
+    readonly noComptime?: boolean | undefined;
+    readonly ignoreImplicitCastWarning?: boolean | undefined;
+    /**
+     * Whether calling this function is a side-effect in itself, irrespective of
+     * its arguments. Examples:
+     *
+     * - `discard` -> `true` - it discards the fragment.
+     * - `workgroupBarrier()` -> `true` - the barrier synchronizes threads.
+     * - `sin(x)`, `abs(x)` -> `false` - these are purely value-producing; the
+     *   call itself has no observable effect beyond the returned value.
+     *
+     * When `false`, the result inherits side-effects from its arguments: it
+     * only has `possibleSideEffects: true` if at least one argument does.
+     */
+    readonly sideEffects: boolean;
+}
+export declare class MissingCpuImplError extends Error {
+    constructor(message: string | undefined);
+}
+export declare function dualImpl<T extends AnyFn>(options: DualImplOptions<T>): DualFn<T>;
+export {};

package/core/function/dualImpl.js

@@ -1,54 +1,75 @@
-import { $gpuCallable } from "../../shared/symbols.js";
-import { isPtr } from "../../data/wgslTypes.js";
-import { setName } from "../../shared/meta.js";
 import { snip } from "../../data/snippet.js";
-import { NormalState, isKnownAtComptime } from "../../types.js";
+import { setName } from "../../shared/meta.js";
+import { $gpuCallable } from "../../shared/symbols.js";
 import { tryConvertSnippet } from "../../tgsl/conversion.js";
 import { concretize } from "../../tgsl/generationHelpers.js";
-
-//#region src/core/function/dualImpl.ts
-var MissingCpuImplError = class extends Error {
-	constructor(message) {
-		super(message);
-		this.name = this.constructor.name;
-	}
-};
-function dualImpl(options) {
-	const impl = ((...args) => {
-		if (typeof options.normalImpl === "string") throw new MissingCpuImplError(options.normalImpl);
-		return options.normalImpl(...args);
-	});
-	if (options.name) setName(impl, options.name);
-	impl.toString = () => options.name ?? "<unknown>";
-	impl[$gpuCallable] = {
-		get strictSignature() {
-			return typeof options.signature !== "function" ? options.signature : void 0;
-		},
-		call(ctx, args) {
-			const { argTypes, returnType } = typeof options.signature === "function" ? options.signature(...args.map((s) => {
-				if (isPtr(s.dataType) && s.dataType.implicit) return s.dataType.inner;
-				return s.dataType;
-			})) : options.signature;
-			const converted = args.map((s, idx) => {
-				const argType = argTypes[idx];
-				if (!argType) throw new Error("Function called with invalid arguments");
-				return tryConvertSnippet(ctx, s, argType, !options.ignoreImplicitCastWarning);
-			});
-			if (!options.noComptime && converted.every((s) => isKnownAtComptime(s)) && typeof options.normalImpl === "function") {
-				ctx.pushMode(new NormalState());
-				try {
-					return snip(options.normalImpl(...converted.map((s) => s.value)), returnType, "constant");
-				} catch (e) {
-					if (!(e instanceof MissingCpuImplError)) throw e;
-				} finally {
-					ctx.popMode("normal");
-				}
-			}
-			return snip(options.codegenImpl(ctx, converted), concretize(returnType), "runtime");
-		}
-	};
-	return impl;
+import { isKnownAtComptime, NormalState } from "../../types.js";
+import { isPtr } from "../../data/wgslTypes.js";
+export class MissingCpuImplError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = this.constructor.name;
+    }
+}
+export function dualImpl(options) {
+    const impl = ((...args) => {
+        if (typeof options.normalImpl === 'string') {
+            throw new MissingCpuImplError(options.normalImpl);
+        }
+        return options.normalImpl(...args);
+    });
+    if (options.name) {
+        setName(impl, options.name);
+    }
+    impl.toString = () => options.name ?? '<unknown>';
+    impl[$gpuCallable] = {
+        get strictSignature() {
+            return typeof options.signature !== 'function' ? options.signature : undefined;
+        },
+        call(ctx, args) {
+            const { argTypes, returnType } = typeof options.signature === 'function'
+                ? options.signature(...args.map((s) => {
+                    // Dereference implicit pointers
+                    if (isPtr(s.dataType) && s.dataType.implicit) {
+                        return s.dataType.inner;
+                    }
+                    return s.dataType;
+                }))
+                : options.signature;
+            const converted = args.map((s, idx) => {
+                const argType = argTypes[idx];
+                if (!argType) {
+                    throw new Error('Function called with invalid arguments');
+                }
+                return tryConvertSnippet(ctx, s, argType, !options.ignoreImplicitCastWarning);
+            });
+            if (!options.noComptime &&
+                converted.every((s) => isKnownAtComptime(s)) &&
+                typeof options.normalImpl === 'function') {
+                ctx.pushMode(new NormalState());
+                try {
+                    return snip(options.normalImpl(...converted.map((s) => s.value)), returnType, 
+                    // Functions give up ownership of their return value
+                    /* origin */ 'constant', options.sideEffects);
+                }
+                catch (e) {
+                    // cpuImpl may in some cases be present but implemented only partially.
+                    // In that case, if the MissingCpuImplError is thrown, we fallback to codegenImpl.
+                    // If it is any other error, we just rethrow.
+                    if (!(e instanceof MissingCpuImplError)) {
+                        throw e;
+                    }
+                }
+                finally {
+                    ctx.popMode('normal');
+                }
+            }
+            const possibleSideEffects = options.sideEffects || args.some((a) => a.possibleSideEffects);
+            const concreteReturnType = concretize(returnType);
+            return snip(options.codegenImpl(ctx, converted, concreteReturnType), concreteReturnType, 
+            // Functions give up ownership of their return value
+            /* origin */ 'runtime', possibleSideEffects);
+        },
+    };
+    return impl;
 }
-
-//#endregion
-export { MissingCpuImplError, dualImpl };

package/core/function/entryInputRouter.d.ts

@@ -0,0 +1,26 @@
+import { type Snippet } from '../../data/snippet.ts';
+import { $internal, $repr } from '../../shared/symbols.ts';
+import { type BaseData } from '../../data/wgslTypes.ts';
+import type { FunctionArgumentAccess } from '../../types.ts';
+/**
+ * Routes `(input) => { input.x }` style property access to the correct WGSL
+ * expression: positional args get a direct snippet, struct fields get
+ * `structArgName.fieldName`.
+ */
+export declare class EntryInputRouter implements BaseData {
+    readonly [$internal]: Record<string, unknown>;
+    readonly type: "entry-input-router";
+    readonly [$repr]: never;
+    readonly structArg: FunctionArgumentAccess | undefined;
+    /** Maps schemaKey → { WGSL arg name, type } */
+    readonly positionalArgsMap: Map<string, FunctionArgumentAccess>;
+    constructor(structArg: FunctionArgumentAccess | undefined, positionalArgs: {
+        schemaKey: string;
+        arg: FunctionArgumentAccess;
+    }[]);
+    toString(): string;
+    accessProp(propName: string): Snippet | {
+        target: Snippet;
+        prop: string;
+    } | undefined;
+}

package/core/function/entryInputRouter.js

@@ -1,35 +1,33 @@
-import { $internal } from "../../shared/symbols.js";
+import {} from "../../data/snippet.js";
+import { $internal, $repr } from "../../shared/symbols.js";
 import { isWgslStruct } from "../../data/wgslTypes.js";
-
-//#region src/core/function/entryInputRouter.ts
 /**
-* Routes `(input) => { input.x }` style property access to the correct WGSL
-* expression: positional args get a direct snippet, struct fields get
-* `structArgName.fieldName`.
-*/
-var EntryInputRouter = class {
-	[$internal] = {};
-	type = "entry-input-router";
-	structArg;
-	/** Maps schemaKey → { WGSL arg name, type } */
-	positionalArgsMap;
-	constructor(structArg, positionalArgs) {
-		this.structArg = structArg;
-		this.positionalArgsMap = new Map(positionalArgs.map((a) => [a.schemaKey, a.arg]));
-	}
-	toString() {
-		return "entry-input-router";
-	}
-	accessProp(propName) {
-		const positionalEntry = this.positionalArgsMap.get(propName);
-		if (positionalEntry) return positionalEntry();
-		const structSnippet = this.structArg?.();
-		if (structSnippet && isWgslStruct(structSnippet.dataType)) return {
-			target: structSnippet,
-			prop: propName
-		};
-	}
-};
-
-//#endregion
-export { EntryInputRouter };
+ * Routes `(input) => { input.x }` style property access to the correct WGSL
+ * expression: positional args get a direct snippet, struct fields get
+ * `structArgName.fieldName`.
+ */
+export class EntryInputRouter {
+    [$internal] = {};
+    type = 'entry-input-router';
+    structArg;
+    /** Maps schemaKey → { WGSL arg name, type } */
+    positionalArgsMap;
+    constructor(structArg, positionalArgs) {
+        this.structArg = structArg;
+        this.positionalArgsMap = new Map(positionalArgs.map((a) => [a.schemaKey, a.arg]));
+    }
+    toString() {
+        return 'entry-input-router';
+    }
+    accessProp(propName) {
+        const positionalEntry = this.positionalArgsMap.get(propName);
+        if (positionalEntry) {
+            return positionalEntry();
+        }
+        const structSnippet = this.structArg?.();
+        if (structSnippet && isWgslStruct(structSnippet.dataType)) {
+            return { target: structSnippet, prop: propName };
+        }
+        return undefined;
+    }
+}

package/core/function/extractArgs.d.ts

@@ -0,0 +1,38 @@
+interface FunctionArgsInfo {
+    args: ArgInfo[];
+    ret: ReturnInfo | undefined;
+    range: {
+        begin: number;
+        end: number;
+    };
+}
+interface ArgInfo {
+    identifier: string;
+    attributes: string[];
+    type: string | undefined;
+}
+interface ReturnInfo {
+    attributes: string[];
+    type: string;
+}
+/**
+ * Extracts info about arguments of a given WGSL function string.
+ * @example
+ * const code = `
+ *   fn add(a: i32, ＠location(0) b: i32, c) -> i32 {
+ *     return a + b + c;
+ *   }`;
+ *
+ * extractArgs(code);
+ * // {
+ * //   args: [
+ * //     { identifier: 'a', attributes: [], type: 'i32' },
+ * //     { identifier: 'b', attributes: ['＠location(0)'], type: 'i32' },
+ * //     { identifier: 'c', attributes: [], type: undefined }
+ * //   ],
+ * //   ret: { type: 'i32', attributes: [] },
+ * //   range: { begin: 11, end: 51 }
+ * // }
+ */
+export declare function extractArgs(rawCode: string): FunctionArgsInfo;
+export {};