typegpu 0.10.0 → 0.10.2

package/core/resolve/tgpuResolve.d.ts

@@ -0,0 +1,151 @@
+import { ShaderGenerator } from "../../tgsl/shaderGenerator.js";
+import { Configurable } from "../root/rootTypes.js";
+import { WgslExtension } from "../../wgslExtensions.js";
+import { ResolvableObject, Wgsl } from "../../types.js";
+import { Namespace } from "./namespace.js";
+import { ResolutionResult } from "../../resolutionCtx.js";
+
+//#region src/core/resolve/tgpuResolve.d.ts
+interface TgpuResolveOptions {
+  /**
+   * The naming strategy used for generating identifiers for resolved externals and their dependencies.
+   *
+   * ## Namespaces
+   * Each call to `tgpu.resolve` uses it's own namespace by default, but a
+   * custom namespace can be created with `tgpu.namespace` and passed in.
+   *
+   * This allows tracking the behavior of the resolution process, as well as
+   * sharing state between calls to `tgpu.resolve`.
+   *
+   * @default 'random'
+   */
+  names?: 'strict' | 'random' | Namespace | undefined;
+  /**
+   * A function to configure the resolution context.
+   */
+  config?: ((cfg: Configurable) => Configurable) | undefined;
+  /**
+   * List of WGSL shader extensions to enable.
+   */
+  enableExtensions?: WgslExtension[] | undefined;
+  /**
+   * A custom shader code generator, used when resolving TypeGPU functions.
+   * If not provided, the default WGSL generator will be used.
+   */
+  shaderGenerator?: ShaderGenerator | undefined;
+}
+interface TgpuExtendedResolveOptions extends TgpuResolveOptions {
+  /**
+   * Map of external names to their resolvable values.
+   */
+  externals: Record<string, Wgsl | object>;
+  /**
+   * The code template to use for the resolution. All external names will be replaced with their resolved values.
+   * @default ''
+   */
+  template?: string | undefined;
+}
+/**
+ * Resolves a template with external values. Each external that is used will get resolved to a code string and replaced in the template.
+ * Any dependencies of the externals will also be resolved and included in the output.
+ * @param options - The options for the resolution.
+ *
+ * @returns {ResolutionResult}
+ *
+ * @example
+ * ```ts
+ * const Gradient = d.struct({ from: d.vec3f, to: d.vec3f });
+ *
+ * const { code, usedBindGroupLayouts, catchall } = tgpu.resolveWithContext({
+ *   template: `
+ *     fn getGradientAngle(gradient: Gradient) -> f32 {
+ *       return atan(gradient.to.y - gradient.from.y, gradient.to.x - gradient.from.x);
+ *     }
+ *   `,
+ *   externals: {
+ *     Gradient,
+ *   },
+ * });
+ *
+ * console.log(code);
+ * // struct Gradient_0 {
+ * //   from: vec3f,
+ * //   to: vec3f,
+ * // }
+ * // fn getGradientAngle(gradient: Gradient_0) -> f32 {
+ * //   return atan(gradient.to.y - gradient.from.y, gradient.to.x - gradient.from.x);
+ * // }
+ * ```
+ */
+declare function resolveWithContext(options: TgpuExtendedResolveOptions): ResolutionResult;
+/**
+ * Resolves given TypeGPU resources.
+ * Any dependencies of the externals will also be resolved and included in the output.
+ * @param items - An array of items to resolve.
+ * @param options - The options for the resolution.
+ *
+ * @returns {ResolutionResult}
+ *
+ * @example
+ * ```ts
+ * const Gradient = d.struct({
+ *   from: d.vec3f,
+ *   to: d.vec3f,
+ * });
+ *
+ * const { code, usedBindGroupLayouts, catchall } =
+ *   tgpu.resolveWithContext([Gradient]);
+ *
+ * console.log(code);
+ * // struct Gradient_0 {
+ * //   from: vec3f,
+ * //   to: vec3f,
+ * // }
+ * ```
+ */
+declare function resolveWithContext(items: ResolvableObject[], options?: TgpuResolveOptions): ResolutionResult;
+/**
+ * A shorthand for calling `tgpu.resolveWithContext(...).code`.
+ *
+ * @example
+ * ```ts
+ * const Gradient = d.struct({ from: d.vec3f, to: d.vec3f });
+ *
+ * const resolved = tgpu.resolve([Gradient]);
+ *
+ * console.log(resolved);
+ * // struct Gradient_0 {
+ * //   from: vec3f,
+ * //   to: vec3f,
+ * // }
+ * ```
+ *
+ * @example
+ * ```ts
+ * const Gradient = d.struct({ from: d.vec3f, to: d.vec3f });
+ *
+ * const code = tgpu.resolve({
+ *   template: `
+ *     fn getGradientAngle(gradient: Gradient) -> f32 {
+ *       return atan(gradient.to.y - gradient.from.y, gradient.to.x - gradient.from.x);
+ *     }
+ *   `,
+ *   externals: {
+ *     Gradient,
+ *   },
+ * });
+ *
+ * console.log(code);
+ * // struct Gradient_0 {
+ * //   from: vec3f,
+ * //   to: vec3f,
+ * // }
+ * // fn getGradientAngle(gradient: Gradient_0) -> f32 {
+ * //   return atan(gradient.to.y - gradient.from.y, gradient.to.x - gradient.from.x);
+ * // }
+ * ```
+ */
+declare function resolve(options: TgpuExtendedResolveOptions): string;
+declare function resolve(items: ResolvableObject[], options?: TgpuResolveOptions): string;
+//#endregion
+export { resolve, resolveWithContext };

package/core/resolve/tgpuResolve.js

@@ -0,0 +1,68 @@
+import { $internal, $resolve } from "../../shared/symbols.js";
+import { Void } from "../../data/wgslTypes.js";
+import { snip } from "../../data/snippet.js";
+import { applyExternals, replaceExternalsInWgsl } from "./externals.js";
+import { namespace } from "./namespace.js";
+import { isBindGroupLayout } from "../../tgpuBindGroupLayout.js";
+import { resolve as resolve$1 } from "../../resolutionCtx.js";
+import { isPipeline } from "../pipeline/typeGuards.js";
+
+//#region src/core/resolve/tgpuResolve.ts
+function resolveWithContext(arg0, options) {
+	if (Array.isArray(arg0)) return resolveFromArray(arg0, options);
+	return resolveFromTemplate(arg0);
+}
+function resolve(arg, options) {
+	if (Array.isArray(arg)) return resolveWithContext(arg, options).code;
+	return resolveWithContext(arg).code;
+}
+function resolveFromTemplate(options) {
+	const { template, externals, shaderGenerator, names = "strict", config, enableExtensions } = options;
+	if (!template) console.warn("Calling resolve with an empty template is deprecated and will soon return an empty string. Consider using the 'tgpu.resolve(resolvableArray, options)' API instead.");
+	const dependencies = {};
+	applyExternals(dependencies, externals ?? {});
+	return resolve$1({
+		[$internal]: true,
+		[$resolve](ctx) {
+			return snip(replaceExternalsInWgsl(ctx, dependencies, template ?? ""), Void, "runtime");
+		},
+		toString: () => "<root>"
+	}, {
+		namespace: typeof names === "string" ? namespace({ names }) : names,
+		enableExtensions,
+		shaderGenerator,
+		config,
+		root: tryFindRoot(Object.values(externals))
+	});
+}
+function resolveFromArray(items, options) {
+	const { shaderGenerator, names = "strict", config, enableExtensions } = options ?? {};
+	return resolve$1({
+		[$internal]: true,
+		[$resolve](ctx) {
+			for (const item of items) if (isBindGroupLayout(item)) for (const binding of Object.values(item[$internal].bound)) ctx.resolve(binding);
+			else ctx.resolve(item);
+			return snip("", Void, "runtime");
+		},
+		toString: () => "<root>"
+	}, {
+		namespace: typeof names === "string" ? namespace({ names }) : names,
+		enableExtensions,
+		shaderGenerator,
+		config,
+		root: tryFindRoot(items)
+	});
+}
+/**
+* Attempts to locate a pipeline in a list of items and returns the root.
+* Does not check recursively.
+* Throws an error if multiple pipelines are found.
+*/
+function tryFindRoot(items) {
+	const pipelines = items.filter(isPipeline);
+	if (pipelines.length > 1) throw new Error(`Found ${pipelines.length} pipelines but can only resolve one at a time.`);
+	return pipelines[0]?.[$internal].root;
+}
+
+//#endregion
+export { resolve, resolveWithContext };

package/core/root/configurableImpl.js

@@ -0,0 +1,18 @@
+import { isAccessor, isMutableAccessor } from "../slot/slotTypes.js";
+
+//#region src/core/root/configurableImpl.ts
+var ConfigurableImpl = class ConfigurableImpl {
+	constructor(bindings) {
+		this.bindings = bindings;
+	}
+	with(slot, value) {
+		return new ConfigurableImpl([...this.bindings, [isAccessor(slot) || isMutableAccessor(slot) ? slot.slot : slot, value]]);
+	}
+	pipe(transform) {
+		const newCfg = transform(this);
+		return new ConfigurableImpl([...this.bindings, ...newCfg.bindings]);
+	}
+};
+
+//#endregion
+export { ConfigurableImpl };

package/core/root/init.d.ts

@@ -0,0 +1,69 @@
+import "../buffer/bufferShorthand.js";
+import { LogGeneratorOptions } from "../../tgsl/consoleLog/types.js";
+import "../pipeline/computePipeline.js";
+import "../../tgpuBindGroupLayout.js";
+import { ShaderGenerator } from "../../tgsl/shaderGenerator.js";
+import { TgpuRoot } from "./rootTypes.js";
+import "../../data/wgslTypes.js";
+
+//#region src/core/root/init.d.ts
+/**
+ * Options passed into {@link init}.
+ */
+type InitOptions = {
+  adapter?: GPURequestAdapterOptions | undefined;
+  device?: (GPUDeviceDescriptor & {
+    optionalFeatures?: Iterable<GPUFeatureName>;
+  }) | undefined; /** @default 'random' */
+  unstable_names?: 'random' | 'strict' | undefined;
+  /**
+   * A custom shader code generator, used when resolving TypeGPU functions.
+   * If not provided, the default WGSL generator will be used.
+   */
+  shaderGenerator?: ShaderGenerator | undefined;
+  unstable_logOptions?: LogGeneratorOptions;
+};
+/**
+ * Options passed into {@link initFromDevice}.
+ */
+type InitFromDeviceOptions = {
+  device: GPUDevice; /** @default 'random' */
+  unstable_names?: 'random' | 'strict' | undefined;
+  /**
+   * A custom shader code generator, used when resolving TypeGPU functions.
+   * If not provided, the default WGSL generator will be used.
+   */
+  shaderGenerator?: ShaderGenerator | undefined;
+  unstable_logOptions?: LogGeneratorOptions;
+};
+/**
+ * Requests a new GPU device and creates a root around it.
+ * If a specific device should be used instead, use @see initFromDevice.
+ *
+ * @example
+ * When given no options, the function will ask the browser for a suitable GPU device.
+ * ```ts
+ * const root = await tgpu.init();
+ * ```
+ *
+ * @example
+ * If there are specific options that should be used when requesting a device, you can pass those in.
+ * ```ts
+ * const adapterOptions: GPURequestAdapterOptions = ...;
+ * const deviceDescriptor: GPUDeviceDescriptor = ...;
+ * const root = await tgpu.init({ adapter: adapterOptions, device: deviceDescriptor });
+ * ```
+ */
+declare function init(options?: InitOptions): Promise<TgpuRoot>;
+/**
+ * Creates a root from the given device, instead of requesting it like @see init.
+ *
+ * @example
+ * ```ts
+ * const device: GPUDevice = ...;
+ * const root = tgpu.initFromDevice({ device });
+ * ```
+ */
+declare function initFromDevice(options: InitFromDeviceOptions): TgpuRoot;
+//#endregion
+export { InitFromDeviceOptions, InitOptions, init, initFromDevice };