typegpu 0.10.0 → 0.10.2

package/data/ref.js

@@ -0,0 +1,96 @@
+import { $gpuCallable, $internal, $ownSnippet, $resolve } from "../shared/symbols.js";
+import { setName } from "../shared/meta.js";
+import { isNaturallyEphemeral, isPtr } from "./wgslTypes.js";
+import { UnknownData } from "./dataTypes.js";
+import { snip } from "./snippet.js";
+import { WgslTypeError } from "../errors.js";
+import { stitch } from "../core/resolve/stitch.js";
+import { createPtrFromOrigin, explicitFrom } from "./ptr.js";
+
+//#region src/data/ref.ts
+const _ref = (() => {
+	const impl = ((value) => INTERNAL_createRef(value));
+	setName(impl, "ref");
+	impl.toString = () => "ref";
+	impl[$internal] = true;
+	impl[$gpuCallable] = { call(_ctx, [value]) {
+		if (value.origin === "argument") throw new WgslTypeError(stitch`d.ref(${value}) is illegal, cannot take a reference of an argument. Copy the value locally first, and take a reference of the copy.`);
+		if (isPtr(value.dataType)) return snip(value.value, explicitFrom(value.dataType), value.origin);
+		/**
+		* Pointer type only exists if the ref was created from a reference (buttery-butter).
+		*
+		* @example
+		* ```ts
+		* const life = ref(42); // created from a value
+		* const boid = ref(layout.$.boids[0]); // created from a reference
+		* ```
+		*/
+		const ptrType = createPtrFromOrigin(value.origin, value.dataType);
+		return snip(new RefOperator(value, ptrType), ptrType ?? UnknownData, "runtime");
+	} };
+	return impl;
+})();
+function isRef(value) {
+	return value?.[$internal]?.type === "ref";
+}
+function INTERNAL_createRef(value) {
+	const target = {
+		[$internal]: { type: "ref" },
+		get $() {
+			return value;
+		},
+		set $(newValue) {
+			if (newValue && typeof newValue === "object") for (const key of Object.keys(newValue)) value[key] = newValue[key];
+			else value = newValue;
+		}
+	};
+	if (value === void 0 || value === null) throw new Error("Cannot create a ref from undefined or null");
+	if (typeof value === "object") return new Proxy(target, {
+		get(target, prop) {
+			if (prop in target) return target[prop];
+			return value[prop];
+		},
+		set(_target, prop, propValue) {
+			if (prop === $internal) return false;
+			if (prop === "$") {
+				console.log("Setting ref value:", propValue);
+				return Reflect.set(target, prop, propValue);
+			}
+			return Reflect.set(value, prop, propValue);
+		}
+	});
+	return target;
+}
+/**
+* The result of calling `d.ref(...)`. The code responsible for
+* generating shader code can check if the value of a snippet is
+* an instance of `RefOperator`, and act accordingly.
+*/
+var RefOperator = class {
+	[$internal];
+	snippet;
+	#ptrType;
+	constructor(snippet, ptrType) {
+		this[$internal] = true;
+		this.snippet = snippet;
+		this.#ptrType = ptrType;
+	}
+	get [$ownSnippet]() {
+		if (!this.#ptrType) throw new Error(stitch`Cannot take a reference of ${this.snippet}`);
+		return snip(this, this.#ptrType, this.snippet.origin);
+	}
+	[$resolve]() {
+		if (!this.#ptrType) throw new Error(stitch`Cannot take a reference of ${this.snippet}`);
+		return snip(stitch`(&${this.snippet})`, this.#ptrType, this.snippet.origin);
+	}
+};
+function derefSnippet(snippet) {
+	if (!isPtr(snippet.dataType)) return snippet;
+	const innerType = snippet.dataType.inner;
+	const origin = isNaturallyEphemeral(innerType) ? "runtime" : snippet.origin;
+	if (snippet.value instanceof RefOperator) return snip(stitch`${snippet.value.snippet}`, innerType, origin);
+	return snip(stitch`(*${snippet})`, innerType, origin);
+}
+
+//#endregion
+export { RefOperator, _ref, derefSnippet, isRef };

package/data/sampler.d.ts

@@ -0,0 +1,107 @@
+import { $internal, $repr } from "../shared/symbols.js";
+import { BaseData } from "./wgslTypes.js";
+
+//#region src/data/sampler.d.ts
+interface WgslSamplerProps {
+  addressModeU?: GPUAddressMode;
+  addressModeV?: GPUAddressMode;
+  /**
+   * Specifies the address modes for the texture width, height, and depth
+   * coordinates, respectively.
+   */
+  addressModeW?: GPUAddressMode;
+  /**
+   * Specifies the sampling behavior when the sample footprint is smaller than or equal to one
+   * texel.
+   */
+  magFilter?: GPUFilterMode;
+  /**
+   * Specifies the sampling behavior when the sample footprint is larger than one texel.
+   */
+  minFilter?: GPUFilterMode;
+  /**
+   * Specifies behavior for sampling between mipmap levels.
+   */
+  mipmapFilter?: GPUMipmapFilterMode;
+  lodMinClamp?: number;
+  /**
+   * Specifies the minimum and maximum levels of detail, respectively, used internally when
+   * sampling a texture.
+   */
+  lodMaxClamp?: number;
+  /**
+   * Specifies the maximum anisotropy value clamp used by the sampler. Anisotropic filtering is
+   * enabled when {@link GPUSamplerDescriptor.maxAnisotropy} is > 1 and the implementation supports it.
+   * Anisotropic filtering improves the image quality of textures sampled at oblique viewing
+   * angles. Higher {@link GPUSamplerDescriptor.maxAnisotropy} values indicate the maximum ratio of
+   * anisotropy supported when filtering.
+   *
+   * Most implementations support {@link GPUSamplerDescriptor.maxAnisotropy} values in range
+   * between 1 and 16, inclusive. The used value of {@link GPUSamplerDescriptor.maxAnisotropy}
+   * will be clamped to the maximum value that the platform supports.
+   * The precise filtering behavior is implementation-dependent.
+   */
+  maxAnisotropy?: number;
+}
+interface WgslComparisonSamplerProps {
+  compare: GPUCompareFunction;
+  addressModeU?: GPUAddressMode;
+  addressModeV?: GPUAddressMode;
+  /**
+   * Specifies the address modes for the texture width, height, and depth
+   * coordinates, respectively.
+   */
+  addressModeW?: GPUAddressMode;
+  /**
+   * Specifies the sampling behavior when the sample footprint is smaller than or equal to one
+   * texel.
+   */
+  magFilter?: GPUFilterMode;
+  /**
+   * Specifies the sampling behavior when the sample footprint is larger than one texel.
+   */
+  minFilter?: GPUFilterMode;
+  /**
+   * Specifies behavior for sampling between mipmap levels.
+   */
+  mipmapFilter?: GPUMipmapFilterMode;
+  lodMinClamp?: number;
+  /**
+   * Specifies the minimum and maximum levels of detail, respectively, used internally when
+   * sampling a texture.
+   */
+  lodMaxClamp?: number;
+  /**
+   * Specifies the maximum anisotropy value clamp used by the sampler. Anisotropic filtering is
+   * enabled when {@link GPUSamplerDescriptor.maxAnisotropy} is > 1 and the implementation supports it.
+   * Anisotropic filtering improves the image quality of textures sampled at oblique viewing
+   * angles. Higher {@link GPUSamplerDescriptor.maxAnisotropy} values indicate the maximum ratio of
+   * anisotropy supported when filtering.
+   *
+   * Most implementations support {@link GPUSamplerDescriptor.maxAnisotropy} values in range
+   * between 1 and 16, inclusive. The used value of {@link GPUSamplerDescriptor.maxAnisotropy}
+   * will be clamped to the maximum value that the platform supports.
+   * The precise filtering behavior is implementation-dependent.
+   */
+  maxAnisotropy?: number;
+}
+interface sampler {
+  [$internal]: true;
+  type: 'sampler';
+}
+declare function sampler(): WgslSampler;
+interface comparisonSampler {
+  [$internal]: Record<string, never>;
+  type: 'sampler_comparison';
+}
+declare function comparisonSampler(): WgslComparisonSampler;
+interface WgslSampler extends BaseData {
+  readonly [$repr]: sampler;
+  readonly type: 'sampler';
+}
+interface WgslComparisonSampler extends BaseData {
+  readonly [$repr]: comparisonSampler;
+  readonly type: 'sampler_comparison';
+}
+//#endregion
+export { WgslComparisonSampler, WgslComparisonSamplerProps, WgslSampler, WgslSamplerProps, comparisonSampler, sampler };

package/data/sampler.js

@@ -0,0 +1,26 @@
+import { $internal, $repr } from "../shared/symbols.js";
+
+//#region src/data/sampler.ts
+function sampler() {
+	return {
+		[$internal]: {},
+		type: "sampler",
+		[$repr]: void 0
+	};
+}
+function comparisonSampler() {
+	return {
+		[$internal]: {},
+		type: "sampler_comparison",
+		[$repr]: void 0
+	};
+}
+function isWgslSampler(value) {
+	return !!value[$internal] && value.type === "sampler";
+}
+function isWgslComparisonSampler(value) {
+	return !!value[$internal] && value.type === "sampler_comparison";
+}
+
+//#endregion
+export { comparisonSampler, isWgslComparisonSampler, isWgslSampler, sampler };

package/data/schemaCallWrapper.js

@@ -0,0 +1,32 @@
+import { $cast, $gpuCallable } from "../shared/symbols.js";
+import { hasCast, isGPUCallable } from "../types.js";
+
+//#region src/data/schemaCallWrapper.ts
+/**
+* A wrapper for `schema(item)` or `schema()` call on JS side.
+* If the schema is a pointer, returns the value pointed to without copying.
+* If the schema is a TgpuVertexFormatData, calls the corresponding constructible schema instead.
+* If the schema is not callable, throws an error.
+* Otherwise, returns `schema(item)` or `schema()`.
+*/
+function schemaCallWrapper(schema, item) {
+	const callSchema = schema;
+	if (hasCast(callSchema)) return callSchema[$cast](item);
+	if (typeof callSchema !== "function") return item;
+	return item === void 0 ? callSchema() : callSchema(item);
+}
+/**
+* A wrapper for `schema(item)` or `schema()` call on the GPU side.
+* If the schema is a pointer, returns the value pointed to without copying.
+* If the schema is a TgpuVertexFormatData, calls the corresponding constructible schema instead.
+* If the schema is not callable, throws an error.
+* Otherwise, returns `schema(item)` or `schema()`.
+*/
+function schemaCallWrapperGPU(ctx, schema, item) {
+	if (!isGPUCallable(schema)) return item;
+	const callSchema = schema;
+	return item === void 0 || item.value === void 0 ? callSchema[$gpuCallable].call(ctx, []) : callSchema[$gpuCallable].call(ctx, [item]);
+}
+
+//#endregion
+export { schemaCallWrapper, schemaCallWrapperGPU };

package/data/schemaMemoryLayout.js

@@ -0,0 +1,200 @@
+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
+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
+};
+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
+	};
+}
+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
+	};
+}
+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
+	};
+}
+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
+	};
+}
+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}`);
+}
+/**
+* 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];
+}
+
+//#endregion
+export { getLayoutInfo };

package/data/sizeOf.d.ts

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

package/data/sizeOf.js

@@ -0,0 +1,15 @@
+import { getLayoutInfo } from "./schemaMemoryLayout.js";
+
+//#region src/data/sizeOf.ts
+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);
+}
+
+//#endregion
+export { PUBLIC_sizeOf, sizeOf };

package/data/snippet.d.ts

@@ -0,0 +1,26 @@
+import { BaseData } from "./wgslTypes.js";
+import { UnknownData } from "./dataTypes.js";
+
+//#region src/data/snippet.d.ts
+type Origin = 'uniform' | 'readonly' | 'mutable' | 'workgroup' | 'private' | 'function' | 'this-function' | 'handle' | 'argument' | 'runtime' | 'constant' | 'constant-tgpu-const-ref' | 'runtime-tgpu-const-ref';
+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;
+}
+interface ResolvedSnippet {
+  readonly value: string;
+  /**
+   * 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;
+  readonly origin: Origin;
+}
+type MapValueToSnippet<T> = { [K in keyof T]: Snippet };
+//#endregion
+export { MapValueToSnippet, Origin, ResolvedSnippet, Snippet };

package/data/snippet.js

@@ -0,0 +1,61 @@
+import { DEV } from "../shared/env.js";
+import { isNumericSchema } from "./wgslTypes.js";
+import { undecorate } from "./dataTypes.js";
+
+//#region src/data/snippet.ts
+function isEphemeralOrigin(space) {
+	return space === "runtime" || space === "constant" || space === "argument";
+}
+function isEphemeralSnippet(snippet) {
+	return isEphemeralOrigin(snippet.origin);
+}
+const originToPtrParams = {
+	uniform: {
+		space: "uniform",
+		access: "read"
+	},
+	readonly: {
+		space: "storage",
+		access: "read"
+	},
+	mutable: {
+		space: "storage",
+		access: "read-write"
+	},
+	workgroup: {
+		space: "workgroup",
+		access: "read-write"
+	},
+	private: {
+		space: "private",
+		access: "read-write"
+	},
+	function: {
+		space: "function",
+		access: "read-write"
+	},
+	"this-function": {
+		space: "function",
+		access: "read-write"
+	}
+};
+var SnippetImpl = class {
+	constructor(value, dataType, origin) {
+		this.value = value;
+		this.dataType = dataType;
+		this.origin = origin;
+	}
+};
+function isSnippet(value) {
+	return value instanceof SnippetImpl;
+}
+function isSnippetNumeric(snippet) {
+	return isNumericSchema(snippet.dataType);
+}
+function snip(value, dataType, origin) {
+	if (DEV && isSnippet(value)) throw new Error("Cannot nest snippets");
+	return new SnippetImpl(value, undecorate(dataType), origin);
+}
+
+//#endregion
+export { isEphemeralOrigin, isEphemeralSnippet, isSnippet, isSnippetNumeric, originToPtrParams, snip };

package/data/struct.d.ts

@@ -0,0 +1,17 @@
+import { AnyWgslData, WgslStruct } from "./wgslTypes.js";
+
+//#region src/data/struct.d.ts
+/**
+ * Creates a struct schema that can be used to construct GPU buffers.
+ * Ensures proper alignment and padding of properties (as opposed to a `d.unstruct` schema).
+ * The order of members matches the passed in properties object.
+ *
+ * @example
+ * const CircleStruct = d.struct({ radius: d.f32, pos: d.vec3f });
+ *
+ * @param props Record with `string` keys and `TgpuData` values,
+ * each entry describing one struct member.
+ */
+declare function struct<TProps extends Record<string, AnyWgslData>>(props: TProps): WgslStruct<TProps>;
+//#endregion
+export { struct };

package/data/struct.js

@@ -0,0 +1,46 @@
+import { $internal } from "../shared/symbols.js";
+import { getName, setName } from "../shared/meta.js";
+import { schemaCallWrapper } from "./schemaCallWrapper.js";
+import { isValidProp } from "../nameRegistry.js";
+
+//#region src/data/struct.ts
+/**
+* Creates a struct schema that can be used to construct GPU buffers.
+* Ensures proper alignment and padding of properties (as opposed to a `d.unstruct` schema).
+* The order of members matches the passed in properties object.
+*
+* @example
+* const CircleStruct = d.struct({ radius: d.f32, pos: d.vec3f });
+*
+* @param props Record with `string` keys and `TgpuData` values,
+* each entry describing one struct member.
+*/
+function struct(props) {
+	return INTERNAL_createStruct(props, false);
+}
+function abstruct(props) {
+	return INTERNAL_createStruct(props, true);
+}
+function INTERNAL_createStruct(props, isAbstruct) {
+	Object.keys(props).forEach((key) => {
+		if (!isValidProp(key)) throw new Error(`Property key '${key}' is a reserved WGSL word. Choose a different name.`);
+	});
+	const structSchema = (instanceProps) => Object.fromEntries(Object.entries(props).map(([key, schema]) => [key, schemaCallWrapper(schema, instanceProps?.[key])]));
+	Object.setPrototypeOf(structSchema, WgslStructImpl);
+	structSchema.propTypes = props;
+	Object.defineProperty(structSchema, $internal, { value: { isAbstruct } });
+	return structSchema;
+}
+const WgslStructImpl = {
+	type: "struct",
+	$name(label) {
+		setName(this, label);
+		return this;
+	},
+	toString() {
+		return `struct:${getName(this) ?? "<unnamed>"}`;
+	}
+};
+
+//#endregion
+export { INTERNAL_createStruct, abstruct, struct };