typegpu 0.11.8 → 0.12.0

package/data/schemaMemoryLayout.js

@@ -1,200 +1,228 @@
-import { isDecorated, isWgslArray, isWgslStruct } from "./wgslTypes.js";
-import { getCustomSize, isDisarray, isLooseDecorated, isUnstruct, undecorate } from "./dataTypes.js";
-import { alignmentOf, customAlignmentOf } from "./alignmentOf.js";
 import { roundUp } from "../mathUtils.js";
-
-//#region src/data/schemaMemoryLayout.ts
+import { alignmentOf, customAlignmentOf } from "./alignmentOf.js";
+import { getCustomSize, isDisarray, isLooseDecorated, isUnstruct, undecorate, } from "./dataTypes.js";
+import { isDecorated, isWgslArray, isWgslStruct } from "./wgslTypes.js";
 const knownSizesMap = {
-	bool: 4,
-	f32: 4,
-	f16: 2,
-	i32: 4,
-	u32: 4,
-	u16: 2,
-	vec2f: 8,
-	vec2h: 4,
-	vec2i: 8,
-	vec2u: 8,
-	"vec2<bool>": 8,
-	vec3f: 12,
-	vec3h: 6,
-	vec3i: 12,
-	vec3u: 12,
-	"vec3<bool>": 12,
-	vec4f: 16,
-	vec4h: 8,
-	vec4i: 16,
-	vec4u: 16,
-	"vec4<bool>": 16,
-	mat2x2f: 16,
-	mat3x3f: 48,
-	mat4x4f: 64,
-	uint8: 1,
-	uint8x2: 2,
-	uint8x4: 4,
-	sint8: 1,
-	sint8x2: 2,
-	sint8x4: 4,
-	unorm8: 1,
-	unorm8x2: 2,
-	unorm8x4: 4,
-	snorm8: 1,
-	snorm8x2: 2,
-	snorm8x4: 4,
-	uint16: 2,
-	uint16x2: 4,
-	uint16x4: 8,
-	sint16: 2,
-	sint16x2: 4,
-	sint16x4: 8,
-	unorm16: 2,
-	unorm16x2: 4,
-	unorm16x4: 8,
-	snorm16: 2,
-	snorm16x2: 4,
-	snorm16x4: 8,
-	float16: 2,
-	float16x2: 4,
-	float16x4: 8,
-	float32: 4,
-	float32x2: 8,
-	float32x3: 12,
-	float32x4: 16,
-	uint32: 4,
-	uint32x2: 8,
-	uint32x3: 12,
-	uint32x4: 16,
-	sint32: 4,
-	sint32x2: 8,
-	sint32x3: 12,
-	sint32x4: 16,
-	"unorm10-10-10-2": 4,
-	"unorm8x4-bgra": 4,
-	atomic: 4
+    bool: 4,
+    f32: 4,
+    f16: 2,
+    i32: 4,
+    u32: 4,
+    u16: 2,
+    vec2f: 8,
+    vec2h: 4,
+    vec2i: 8,
+    vec2u: 8,
+    'vec2<bool>': 8,
+    vec3f: 12,
+    vec3h: 6,
+    vec3i: 12,
+    vec3u: 12,
+    'vec3<bool>': 12,
+    vec4f: 16,
+    vec4h: 8,
+    vec4i: 16,
+    vec4u: 16,
+    'vec4<bool>': 16,
+    mat2x2f: 16,
+    mat3x3f: 48,
+    mat4x4f: 64,
+    uint8: 1,
+    uint8x2: 2,
+    uint8x4: 4,
+    sint8: 1,
+    sint8x2: 2,
+    sint8x4: 4,
+    unorm8: 1,
+    unorm8x2: 2,
+    unorm8x4: 4,
+    snorm8: 1,
+    snorm8x2: 2,
+    snorm8x4: 4,
+    uint16: 2,
+    uint16x2: 4,
+    uint16x4: 8,
+    sint16: 2,
+    sint16x2: 4,
+    sint16x4: 8,
+    unorm16: 2,
+    unorm16x2: 4,
+    unorm16x4: 8,
+    snorm16: 2,
+    snorm16x2: 4,
+    snorm16x4: 8,
+    float16: 2,
+    float16x2: 4,
+    float16x4: 8,
+    float32: 4,
+    float32x2: 8,
+    float32x3: 12,
+    float32x4: 16,
+    uint32: 4,
+    uint32x2: 8,
+    uint32x3: 12,
+    uint32x4: 16,
+    sint32: 4,
+    sint32x2: 8,
+    sint32x3: 12,
+    sint32x4: 16,
+    'unorm10-10-10-2': 4,
+    'unorm8x4-bgra': 4,
+    atomic: 4,
 };
 function computeMLOfStruct(struct) {
-	let size = 0;
-	let longestContiguousPrefix = 0;
-	let isContiguous = true;
-	let prefixEnd = false;
-	for (const property of Object.values(struct.propTypes)) {
-		if (Number.isNaN(size)) throw new Error("Only the last property of a struct can be unbounded");
-		const prevSize = size;
-		size = roundUp(size, alignmentOf(property));
-		const hasPadding = prevSize !== size;
-		const propLayout = computeMemoryLayout(property);
-		size += propLayout.size;
-		if (Number.isNaN(size) && property.type !== "array") throw new Error("Cannot nest unbounded struct within another struct");
-		if (prefixEnd) continue;
-		if (!hasPadding && propLayout.isContiguous) longestContiguousPrefix += propLayout.size;
-		else {
-			prefixEnd = true;
-			isContiguous = false;
-			if (!hasPadding) longestContiguousPrefix += propLayout.longestContiguousPrefix;
-		}
-	}
-	const trueSize = roundUp(size, alignmentOf(struct));
-	return {
-		isContiguous: size === trueSize && isContiguous,
-		size: trueSize,
-		longestContiguousPrefix
-	};
+    let size = 0;
+    let longestContiguousPrefix = 0;
+    let isContiguous = true;
+    let prefixEnd = false;
+    for (const property of Object.values(struct.propTypes)) {
+        if (Number.isNaN(size)) {
+            throw new Error('Only the last property of a struct can be unbounded');
+        }
+        const prevSize = size;
+        size = roundUp(size, alignmentOf(property));
+        const hasPadding = prevSize !== size;
+        const propLayout = computeMemoryLayout(property);
+        size += propLayout.size;
+        if (Number.isNaN(size) && property.type !== 'array') {
+            throw new Error('Cannot nest unbounded struct within another struct');
+        }
+        if (prefixEnd) {
+            continue;
+        }
+        if (!hasPadding && propLayout.isContiguous) {
+            longestContiguousPrefix += propLayout.size;
+        }
+        else {
+            prefixEnd = true;
+            isContiguous = false;
+            if (!hasPadding) {
+                longestContiguousPrefix += propLayout.longestContiguousPrefix;
+            }
+        }
+    }
+    const trueSize = roundUp(size, alignmentOf(struct));
+    return {
+        isContiguous: size === trueSize && isContiguous,
+        size: trueSize,
+        longestContiguousPrefix,
+    };
 }
 function computeMLOfUnstruct(data) {
-	let size = 0;
-	let longestContiguousPrefix = 0;
-	let isContiguous = true;
-	let prefixEnd = false;
-	for (const property of Object.values(data.propTypes)) {
-		const alignment = customAlignmentOf(property);
-		const prevSize = size;
-		size = roundUp(size, alignment);
-		const hasPadding = prevSize !== size;
-		if (hasPadding) isContiguous = false;
-		const propLayout = computeMemoryLayout(property);
-		size += propLayout.size;
-		if (prefixEnd) continue;
-		if (!hasPadding && propLayout.isContiguous) longestContiguousPrefix += propLayout.size;
-		else {
-			prefixEnd = true;
-			isContiguous = false;
-			if (!hasPadding) longestContiguousPrefix += propLayout.longestContiguousPrefix;
-		}
-	}
-	return {
-		isContiguous,
-		size,
-		longestContiguousPrefix
-	};
+    let size = 0;
+    let longestContiguousPrefix = 0;
+    let isContiguous = true;
+    let prefixEnd = false;
+    for (const property of Object.values(data.propTypes)) {
+        const alignment = customAlignmentOf(property);
+        const prevSize = size;
+        size = roundUp(size, alignment);
+        const hasPadding = prevSize !== size;
+        if (hasPadding) {
+            isContiguous = false;
+        }
+        const propLayout = computeMemoryLayout(property);
+        size += propLayout.size;
+        if (prefixEnd) {
+            continue;
+        }
+        if (!hasPadding && propLayout.isContiguous) {
+            longestContiguousPrefix += propLayout.size;
+        }
+        else {
+            prefixEnd = true;
+            isContiguous = false;
+            if (!hasPadding) {
+                longestContiguousPrefix += propLayout.longestContiguousPrefix;
+            }
+        }
+    }
+    return {
+        isContiguous: isContiguous,
+        size,
+        longestContiguousPrefix,
+    };
 }
 function computeMLOfWgslArray(data) {
-	const elementType = data.elementType;
-	const elementMemoryLayout = computeMemoryLayout(elementType);
-	const elementSize = elementMemoryLayout.size;
-	const stride = roundUp(elementSize, alignmentOf(elementType));
-	const isContiguous = !(stride > elementSize) && elementMemoryLayout.isContiguous;
-	const size = data.elementCount === 0 ? NaN : data.elementCount * stride;
-	let longestContiguousPrefix;
-	if (isContiguous) longestContiguousPrefix = size;
-	else longestContiguousPrefix = elementMemoryLayout.longestContiguousPrefix;
-	return {
-		size,
-		isContiguous,
-		longestContiguousPrefix
-	};
+    const elementType = data.elementType;
+    const elementMemoryLayout = computeMemoryLayout(elementType);
+    const elementSize = elementMemoryLayout.size;
+    const stride = roundUp(elementSize, alignmentOf(elementType));
+    const hasPadding = stride > elementSize;
+    const isContiguous = !hasPadding && elementMemoryLayout.isContiguous;
+    const size = data.elementCount === 0 ? Number.NaN : data.elementCount * stride;
+    let longestContiguousPrefix;
+    if (isContiguous) {
+        longestContiguousPrefix = size;
+    }
+    else {
+        longestContiguousPrefix = elementMemoryLayout.longestContiguousPrefix;
+    }
+    return { size, isContiguous, longestContiguousPrefix };
 }
 function computeMLOfDisarray(data) {
-	const elementType = data.elementType;
-	const elementMemoryLayout = computeMemoryLayout(elementType);
-	const elementSize = elementMemoryLayout.size;
-	const stride = roundUp(elementSize, customAlignmentOf(elementType));
-	const isContiguous = !(stride > elementSize) && elementMemoryLayout.isContiguous;
-	const size = data.elementCount * stride;
-	let longestContiguousPrefix;
-	if (isContiguous) longestContiguousPrefix = size;
-	else longestContiguousPrefix = elementMemoryLayout.longestContiguousPrefix;
-	return {
-		size,
-		isContiguous,
-		longestContiguousPrefix
-	};
+    const elementType = data.elementType;
+    const elementMemoryLayout = computeMemoryLayout(elementType);
+    const elementSize = elementMemoryLayout.size;
+    const stride = roundUp(elementSize, customAlignmentOf(elementType));
+    const hasPadding = stride > elementSize;
+    const isContiguous = !hasPadding && elementMemoryLayout.isContiguous;
+    const size = data.elementCount * stride;
+    let longestContiguousPrefix;
+    if (isContiguous) {
+        longestContiguousPrefix = size;
+    }
+    else {
+        longestContiguousPrefix = elementMemoryLayout.longestContiguousPrefix;
+    }
+    return { size, isContiguous, longestContiguousPrefix };
 }
 function computeMemoryLayout(data) {
-	const knownSize = knownSizesMap[data.type];
-	if (knownSize !== void 0) return {
-		isContiguous: data.type !== "mat3x3f",
-		size: knownSize,
-		longestContiguousPrefix: data.type === "mat3x3f" ? 12 : knownSize
-	};
-	if (isWgslStruct(data)) return computeMLOfStruct(data);
-	if (isUnstruct(data)) return computeMLOfUnstruct(data);
-	if (isWgslArray(data)) return computeMLOfWgslArray(data);
-	if (isDisarray(data)) return computeMLOfDisarray(data);
-	if (isDecorated(data) || isLooseDecorated(data)) {
-		const size = getCustomSize(data);
-		const undecoratedLayout = computeMemoryLayout(undecorate(data));
-		if (size) return {
-			isContiguous: size === undecoratedLayout.size && undecoratedLayout.isContiguous,
-			size,
-			longestContiguousPrefix: undecoratedLayout.longestContiguousPrefix
-		};
-		return computeMemoryLayout(data.inner);
-	}
-	throw new Error(`Cannot determine memory layout of data: ${data}`);
+    const knownSize = knownSizesMap[data.type];
+    if (knownSize !== undefined) {
+        return {
+            isContiguous: data.type !== 'mat3x3f',
+            size: knownSize,
+            longestContiguousPrefix: data.type === 'mat3x3f' ? 12 : knownSize,
+        };
+    }
+    if (isWgslStruct(data)) {
+        return computeMLOfStruct(data);
+    }
+    if (isUnstruct(data)) {
+        return computeMLOfUnstruct(data);
+    }
+    if (isWgslArray(data)) {
+        return computeMLOfWgslArray(data);
+    }
+    if (isDisarray(data)) {
+        return computeMLOfDisarray(data);
+    }
+    if (isDecorated(data) || isLooseDecorated(data)) {
+        const size = getCustomSize(data);
+        const undecoratedLayout = computeMemoryLayout(undecorate(data));
+        if (size) {
+            const isContiguous = size === undecoratedLayout.size && undecoratedLayout.isContiguous;
+            return {
+                isContiguous,
+                size,
+                longestContiguousPrefix: undecoratedLayout.longestContiguousPrefix,
+            };
+        }
+        return computeMemoryLayout(data.inner);
+    }
+    throw new Error(`Cannot determine memory layout of data: ${data}`);
 }
 /**
-* Since memory layout can be inferred from data types, they are not stored on them.
-* Instead, this weak map acts as an extended property of those data types.
-*/
-const cachedLayouts = /* @__PURE__ */ new WeakMap();
-function getLayoutInfo(schema, key) {
-	let layout = cachedLayouts.get(schema);
-	if (layout === void 0) {
-		layout = computeMemoryLayout(schema);
-		cachedLayouts.set(schema, layout);
-	}
-	return layout[key];
+ * Since memory layout can be inferred from data types, they are not stored on them.
+ * Instead, this weak map acts as an extended property of those data types.
+ */
+const cachedLayouts = new WeakMap();
+export function getLayoutInfo(schema, key) {
+    let layout = cachedLayouts.get(schema);
+    if (layout === undefined) {
+        layout = computeMemoryLayout(schema);
+        cachedLayouts.set(schema, layout);
+    }
+    return layout[key];
 }
-
-//#endregion
-export { getLayoutInfo };

package/data/sizeOf.d.ts

@@ -1,11 +1,7 @@
-import "./wgslTypes.js";
-import { AnyData } from "./dataTypes.js";
-
-//#region src/data/sizeOf.d.ts
-
+import type { AnyData } from './dataTypes.ts';
+import type { BaseData } from './wgslTypes.ts';
+export declare function sizeOf(schema: BaseData): number;
 /**
  * Returns the size (in bytes) of data represented by the `schema`.
  */
-declare function PUBLIC_sizeOf(schema: AnyData): number;
-//#endregion
-export { PUBLIC_sizeOf };
+export declare function PUBLIC_sizeOf(schema: AnyData): number;

package/data/sizeOf.js

@@ -1,15 +1,10 @@
 import { getLayoutInfo } from "./schemaMemoryLayout.js";
-
-//#region src/data/sizeOf.ts
-function sizeOf(schema) {
-	return getLayoutInfo(schema, "size");
+export function sizeOf(schema) {
+    return getLayoutInfo(schema, 'size');
 }
 /**
-* Returns the size (in bytes) of data represented by the `schema`.
-*/
-function PUBLIC_sizeOf(schema) {
-	return sizeOf(schema);
+ * Returns the size (in bytes) of data represented by the `schema`.
+ */
+export function PUBLIC_sizeOf(schema) {
+    return sizeOf(schema);
 }
-
-//#endregion
-export { PUBLIC_sizeOf, sizeOf };

package/data/snippet.d.ts

@@ -1,22 +1,98 @@
-import { BaseData } from "./wgslTypes.js";
-import { UnknownData } from "./dataTypes.js";
-
-//#region src/data/snippet.d.ts
-type Origin = 'uniform' | 'readonly' | 'mutable' | 'workgroup' | 'private' | 'handle' | 'function' | 'local-def' | 'constant-immutable-def' | 'runtime-immutable-def' | 'argument' | 'runtime' | 'constant';
-interface Snippet {
-  readonly value: unknown;
-  /**
-   * The type that `value` is assignable to (not necessary exactly inferred as).
-   * E.g. `1.1` is assignable to `f32`, but `1.1` itself is an abstract float
-   */
-  readonly dataType: BaseData | UnknownData;
-  readonly origin: Origin;
-  readonly possibleSideEffects: boolean;
+import type { UnknownData } from './dataTypes.ts';
+import { type BaseData } from './wgslTypes.ts';
+export type Origin = 'uniform' | 'readonly' | 'mutable' | 'workgroup' | 'private' | 'handle' | 'function' | 'local-def' | 'constant-immutable-def' | 'runtime-immutable-def' | 'argument' | 'runtime' | 'constant';
+/**
+ * What happens to a snippet's origin when it's deep copied in JS, and left as is in WGSL?
+ * e.g. `vec3f(vec3f(0, 1, 2))`
+ */
+export declare function fallthroughCopyOrigin(origin: Origin): Origin;
+/**
+ * Whether a snippet aliases a value that lives outside the current expression.
+ *
+ * @example
+ * ```ts
+ * function foo(a: number) {
+ *   const color = d.vec3f(1, 2, 3);
+ *   return color * a;
+ * }
+ *
+ * // References:
+ * // -  color
+ * // -  a
+ * //
+ * // Not references:
+ * // - d.vec3f(1, 2, 3)
+ * // - color * a
+ * ```
+ */
+export declare function isAlias(snippet: Snippet): boolean;
+export declare const originToPtrParams: {
+    readonly uniform: {
+        readonly space: "uniform";
+        readonly access: "read";
+    };
+    readonly readonly: {
+        readonly space: "storage";
+        readonly access: "read";
+    };
+    readonly mutable: {
+        readonly space: "storage";
+        readonly access: "read-write";
+    };
+    readonly workgroup: {
+        readonly space: "workgroup";
+        readonly access: "read-write";
+    };
+    readonly private: {
+        readonly space: "private";
+        readonly access: "read-write";
+    };
+    readonly function: {
+        readonly space: "function";
+        readonly access: "read-write";
+    };
+    readonly 'local-def': {
+        readonly space: "function";
+        readonly access: "read-write";
+    };
+};
+export type OriginToPtrParams = typeof originToPtrParams;
+export interface Snippet {
+    readonly value: unknown;
+    /**
+     * The type that `value` is assignable to (not necessary exactly inferred as).
+     * E.g. `1.1` is assignable to `f32`, but `1.1` itself is an abstract float
+     */
+    readonly dataType: BaseData | UnknownData;
+    readonly origin: Origin;
+    /**
+     * A snippet has possible side effects either if we're sure that it has side
+     * effects, or if our systems are unable to reliably determine that it
+     * doesn't have side effects.
+     *
+     * A snippet has side-effects if executing the WGSL code within and not using
+     * the return value is not equivalent to just not executing the WGSL code at
+     * all, with a margin of executing a few more instructions. For example, code
+     * that mutates memory, or synchronizes threads, has side effects.
+     */
+    readonly possibleSideEffects: boolean;
 }
-interface ResolvedSnippet extends Snippet {
-  readonly value: string;
-  readonly dataType: BaseData;
+export interface ResolvedSnippet extends Snippet {
+    readonly value: string;
+    readonly dataType: BaseData;
 }
-type MapValueToSnippet<T> = { [K in keyof T]: Snippet };
-//#endregion
-export { MapValueToSnippet, Origin, ResolvedSnippet, Snippet };
+export type MapValueToSnippet<T> = {
+    [K in keyof T]: Snippet;
+};
+export declare function isSnippet(value: unknown): value is Snippet;
+export declare function isSnippetNumeric(snippet: Snippet): boolean;
+export declare function snip(value: string, dataType: BaseData, origin: Origin, possibleSideEffects?: boolean): ResolvedSnippet;
+export declare function snip(value: unknown, dataType: BaseData | UnknownData, origin: Origin, possibleSideEffects?: boolean): Snippet;
+export declare function withDataType(dataType: BaseData | UnknownData, snippet: ResolvedSnippet): ResolvedSnippet;
+export declare function withDataType(dataType: BaseData | UnknownData, snippet: Snippet): Snippet;
+export declare function withValue(value: string, snippet: Snippet): ResolvedSnippet;
+export declare function withValue(value: unknown, snippet: Snippet): Snippet;
+export declare function withSideEffects(possibleSideEffects: boolean, snippet: ResolvedSnippet): ResolvedSnippet;
+export declare function withSideEffects(possibleSideEffects: boolean, snippet: Snippet): Snippet;
+export declare function noSideEffects(snippet: ResolvedSnippet): ResolvedSnippet;
+export declare function noSideEffects(snippet: Snippet): Snippet;