typegpu/core/resolve/tgpuResolve.d.ts

A thin layer between JS and WebGPU/WGSL that improves development experience and allows for faster iteration.

import { type ResolutionResult } from '../../resolutionCtx.ts';
import type { ShaderGenerator } from '../../tgsl/shaderGenerator.ts';
import { type ResolvableObject, type Wgsl } from '../../types.ts';
import type { WgslEnableExtension } from '../../wgslExtensions.ts';
import type { Configurable } from '../root/rootTypes.ts';
import { type Namespace } from './namespace.ts';
export interface TgpuResolveOptions {
    /**
     * The naming strategy used for generating identifiers for resolved externals and their dependencies.
     *
     * ## Namespaces
     * Each call to `tgpu.resolve` uses its own namespace by default, but a
     * custom namespace can be created with `tgpu['~unstable'].namespace` and passed in.
     *
     * This allows tracking the behavior of the resolution process, as well as
     * sharing state between calls to `tgpu.resolve`.
     *
     * @default 'strict'
     */
    names?: 'strict' | 'random' | Namespace | undefined;
    /**
     * When set to true, the resulting shaders will be stripped from all unnecessary whitespace.
     *
     * @default false
     */
    unstable_minify?: boolean;
    /**
     * A function to configure the resolution context.
     */
    config?: ((cfg: Configurable) => Configurable) | undefined;
    /**
     * List of WGSL shader extensions to enable.
     */
    enableExtensions?: WgslEnableExtension[] | undefined;
    /**
     * **NOTE: This is an unstable API and may change in the future.**
     *
     * A custom shader code generator, used when resolving TypeGPU functions.
     * If not provided, the default WGSL generator will be used.
     */
    unstable_shaderGenerator?: ShaderGenerator | undefined;
}
export 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);
 * // }
 * ```
 */
export 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,
 * // }
 * ```
 */
export 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);
 * // }
 * ```
 */
export declare function resolve(options: TgpuExtendedResolveOptions): string;
export declare function resolve(items: ResolvableObject[], options?: TgpuResolveOptions): string;