typegpu 0.11.9 → 0.12.0

package/tgsl/jsPolyfills.js

@@ -1,44 +1,46 @@
 import { f32 } from "../data/numeric.js";
-import { abs, acos, acosh, asin, asinh, atan, atan2, atanh, ceil, cos, cosh, countLeadingZeros, exp, floor, log, log2, max, min, pow, sign, sin, sinh, sqrt, tan, tanh, trunc } from "../std/numeric.js";
-
-//#region src/tgsl/jsPolyfills.ts
-const mathToStd = new Map([
-	[Math.abs, abs],
-	[Math.acos, acos],
-	[Math.acosh, acosh],
-	[Math.asin, asin],
-	[Math.asinh, asinh],
-	[Math.atan, atan],
-	[Math.atan2, atan2],
-	[Math.atanh, atanh],
-	[Math.ceil, ceil],
-	[Math.cos, cos],
-	[Math.cosh, cosh],
-	[Math.exp, exp],
-	[Math.floor, floor],
-	[Math.fround, f32],
-	[Math.clz32, countLeadingZeros],
-	[Math.trunc, trunc],
-	[Math.log, log],
-	[Math.log2, log2],
-	[Math.pow, pow],
-	[Math.sign, sign],
-	[Math.sin, sin],
-	[Math.sinh, sinh],
-	[Math.sqrt, sqrt],
-	[Math.tan, tan],
-	[Math.tanh, tanh],
-	[Math.max, max],
-	[Math.min, min]
+import { abs, acos, acosh, asin, asinh, atan, atan2, atanh, ceil, cos, cosh, countLeadingZeros, exp, floor, log, log2, max, min, pow, sign, sin, sinh, sqrt, tan, tanh, trunc, } from "../std/numeric.js";
+export const mathToStd = new Map([
+    // -- one to one Math to WGSL correlation --
+    [Math.abs, abs],
+    [Math.acos, acos],
+    [Math.acosh, acosh],
+    [Math.asin, asin],
+    [Math.asinh, asinh],
+    [Math.atan, atan],
+    [Math.atan2, atan2],
+    [Math.atanh, atanh],
+    [Math.ceil, ceil],
+    [Math.cos, cos],
+    [Math.cosh, cosh],
+    [Math.exp, exp],
+    [Math.floor, floor],
+    [Math.fround, f32],
+    [Math.clz32, countLeadingZeros],
+    [Math.trunc, trunc],
+    [Math.log, log],
+    [Math.log2, log2],
+    [Math.pow, pow],
+    [Math.sign, sign],
+    [Math.sin, sin],
+    [Math.sinh, sinh],
+    [Math.sqrt, sqrt],
+    [Math.tan, tan],
+    [Math.tanh, tanh],
+    // -- varying in Math and two arg in WGSL, but we support varying in std --
+    [Math.max, max],
+    [Math.min, min],
+    // -- possible if we extend std --
+    // [Math.cbrt, ???],
+    // [Math.log10, ???],
+    // [Math.log1p, ???],
+    // [Math.f16round, ???],
+    // [Math.hypot, ???],
+    // [Math.expm1, ???],
+    // -- skipped --
+    // [Math.random, ???],
+    // [Math.imul, ???],
+    // [Math.round, ???], // round(2.5) is 3 in JS and 2 in WGSL
 ]);
-const supportedLogOps = () => [
-	console.log,
-	console.debug,
-	console.info,
-	console.warn,
-	console.error,
-	console.clear
-];
-
-//#endregion
-export { mathToStd, supportedLogOps };
+// deferring the array creation lets us handle console mocks
+export const supportedLogOps = () => [console.log, console.debug, console.info, console.warn, console.error, console.clear];

package/tgsl/makeDereferenceable.d.ts

@@ -0,0 +1,48 @@
+import type { Snippet } from '../data/snippet.ts';
+import type { SimulationState } from '../types.ts';
+import type { makeResolvable } from './makeResolvable.ts';
+/**
+ * WARNING: This is an API that touches a lot of internals, and is not stable
+ * (can change between patches). You should probably talk to the TypeGPU team
+ * before using this, maybe we can provide a better public API for your use case.
+ *
+ * Defines additional properties on `value` (mutates it) that makes TypeGPU
+ * understand how it should handle using .$ on that object. All dereferenceable
+ * value must also be made resolvable (through the makeResolvable API).
+ *
+ * `value` can in particular be the prototype of a class, meaning all instances
+ * of that class will be dereferenceable.
+ */
+export declare function makeDereferenceable<T extends makeResolvable.Resolvable, TValue>(value: T, options: makeDereferenceable.Options<T, TValue>): T & {
+    $: TValue;
+};
+export declare namespace makeDereferenceable {
+    interface Options<T extends makeResolvable.Resolvable, TValue> {
+        normalMode: {
+            get(this: T): TValue;
+            set?(this: T, value: TValue): void;
+        };
+        codegenMode: {
+            /**
+             * Should return a representative value that is accessible on the GPU.
+             * If not provided, `codegenMode.getBaseSnippet` is used instead.
+             */
+            get(this: T): TValue;
+        } | {
+            /**
+             * Used if `codegenMode.get` is not defined. The snippet returned from
+             * this function should represent the value that exists on .$
+             *
+             * The value of the snippet should in most cases be `trackingProxy` that
+             * is provided as the argument.
+             * @param trackingProxy
+             */
+            getBaseSnippet(this: T, trackingProxy: TValue): Snippet;
+        };
+        /** @deprecated 'simulate' mode is planned to be removed in the future */
+        simulateMode?: {
+            get?(this: T, state: SimulationState): TValue;
+            set?(this: T, state: SimulationState, value: TValue): void;
+        };
+    }
+}

package/tgsl/makeDereferenceable.js

@@ -0,0 +1,86 @@
+import { $gpuValueOf, $internal, $ownSnippet, $resolve } from "../shared/symbols.js";
+import { valueProxyHandler } from "../core/valueProxyUtils.js";
+import { getExecMode } from "../execMode.js";
+import { assertExhaustive } from "../shared/utilityTypes.js";
+/**
+ * WARNING: This is an API that touches a lot of internals, and is not stable
+ * (can change between patches). You should probably talk to the TypeGPU team
+ * before using this, maybe we can provide a better public API for your use case.
+ *
+ * Defines additional properties on `value` (mutates it) that makes TypeGPU
+ * understand how it should handle using .$ on that object. All dereferenceable
+ * value must also be made resolvable (through the makeResolvable API).
+ *
+ * `value` can in particular be the prototype of a class, meaning all instances
+ * of that class will be dereferenceable.
+ */
+export function makeDereferenceable(value, options) {
+    Object.defineProperty(value, $gpuValueOf, {
+        get() {
+            if ('get' in options.codegenMode) {
+                return options.codegenMode.get.apply(this);
+            }
+            // oxlint-disable-next-line typescript/no-this-alias
+            const resource = this;
+            return new Proxy({
+                [$internal]: true,
+                get [$ownSnippet]() {
+                    if (!('getBaseSnippet' in options.codegenMode)) {
+                        throw new Error(`Expected 'getBaseSnippet' to be defined.`);
+                    }
+                    return options.codegenMode.getBaseSnippet.apply(resource, [this]);
+                },
+                [$resolve]: (ctx) => ctx.resolve(resource),
+                toString: () => `${resource.toString()}.$`,
+            }, valueProxyHandler);
+        },
+    });
+    Object.defineProperty(value, '$', {
+        get() {
+            const mode = getExecMode();
+            if (mode.type === 'codegen') {
+                return this[$gpuValueOf];
+            }
+            if (mode.type === 'simulate') {
+                if (options.simulateMode?.get) {
+                    return options.simulateMode.get.apply(this, [mode]);
+                }
+                return options.normalMode.get.apply(this);
+            }
+            if (mode.type === 'normal') {
+                return options.normalMode.get.apply(this);
+            }
+            return assertExhaustive(mode, 'makeDereferenceable.ts#$ (get)');
+        },
+        set(value) {
+            const mode = getExecMode();
+            if (mode.type === 'normal') {
+                if (!options.normalMode.set) {
+                    throw new Error(`'${this.toString()}' cannot be set in normal mode`);
+                }
+                options.normalMode.set.apply(this, [value]);
+                return;
+            }
+            if (mode.type === 'simulate') {
+                if (options.simulateMode?.set) {
+                    options.simulateMode.set.apply(this, [mode, value]);
+                }
+                else if (options.normalMode.set) {
+                    // Falling back to the 'normal' set
+                    options.normalMode.set.apply(this, [value]);
+                }
+                else {
+                    throw new Error(`'${this.toString()}' cannot be set in simulate mode`);
+                }
+                return;
+            }
+            if (mode.type === 'codegen') {
+                // The shader generator handles assignment, and does not defer to
+                // whatever's being assigned to generate the shader code.
+                throw new Error('Unreachable makeDerefenceable.ts#$ (set)');
+            }
+            return assertExhaustive(mode, 'makeDereferenceable.ts#$ (set)');
+        },
+    });
+    return value;
+}

package/tgsl/makeResolvable.d.ts

@@ -0,0 +1,22 @@
+import { type ResolvedSnippet } from '../data/snippet.ts';
+import type { ResolutionCtx, SelfResolvable } from '../types.ts';
+/**
+ * WARNING: This is an API that touches a lot of internals, and is not stable
+ * (can change between patches). You should probably talk to the TypeGPU team
+ * before using this, maybe we can provide a better public API for your use case.
+ *
+ * Defines additional properties on `value` (mutates it) that makes TypeGPU
+ * understand how it should handle passing this object to the `tgpu.resolve`
+ * API, or just how to generate shader code from it to begin with.
+ *
+ * `value` can in particular be the prototype of a class, meaning all instances
+ * of that class will be resolvable.
+ */
+export declare function makeResolvable<T extends object>(value: T, options: makeResolvable.Options<T>): T & SelfResolvable;
+export declare namespace makeResolvable {
+    interface Options<T> {
+        resolve(this: T, ctx: ResolutionCtx): ResolvedSnippet;
+        asString(this: T): string;
+    }
+    type Resolvable = SelfResolvable;
+}

package/tgsl/makeResolvable.js

@@ -0,0 +1,33 @@
+import {} from "../data/snippet.js";
+import { $internal, $resolve, isMarkedInternal } from "../shared/symbols.js";
+/**
+ * WARNING: This is an API that touches a lot of internals, and is not stable
+ * (can change between patches). You should probably talk to the TypeGPU team
+ * before using this, maybe we can provide a better public API for your use case.
+ *
+ * Defines additional properties on `value` (mutates it) that makes TypeGPU
+ * understand how it should handle passing this object to the `tgpu.resolve`
+ * API, or just how to generate shader code from it to begin with.
+ *
+ * `value` can in particular be the prototype of a class, meaning all instances
+ * of that class will be resolvable.
+ */
+export function makeResolvable(value, options) {
+    if (!isMarkedInternal(value)) {
+        Object.defineProperty(value, $internal, {
+            value: true,
+            writable: true,
+        });
+    }
+    Object.defineProperty(value, 'toString', {
+        value() {
+            return options.asString.apply(this);
+        },
+    });
+    Object.defineProperty(value, $resolve, {
+        value(ctx) {
+            return options.resolve.apply(this, [ctx]);
+        },
+    });
+    return value;
+}

package/tgsl/shaderGenerator.d.ts

@@ -1,24 +1,84 @@
-import { ResolvedSnippet, Snippet } from "../data/snippet.js";
-import { GenerationCtx } from "./generationHelpers.js";
-import { ConstantDefinitionOptions, FunctionDefinitionOptions, VariableDefinitionOptions } from "./shaderGenerator_members.js";
-import { BaseData } from "../data/wgslTypes.js";
-
-//#region src/tgsl/shaderGenerator.d.ts
-
+import type { Block } from 'tinyest';
+import type { BaseData } from '../data/wgslTypes.ts';
+import type { ResolvedSnippet, Snippet } from '../data/snippet.ts';
+import type { VariableScope } from '../core/variable/tgpuVariable.ts';
+import type { BindableBufferUsage, FunctionArgument, ResolutionCtx, ShaderStage } from '../types.ts';
+export interface FunctionDefinitionOptions {
+    readonly functionType: 'normal' | ShaderStage;
+    readonly name: string;
+    readonly workgroupSize?: readonly number[] | undefined;
+    readonly args: readonly FunctionArgument[];
+    readonly body: Block;
+    determineReturnType(): BaseData;
+}
+export interface ConstantDefinitionOptions {
+    readonly id: string;
+    readonly dataType: BaseData;
+    readonly init: Snippet;
+}
+export interface VariableDefinitionOptions {
+    readonly scope: VariableScope | BindableBufferUsage | 'handle';
+    readonly id: string;
+    readonly dataType: BaseData;
+    readonly init: Snippet | undefined;
+    readonly group?: string | undefined;
+    readonly binding?: number | undefined;
+}
+export interface ResolvedStatement {
+    code: string;
+    /**
+     * True if the statement (or statements) in `code` define variables that would
+     * be scoped to the nearest block.
+     */
+    definesInNearestScope: boolean;
+    /**
+     * If not undefined, the execution of the statement (or statements) in `code`
+     * *ends* in a control flow statement that will always cause the subsequent
+     * statements to not be executed.
+     *
+     * For example, statements with code set to `return;`, `break;` and  `continue;`
+     * will have this field set to 'return', 'break' and 'continue' respectively.
+     * So will any sequence of statements that end with them, or `return value;`
+     *
+     * However, the statement `if (cond) { return; }` has `endsWithControlFlow` set to `undefined`,
+     * because it's not guaranteed that including this code in a sequence will cause all
+     * subsequent statements to be unreachable.
+     */
+    endsWithControlFlow?: 'return' | 'break' | 'continue' | undefined;
+}
+/**
+ * **NOTE: This is an unstable API and may change in the future.**
+ *
+ * Used to instantiate generators, once per resolution context
+ */
+export interface ShaderGeneratorClass<T extends ShaderGenerator = ShaderGenerator> {
+    new (): T;
+}
+/**
+ * Binary operators that can appear in WGSL
+ */
+export type BinaryOperator = '=' | '^' | '|' | '&' | '*' | '/' | '%' | '+' | '-' | '<<' | '>>' | '<' | '>' | '<=' | '>=' | '==' | '!=' | '&&' | '||' | '+=' | '-=' | '*=' | '/=' | '%=' | '<<=' | '>>=' | '&=' | '|=' | '^=';
+/**
+ * Represents generators that, once instantiated, will generate `wgsl` (as opposed to e.g. `glsl`)
+ */
+export type WgslGeneratorClass = ShaderGeneratorClass<ShaderGenerator & {
+    languageKey: 'wgsl';
+}>;
 /**
  * **NOTE: This is an unstable API and may change in the future.**
  *
  * An interface meant to be used by other systems to generate snippets of
  * shader code in the target language (WGSL, GLSL, etc.).
  */
-interface ShaderGenerator {
-  initGenerator(ctx: GenerationCtx): void;
-  declareGlobalConst(options: ConstantDefinitionOptions): ResolvedSnippet;
-  declareGlobalVar(options: VariableDefinitionOptions): ResolvedSnippet;
-  functionDefinition(options: FunctionDefinitionOptions): string;
-  typeInstantiation(schema: BaseData, args: readonly Snippet[]): ResolvedSnippet;
-  typeAnnotation(schema: BaseData): string;
-  numericLiteral(value: number, schema: BaseData): ResolvedSnippet;
+export interface ShaderGenerator {
+    readonly languageKey: string;
+    initGenerator(ctx: ResolutionCtx): void;
+    declareGlobalConst(options: ConstantDefinitionOptions): ResolvedSnippet;
+    declareGlobalVar(options: VariableDefinitionOptions): ResolvedSnippet;
+    functionDefinition(options: FunctionDefinitionOptions): string;
+    typeInstantiation(schema: BaseData, args: readonly Snippet[]): ResolvedSnippet;
+    numericLiteral(value: number, schema: BaseData): ResolvedSnippet;
+    emitTypeAnnotation(schema: BaseData): string;
+    emitCall(name: string, templateParams: readonly Snippet[], args: readonly Snippet[]): string;
+    emitBinaryOp(lhs: Snippet, op: BinaryOperator, rhs: Snippet): string;
 }
-//#endregion
-export { ShaderGenerator };

package/tgsl/shaderGenerator.js

@@ -0,0 +1 @@
+export {};

package/tgsl/shellless.d.ts

@@ -1,11 +1,8 @@
-import { Snippet } from "../data/snippet.js";
-import { ShelllessImpl } from "../core/function/shelllessImpl.js";
-
-//#region src/tgsl/shellless.d.ts
+import { type ShelllessImpl } from '../core/function/shelllessImpl.ts';
+import type { Snippet } from '../data/snippet.ts';
 type AnyFn = (...args: never[]) => unknown;
-declare class ShelllessRepository {
-  cache: Map<AnyFn, ShelllessImpl[]>;
-  get(fn: AnyFn, argSnippets: Snippet[] | undefined): ShelllessImpl | undefined;
+export declare class ShelllessRepository {
+    cache: Map<AnyFn, ShelllessImpl[]>;
+    get(fn: AnyFn, argSnippets: readonly Snippet[] | undefined): ShelllessImpl | undefined;
 }
-//#endregion
-export { ShelllessRepository };
+export {};

package/tgsl/shellless.js

@@ -1,48 +1,78 @@
-import { isPtr, isWgslArray, isWgslStruct } from "../data/wgslTypes.js";
-import { getFunctionMetadata, getName } from "../shared/meta.js";
+import { createShelllessImpl } from "../core/function/shelllessImpl.js";
 import { UnknownData } from "../data/dataTypes.js";
-import { WgslTypeError } from "../errors.js";
 import { RefOperator } from "../data/ref.js";
+import { isPtr, isWgslArray, isWgslStruct } from "../data/wgslTypes.js";
+import { WgslTypeError } from "../errors.js";
+import { getFunctionMetadata, getName } from "../shared/meta.js";
 import { concretize } from "./generationHelpers.js";
-import { createShelllessImpl } from "../core/function/shelllessImpl.js";
-
-//#region src/tgsl/shellless.ts
 function shallowEqualSchemas(a, b) {
-	if (a.type !== b.type) return false;
-	if (isPtr(a) && isPtr(b)) return a.access === b.access && a.addressSpace === b.addressSpace && a.implicit === b.implicit && shallowEqualSchemas(a.inner, b.inner);
-	if (isWgslArray(a) && isWgslArray(b)) return a.elementCount === b.elementCount && shallowEqualSchemas(a.elementType, b.elementType);
-	if (isWgslStruct(a) && isWgslStruct(b)) return a === b;
-	return true;
+    if (a.type !== b.type)
+        return false;
+    if (isPtr(a) && isPtr(b)) {
+        return (a.access === b.access &&
+            a.addressSpace === b.addressSpace &&
+            a.implicit === b.implicit &&
+            shallowEqualSchemas(a.inner, b.inner));
+    }
+    if (isWgslArray(a) && isWgslArray(b)) {
+        return a.elementCount === b.elementCount && shallowEqualSchemas(a.elementType, b.elementType);
+    }
+    if (isWgslStruct(a) && isWgslStruct(b)) {
+        // Only structs with the same identity are considered equal
+        return a === b;
+    }
+    return true;
+}
+export class ShelllessRepository {
+    cache = new Map();
+    get(fn, argSnippets) {
+        const meta = getFunctionMetadata(fn);
+        if (!meta) {
+            return undefined;
+        }
+        if (!argSnippets && meta.ast.params.length > 0) {
+            throw new Error(`Cannot resolve '${getName(fn)}' directly, because it expects arguments. Either call it from another function, or wrap it in a shell`);
+        }
+        const argTypes = (argSnippets ?? []).map((s, index) => {
+            if (s.value instanceof RefOperator) {
+                if (s.dataType === UnknownData) {
+                    throw new WgslTypeError(`d.ref() created with primitive types must be stored in a variable before use`);
+                }
+                return s.dataType;
+            }
+            if (s.dataType === UnknownData) {
+                throw new Error(`Passed illegal value ${s.value} as the #${index} argument to ${getName(fn) ?? '<unnamed>'}(...)\n` +
+                    `Shellless functions can only accept arguments representing WGSL resources: constructible WGSL types, d.refs, samplers or texture views.\n` +
+                    `Remember, that arguments such as samplers, texture views, accessors, slots etc. should be dereferenced via '.$' first.`);
+            }
+            let type = concretize(s.dataType);
+            if (isPtr(type) && type.implicit) {
+                // If the pointer was made implicitly (e.g. by assigning a reference to a const variable),
+                // then we dereference the pointer before passing it to the function. The main reason for this,
+                // is that in TypeScript, the type of the function accepts a value, not the value wrapped in
+                // d.ref<> (so it's not considered mutable from the perspective of the function)
+                // Example:
+                // const foo = layout.$.boids;
+                // bar(foo)
+                //     ^^^
+                type = type.inner;
+            }
+            return type;
+        });
+        let cache = this.cache.get(fn);
+        if (cache) {
+            const variant = cache.find((v) => v.argTypes.length === argTypes.length &&
+                v.argTypes.every((t, i) => shallowEqualSchemas(t, argTypes[i])));
+            if (variant) {
+                return variant;
+            }
+        }
+        else {
+            cache = [];
+            this.cache.set(fn, cache);
+        }
+        const shellless = createShelllessImpl(argTypes, fn);
+        cache.push(shellless);
+        return shellless;
+    }
 }
-var ShelllessRepository = class {
-	cache = /* @__PURE__ */ new Map();
-	get(fn, argSnippets) {
-		const meta = getFunctionMetadata(fn);
-		if (!meta) return;
-		if (!argSnippets && meta.ast.params.length > 0) throw new Error(`Cannot resolve '${getName(fn)}' directly, because it expects arguments. Either call it from another function, or wrap it in a shell`);
-		const argTypes = (argSnippets ?? []).map((s, index) => {
-			if (s.value instanceof RefOperator) {
-				if (s.dataType === UnknownData) throw new WgslTypeError(`d.ref() created with primitive types must be stored in a variable before use`);
-				return s.dataType;
-			}
-			if (s.dataType === UnknownData) throw new Error(`Passed illegal value ${s.value} as the #${index} argument to ${getName(fn) ?? "<unnamed>"}(...)\nShellless functions can only accept arguments representing WGSL resources: constructible WGSL types, d.refs, samplers or texture views.\nRemember, that arguments such as samplers, texture views, accessors, slots etc. should be dereferenced via '.$' first.`);
-			let type = concretize(s.dataType);
-			if (isPtr(type) && type.implicit) type = type.inner;
-			return type;
-		});
-		let cache = this.cache.get(fn);
-		if (cache) {
-			const variant = cache.find((v) => v.argTypes.length === argTypes.length && v.argTypes.every((t, i) => shallowEqualSchemas(t, argTypes[i])));
-			if (variant) return variant;
-		} else {
-			cache = [];
-			this.cache.set(fn, cache);
-		}
-		const shellless = createShelllessImpl(argTypes, fn);
-		cache.push(shellless);
-		return shellless;
-	}
-};
-
-//#endregion
-export { ShelllessRepository };