typegpu 0.11.8 → 0.12.0

package/core/unroll/tgpuUnroll.js

@@ -1,96 +1,87 @@
 import { $gpuCallable, $internal, $resolve } from "../../shared/symbols.js";
 import { setName } from "../../shared/meta.js";
-import { snip } from "../../data/snippet.js";
-import { stitch } from "../resolve/stitch.js";
-
-//#region src/core/unroll/tgpuUnroll.ts
+import { withValue } from "../../data/snippet.js";
 /**
-* The result of calling `tgpu.unroll(...)`. The code responsible for
-* generating shader code can check if the value of a snippet is
-* an instance of `UnrollableIterable`, and act accordingly.
-*/
-var UnrollableIterable = class {
-	[$internal] = true;
-	snippet;
-	constructor(snippet) {
-		this.snippet = snippet;
-	}
-	[$resolve](_ctx) {
-		return snip(stitch`${this.snippet}`, this.snippet.dataType, this.snippet.origin);
-	}
-};
+ * The result of calling `tgpu.unroll(...)`. The code responsible for
+ * generating shader code can check if the value of a snippet is
+ * an instance of `UnrollableIterable`, and act accordingly.
+ */
+export class UnrollableIterable {
+    [$internal] = true;
+    snippet;
+    constructor(snippet) {
+        this.snippet = snippet;
+    }
+    [$resolve](ctx) {
+        return ctx.resolveSnippet(this.snippet);
+    }
+}
 /**
-* Marks an iterable to be unrolled by the shader generator when used in a for loop.
-*
-* @example
-* ```ts
-* const neighborOffsets = [d.vec2i(0, 1), d.vec2i(0, -1), d.vec2i(1, 0), d.vec2i(-1, 0)];
-*
-* // Unrolls into 4 blocks of code, one for each offset.
-* for (const offset of tgpu.unroll(neighborOffsets)) {
-*   // ...
-* }
-* ```
-*
-* If you'd like to unroll over a range of numbers, use `tgpu.unroll(std.range(n))`.
-*
-* @example
-* ```ts
-* // (...)
-* const FBM_OCTAVES = 3;
-*
-* function fbm(pos: d.v3f): number {
-*   'use gpu';
-*   let sum = d.f32();
-*
-*   // i = 0, 1, 2
-*   for (const i of tgpu.unroll(std.range(FBM_OCTAVES))) {
-*     sum +=
-*       noise3d(pos * (CLOUD_FREQUENCY * FBM_LACUNARITY ** i)) *
-*       (CLOUD_AMPLITUDE * FBM_PERSISTENCE ** i);
-*   }
-*
-*   return sum;
-* }
-*
-* ```
-*
-* Generates:
-*
-* ```wgsl
-* // (...)
-*
-* fn fbm(pos: vec3f) -> f32 {
-*   var sum = 0f;
-*   // unrolled iteration #0
-*   {
-*     sum += noise3d(pos * 1.4f) * 1f;
-*   }
-*   // unrolled iteration #1
-*   {
-*     sum += noise3d(pos * 2.8f) * 0.5f;
-*   }
-*   // unrolled iteration #2
-*   {
-*     sum += noise3d(pos * 5.6f) * 0.25f;
-*   }
-*   return sum;
-* }
-* ```
-*/
-const unroll = (() => {
-	function jsImpl(iterable) {
-		return iterable;
-	}
-	const impl = jsImpl;
-	setName(impl, "unroll");
-	impl.toString = () => "unroll";
-	impl[$internal] = true;
-	impl[$gpuCallable] = { call(_ctx, [value]) {
-		return snip(new UnrollableIterable(value), value.dataType, value.origin);
-	} };
-	return impl;
+ * Marks an iterable to be unrolled by the shader generator when used in a for loop.
+ *
+ * @example
+ * ```ts
+ * const neighborOffsets = [d.vec2i(0, 1), d.vec2i(0, -1), d.vec2i(1, 0), d.vec2i(-1, 0)];
+ *
+ * // Unrolls into 4 blocks of code, one for each offset.
+ * for (const offset of tgpu.unroll(neighborOffsets)) {
+ *   // ...
+ * }
+ * ```
+ *
+ * If you'd like to unroll over a range of numbers, use `tgpu.unroll(std.range(n))`.
+ *
+ * @example
+ * ```ts
+ * // (...)
+ * const FBM_OCTAVES = 3;
+ *
+ * function fbm(pos: d.v3f): number {
+ *   'use gpu';
+ *   let sum = d.f32();
+ *
+ *   // i = 0, 1, 2
+ *   for (const i of tgpu.unroll(std.range(FBM_OCTAVES))) {
+ *     sum +=
+ *       noise3d(pos * (CLOUD_FREQUENCY * FBM_LACUNARITY ** i)) *
+ *       (CLOUD_AMPLITUDE * FBM_PERSISTENCE ** i);
+ *   }
+ *
+ *   return sum;
+ * }
+ *
+ * ```
+ *
+ * Generates:
+ *
+ * ```wgsl
+ * // (...)
+ *
+ * fn fbm(pos: vec3f) -> f32 {
+ *   var sum = 0f;
+ *   // unrolled iteration #0
+ *   sum += noise3d(pos * 1.4f) * 1f;
+ *   // unrolled iteration #1
+ *   sum += noise3d(pos * 2.8f) * 0.5f;
+ *   // unrolled iteration #2
+ *   sum += noise3d(pos * 5.6f) * 0.25f;
+ *   // ---
+ *   return sum;
+ * }
+ * ```
+ */
+export const unroll = (() => {
+    function jsImpl(iterable) {
+        return iterable;
+    }
+    const impl = jsImpl;
+    setName(impl, 'unroll');
+    impl.toString = () => 'unroll';
+    impl[$internal] = true;
+    impl[$gpuCallable] = {
+        call(_ctx, [value]) {
+            return withValue(new UnrollableIterable(value), value);
+        },
+    };
+    return impl;
 })();
-
-//#endregion
-export { UnrollableIterable, unroll };

package/core/valueProxyUtils.d.ts

@@ -0,0 +1,3 @@
+import { type SelfResolvable, type WithOwnSnippet } from '../types.ts';
+export declare const valueProxyHandler: ProxyHandler<SelfResolvable & WithOwnSnippet>;
+export declare function getGpuValueRecursively<T>(value: unknown): T;

package/core/valueProxyUtils.js

@@ -1,44 +1,55 @@
-import { $internal, $ownSnippet, $resolve } from "../shared/symbols.js";
-import { getOwnSnippet } from "../types.js";
 import { getGPUValue } from "../getGPUValue.js";
-import { accessProp } from "../tgsl/accessProp.js";
+import { $internal, $ownSnippet, $resolve } from "../shared/symbols.js";
 import { accessIndex } from "../tgsl/accessIndex.js";
-
-//#region src/core/valueProxyUtils.ts
-const valueProxyHandler = { get(target, prop) {
-	if (prop in target) return Reflect.get(target, prop);
-	if (prop === "toString" || prop === Symbol.toStringTag || prop === Symbol.toPrimitive) return () => target.toString();
-	if (typeof prop === "symbol") return;
-	const targetSnippet = getOwnSnippet(target);
-	const index = Number(prop);
-	if (!Number.isNaN(index)) {
-		const accessed$1 = accessIndex(targetSnippet, index);
-		if (!accessed$1) return;
-		return new Proxy({
-			[$internal]: true,
-			[$resolve]: (ctx) => ctx.resolve(accessed$1.value, accessed$1.dataType),
-			[$ownSnippet]: accessed$1,
-			toString: () => `${String(target)}[${prop}]`
-		}, valueProxyHandler);
-	}
-	const accessed = accessProp(targetSnippet, String(prop));
-	if (!accessed) return;
-	return new Proxy({
-		[$internal]: true,
-		[$resolve]: (ctx) => ctx.resolve(accessed.value, accessed.dataType),
-		[$ownSnippet]: accessed,
-		toString: () => `${String(target)}.${prop}`
-	}, valueProxyHandler);
-} };
-function getGpuValueRecursively(value) {
-	let unwrapped = value;
-	while (true) {
-		const gpuValue = getGPUValue(unwrapped);
-		if (!gpuValue) break;
-		unwrapped = gpuValue;
-	}
-	return unwrapped;
+import { accessProp } from "../tgsl/accessProp.js";
+import { getOwnSnippet } from "../types.js";
+export const valueProxyHandler = {
+    get(target, prop) {
+        if (prop in target) {
+            return Reflect.get(target, prop);
+        }
+        if (prop === 'toString' || prop === Symbol.toStringTag || prop === Symbol.toPrimitive) {
+            return () => target.toString();
+        }
+        if (typeof prop === 'symbol') {
+            return undefined;
+        }
+        const targetSnippet = getOwnSnippet(target);
+        const index = Number(prop);
+        if (!Number.isNaN(index)) {
+            const accessed = accessIndex(targetSnippet, index);
+            if (!accessed) {
+                // Prop was not found, must be missing from this object
+                return undefined;
+            }
+            return new Proxy({
+                [$internal]: true,
+                [$resolve]: (ctx) => ctx.resolveSnippet(accessed),
+                [$ownSnippet]: accessed,
+                toString: () => `${String(target)}[${prop}]`,
+            }, valueProxyHandler);
+        }
+        const accessed = accessProp(targetSnippet, String(prop));
+        if (!accessed) {
+            // Prop was not found, must be missing from this object
+            return undefined;
+        }
+        return new Proxy({
+            [$internal]: true,
+            [$resolve]: (ctx) => ctx.resolveSnippet(accessed),
+            [$ownSnippet]: accessed,
+            toString: () => `${String(target)}.${prop}`,
+        }, valueProxyHandler);
+    },
+};
+export function getGpuValueRecursively(value) {
+    let unwrapped = value;
+    while (true) {
+        const gpuValue = getGPUValue(unwrapped);
+        if (!gpuValue) {
+            break;
+        }
+        unwrapped = gpuValue;
+    }
+    return unwrapped;
 }
-
-//#endregion
-export { getGpuValueRecursively, valueProxyHandler };

package/core/variable/tgpuVariable.d.ts

@@ -1,25 +1,26 @@
-import { TgpuNamable } from "../../shared/meta.js";
-import { $gpuValueOf, $internal } from "../../shared/symbols.js";
-import { BaseData } from "../../data/wgslTypes.js";
-import { InferGPU } from "../../shared/repr.js";
-import { AnyData } from "../../data/dataTypes.js";
-
-//#region src/core/variable/tgpuVariable.d.ts
-type VariableScope = 'private' | 'workgroup';
-interface TgpuVar<TScope extends VariableScope = VariableScope, TDataType extends BaseData = BaseData> extends TgpuNamable {
-  readonly resourceType: 'var';
-  readonly [$gpuValueOf]: InferGPU<TDataType>;
-  /**
-   * @deprecated Use `.$` instead, works the same way.
-   */
-  value: InferGPU<TDataType>;
-  $: InferGPU<TDataType>;
-  readonly [$internal]: {
-    /** Makes it differentiable on the type level. Does not exist at runtime. */
-    dataType?: TDataType;
-    /** Makes it differentiable on the type level. Does not exist at runtime. */
-    scope?: TScope;
-  };
+import type { AnyData } from '../../data/dataTypes.ts';
+import type { BaseData } from '../../data/wgslTypes.ts';
+import type { TgpuNamable } from '../../shared/meta.ts';
+import type { InferGPU } from '../../shared/repr.ts';
+import type { TgpuSoul } from '../../shared/soul.ts';
+import { $gpuValueOf, $internal, $soul } from '../../shared/symbols.ts';
+export type VariableScope = 'private' | 'workgroup';
+export interface TgpuVarSoul<TScope extends VariableScope = VariableScope, TDataType extends BaseData = BaseData> extends TgpuSoul<'var'> {
+    readonly scope: TScope;
+    readonly dataType: TDataType;
+    readonly initialValue: InferGPU<TDataType> | undefined;
+}
+export interface TgpuVar<TScope extends VariableScope = VariableScope, TDataType extends BaseData = BaseData> extends TgpuNamable {
+    readonly resourceType: 'var';
+    readonly [$gpuValueOf]: InferGPU<TDataType>;
+    $: InferGPU<TDataType>;
+    readonly [$soul]: TgpuVarSoul<TScope, TDataType>;
+    readonly [$internal]: {
+        /** Makes it differentiable on the type level. Does not exist at runtime. */
+        dataType?: TDataType;
+        /** Makes it differentiable on the type level. Does not exist at runtime. */
+        scope?: TScope;
+    };
 }
 /**
  * Defines a variable scoped to each entry function (private).
@@ -27,14 +28,12 @@ interface TgpuVar<TScope extends VariableScope = VariableScope, TDataType extend
  * @param dataType The schema of the held data's type
  * @param initialValue If not provided, the variable will be initialized to the dataType's "zero-value".
  */
-declare function privateVar<TDataType extends AnyData>(dataType: TDataType, initialValue?: InferGPU<TDataType>): TgpuVar<'private', TDataType>;
+export declare function privateVar<TDataType extends AnyData>(dataType: TDataType, initialValue?: InferGPU<TDataType>): TgpuVar<'private', TDataType>;
 /**
  * Defines a variable scoped to the whole workgroup, shared between entry functions
  * of the same invocation.
  *
  * @param dataType The schema of the held data's type
  */
-declare function workgroupVar<TDataType extends AnyData>(dataType: TDataType): TgpuVar<'workgroup', TDataType>;
-declare function isVariable(value: unknown): value is TgpuVar;
-//#endregion
-export { TgpuVar, VariableScope, isVariable, privateVar, workgroupVar };
+export declare function workgroupVar<TDataType extends AnyData>(dataType: TDataType): TgpuVar<'workgroup', TDataType>;
+export declare function isVariable(value: unknown): value is TgpuVar;

package/core/variable/tgpuVariable.js

@@ -1,103 +1,100 @@
-import { $gpuValueOf, $internal, $ownSnippet, $resolve } from "../../shared/symbols.js";
-import { getName, setName } from "../../shared/meta.js";
 import { snip } from "../../data/snippet.js";
 import { IllegalVarAccessError } from "../../errors.js";
-import { getExecMode, isInsideTgpuFn } from "../../execMode.js";
-import { assertExhaustive } from "../../shared/utilityTypes.js";
-import { valueProxyHandler } from "../valueProxyUtils.js";
-
-//#region src/core/variable/tgpuVariable.ts
+import { isInsideTgpuFn } from "../../execMode.js";
+import { makeDereferenceable } from "../../tgsl/makeDereferenceable.js";
+import { makeResolvable } from "../../tgsl/makeResolvable.js";
+import { getName, setName } from "../../shared/meta.js";
+import { $gpuValueOf, $internal, $soul } from "../../shared/symbols.js";
 /**
-* Defines a variable scoped to each entry function (private).
-*
-* @param dataType The schema of the held data's type
-* @param initialValue If not provided, the variable will be initialized to the dataType's "zero-value".
-*/
-function privateVar(dataType, initialValue) {
-	return new TgpuVarImpl("private", dataType, initialValue);
+ * Defines a variable scoped to each entry function (private).
+ *
+ * @param dataType The schema of the held data's type
+ * @param initialValue If not provided, the variable will be initialized to the dataType's "zero-value".
+ */
+export function privateVar(dataType, initialValue) {
+    return new TgpuVarImpl('private', dataType, initialValue);
 }
 /**
-* Defines a variable scoped to the whole workgroup, shared between entry functions
-* of the same invocation.
-*
-* @param dataType The schema of the held data's type
-*/
-function workgroupVar(dataType) {
-	return new TgpuVarImpl("workgroup", dataType);
+ * Defines a variable scoped to the whole workgroup, shared between entry functions
+ * of the same invocation.
+ *
+ * @param dataType The schema of the held data's type
+ */
+export function workgroupVar(dataType) {
+    return new TgpuVarImpl('workgroup', dataType);
+}
+export function isVariable(value) {
+    return value instanceof TgpuVarImpl;
 }
-function isVariable(value) {
-	return value instanceof TgpuVarImpl;
+// --------------
+// Implementation
+// --------------
+class TgpuVarImpl {
+    [$soul];
+    static {
+        const prototype = TgpuVarImpl.prototype;
+        prototype.resourceType = 'var';
+        prototype[$internal] = {};
+        makeDereferenceable(makeResolvable(prototype, {
+            asString() {
+                return `var:${getName(this) ?? '<unnamed>'}`;
+            },
+            resolve(ctx) {
+                const id = ctx.makeUniqueIdentifier(getName(this), 'global');
+                const init = this[$soul].initialValue
+                    ? snip(this[$soul].initialValue, this[$soul].dataType, 'constant')
+                    : undefined;
+                return ctx.gen.declareGlobalVar({
+                    scope: this[$soul].scope,
+                    id,
+                    dataType: this[$soul].dataType,
+                    init,
+                });
+            },
+        }), {
+            codegenMode: {
+                getBaseSnippet(trackingProxy) {
+                    return snip(trackingProxy, this[$soul].dataType, this[$soul].scope, 
+                    /* possibleSideEffects */ false);
+                },
+            },
+            simulateMode: {
+                get(state) {
+                    if (!state.vars[this[$soul].scope].has(this)) {
+                        // Not initialized yet
+                        state.vars[this[$soul].scope].set(this, this[$soul].initialValue);
+                    }
+                    return state.vars[this[$soul].scope].get(this);
+                },
+                set(state, value) {
+                    state.vars[this[$soul].scope].set(this, value);
+                },
+            },
+            normalMode: {
+                get() {
+                    throw new IllegalVarAccessError(isInsideTgpuFn()
+                        ? `Cannot access variable '${getName(this) ?? '<unnamed>'}'. TypeGPU functions that depends on GPU resources need to be part of a compute dispatch, draw call or simulation`
+                        : 'TypeGPU variables are inaccessible during normal JS execution. If you wanted to simulate GPU behavior, try `tgpu.simulate()`');
+                },
+                set(_value) {
+                    throw new IllegalVarAccessError(isInsideTgpuFn()
+                        ? `Cannot access variable ${getName(this) ?? '<unnamed>'}. TypeGPU functions that depends on GPU resources need to be part of a compute dispatch, draw call or simulation`
+                        : 'TypeGPU variables are inaccessible during normal JS execution. If you wanted to simulate GPU behavior, try `tgpu.simulate()`');
+                },
+            },
+        });
+    }
+    constructor(scope, dataType, initialValue) {
+        this[$soul] = {
+            type: 'var',
+            scope,
+            dataType,
+            initialValue,
+            label: undefined,
+        };
+    }
+    $name(label) {
+        setName(this, label);
+        return this;
+    }
 }
-var TgpuVarImpl = class {
-	[$internal] = {};
-	resourceType;
-	#scope;
-	#dataType;
-	#initialValue;
-	constructor(scope, dataType, initialValue) {
-		this.resourceType = "var";
-		this.#scope = scope;
-		this.#dataType = dataType;
-		this.#initialValue = initialValue;
-	}
-	[$resolve](ctx) {
-		const id = ctx.makeUniqueIdentifier(getName(this), "global");
-		const init = this.#initialValue ? snip(this.#initialValue, this.#dataType, "constant") : void 0;
-		return ctx.gen.declareGlobalVar({
-			scope: this.#scope,
-			id,
-			dataType: this.#dataType,
-			init
-		});
-	}
-	$name(label) {
-		setName(this, label);
-		return this;
-	}
-	toString() {
-		return `var:${getName(this) ?? "<unnamed>"}`;
-	}
-	get [$gpuValueOf]() {
-		const dataType = this.#dataType;
-		const origin = this.#scope;
-		return new Proxy({
-			[$internal]: true,
-			get [$ownSnippet]() {
-				return snip(this, dataType, origin);
-			},
-			[$resolve]: (ctx) => ctx.resolve(this),
-			toString: () => `var:${getName(this) ?? "<unnamed>"}.$`
-		}, valueProxyHandler);
-	}
-	get $() {
-		const mode = getExecMode();
-		const insideTgpuFn = isInsideTgpuFn();
-		if (mode.type === "normal") throw new IllegalVarAccessError(insideTgpuFn ? `Cannot access variable '${getName(this) ?? "<unnamed>"}'. TypeGPU functions that depends on GPU resources need to be part of a compute dispatch, draw call or simulation` : "TypeGPU variables are inaccessible during normal JS execution. If you wanted to simulate GPU behavior, try `tgpu.simulate()`");
-		if (mode.type === "codegen") return this[$gpuValueOf];
-		if (mode.type === "simulate") {
-			if (!mode.vars[this.#scope].has(this)) mode.vars[this.#scope].set(this, this.#initialValue);
-			return mode.vars[this.#scope].get(this);
-		}
-		return assertExhaustive(mode, "tgpuVariable.ts#TgpuVarImpl/$");
-	}
-	set $(value) {
-		const mode = getExecMode();
-		const insideTgpuFn = isInsideTgpuFn();
-		if (mode.type === "normal") throw new IllegalVarAccessError(insideTgpuFn ? `Cannot access ${String(this)}. TypeGPU functions that depends on GPU resources need to be part of a compute dispatch, draw call or simulation` : "TypeGPU variables are inaccessible during normal JS execution. If you wanted to simulate GPU behavior, try `tgpu.simulate()`");
-		if (mode.type === "codegen") throw new Error("Unreachable tgpuVariable.ts#TgpuVarImpl/$");
-		if (mode.type === "simulate") {
-			mode.vars[this.#scope].set(this, value);
-			return;
-		}
-		assertExhaustive(mode, "tgpuVariable.ts#TgpuVarImpl/$");
-	}
-	get value() {
-		return this.$;
-	}
-	set value(v) {
-		this.$ = v;
-	}
-};
-
-//#endregion
-export { isVariable, privateVar, workgroupVar };

package/core/vertexLayout/connectAttributesToShader.d.ts

@@ -0,0 +1,9 @@
+import type { AnyVertexAttribs, TgpuVertexAttrib } from '../../shared/vertexFormat.ts';
+import type { TgpuVertexFn } from '../function/tgpuVertexFn.ts';
+import type { INTERNAL_TgpuVertexAttrib, TgpuVertexLayout } from './vertexLayout.ts';
+export interface ConnectAttributesToShaderResult {
+    usedVertexLayouts: TgpuVertexLayout[];
+    bufferDefinitions: GPUVertexBufferLayout[];
+}
+export declare function isAttribute(value: unknown): value is TgpuVertexAttrib & INTERNAL_TgpuVertexAttrib;
+export declare function connectAttributesToShader(shaderInputLayout: TgpuVertexFn.In, attributes: AnyVertexAttribs): ConnectAttributesToShaderResult;