typegpu/index.d.ts

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

import { T as TgpuBindGroupLayout, a as TgpuBindGroup, W as Wgsl, b as TgpuRoot, A as AnyWgslData, c as TgpuFn, d as TgpuBufferUsage, I as Infer, e as TgpuAccessor, f as TgpuDerived, g as TgpuSlot, h as TgpuVertexLayout, i as WgslArray, D as Disarray, j as TgpuBuffer, k as AnyData, l as fn, m as bindGroupLayout, v as vertexLayout, n as fragmentFn, o as vertexFn, p as computeFn, q as privateVar, w as workgroupVar, r as constant, s as declare, t as sampler, u as comparisonSampler } from './tgpuComputeFn-DOUjhQua.js';
export { as as BindLayoutEntry, V as Configurable, ae as Eventual, at as ExtractBindGroupInputFromLayout, aL as INTERNAL_GlobalExt, a3 as IndexFlag, au as LayoutEntryToInput, R as RandomNameRegistry, am as Render, an as Sampled, $ as Storage, a0 as StorageFlag, S as StrictNameRegistry, al as TextureProps, af as TgpuAnyTextureView, a8 as TgpuBufferMutable, a9 as TgpuBufferReadonly, aa as TgpuBufferUniform, aI as TgpuComputeFn, aJ as TgpuComputeFnShell, a2 as TgpuComputePipeline, ao as TgpuConst, aK as TgpuDeclare, aD as TgpuFnShell, aG as TgpuFragmentFn, aH as TgpuFragmentFnShell, av as TgpuLayoutComparisonSampler, aw as TgpuLayoutEntry, ax as TgpuLayoutExternalTexture, ay as TgpuLayoutSampler, az as TgpuLayoutStorage, aA as TgpuLayoutStorageTexture, aB as TgpuLayoutTexture, aC as TgpuLayoutUniform, ab as TgpuMutable, ag as TgpuMutableTexture, ac as TgpuReadonly, ah as TgpuReadonlyTexture, a1 as TgpuRenderPipeline, ai as TgpuSampledTexture, ar as TgpuSampler, aj as TgpuTexture, ad as TgpuUniform, ap as TgpuVar, aE as TgpuVertexFn, aF as TgpuVertexFnShell, ak as TgpuWriteonlyTexture, a4 as Uniform, a5 as UniformFlag, aq as VariableScope, a6 as Vertex, a7 as VertexFlag, X as WithBinding, Y as WithCompute, Z as WithFragment, _ as WithVertex, x as isBuffer, Q as isBufferShorthand, C as isComparisonSampler, z as isDerived, F as isSampledTextureView, E as isSampler, B as isSlot, G as isStorageTextureView, H as isTexture, U as isTgpuFn, J as isUsableAsRender, K as isUsableAsSampled, L as isUsableAsStorage, P as isUsableAsUniform, y as isUsableAsVertex, M as unstable_asMutable, N as unstable_asReadonly, O as unstable_asUniform } from './tgpuComputeFn-DOUjhQua.js';
import 'tinyest';

/**
 * The results of a WGSL resolution.
 *
 * @param code - The resolved code.
 * @param usedBindGroupLayouts - List of used `tgpu.bindGroupLayout`s.
 * @param catchall - Automatically constructed bind group for buffer usages and buffer shorthands, preceded by its index.
 */
interface ResolutionResult {
    code: string;
    usedBindGroupLayouts: TgpuBindGroupLayout[];
    catchall: [number, TgpuBindGroup] | undefined;
}

interface 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;
    /**
     * The naming strategy used for generating identifiers for resolved externals and their dependencies.
     * @default 'random'
     */
    names?: 'strict' | 'random' | undefined;
}
/**
 * Resolves a template with external values. Each external 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: TgpuResolveOptions): ResolutionResult;
/**
 * Resolves a template with external values. Each external 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 The resolved code.
 *
 * @example
 * ```ts
 * const Gradient = d.struct({
 *   from: d.vec3f,
 *   to: d.vec3f,
 * });
 *
 * const resolved = 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(resolved);
 * // 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: TgpuResolveOptions): string;

/**
 * Options passed into {@link init}.
 */
type InitOptions = {
    adapter?: GPURequestAdapterOptions | undefined;
    device?: GPUDeviceDescriptor & {
        optionalFeatures?: Iterable<GPUFeatureName>;
    } | undefined;
    /** @default 'random' */
    unstable_names?: 'random' | 'strict' | undefined;
};
/**
 * Options passed into {@link initFromDevice}.
 */
type InitFromDeviceOptions = {
    device: GPUDevice;
    /** @default 'random' */
    unstable_names?: 'random' | 'strict' | undefined;
};
/**
 * 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;

declare function accessor<T extends AnyWgslData>(schema: T, defaultValue?: TgpuFn<() => T> | TgpuBufferUsage<T> | Infer<T>): TgpuAccessor<T>;

declare function derived<T>(compute: () => T): TgpuDerived<T>;

declare function slot<T>(defaultValue?: T): TgpuSlot<T>;

/**
 * An error that happens during resolution of WGSL code.
 * Contains a trace of all ancestor resolvables in
 * which this error originated.
 *
 * @category Errors
 */
declare class ResolutionError extends Error {
    readonly cause: unknown;
    readonly trace: unknown[];
    constructor(cause: unknown, trace: unknown[]);
    appendToTrace(ancestor: unknown): ResolutionError;
}
/**
 * @category Errors
 */
declare class MissingSlotValueError extends Error {
    readonly slot: TgpuSlot<unknown>;
    constructor(slot: TgpuSlot<unknown>);
}
/**
 * @category Errors
 */
declare class NotUniformError extends Error {
    constructor(value: TgpuBuffer<AnyData>);
}
declare class MissingLinksError extends Error {
    constructor(fnLabel: string | undefined, externalNames: string[]);
}
declare class MissingBindGroupsError extends Error {
    constructor(layouts: Iterable<TgpuBindGroupLayout>);
}
declare class MissingVertexBuffersError extends Error {
    constructor(layouts: Iterable<TgpuVertexLayout<WgslArray | Disarray>>);
}

/**
 * @module typegpu
 */

declare const tgpu: {
    fn: typeof fn;
    bindGroupLayout: typeof bindGroupLayout;
    vertexLayout: typeof vertexLayout;
    slot: typeof slot;
    init: typeof init;
    initFromDevice: typeof initFromDevice;
    resolve: typeof resolve;
    resolveWithContext: typeof resolveWithContext;
    '~unstable': {
        /**
         * @deprecated This feature is now stable, use tgpu.fn.
         */
        fn: typeof fn;
        fragmentFn: typeof fragmentFn;
        vertexFn: typeof vertexFn;
        computeFn: typeof computeFn;
        /**
         * @deprecated This feature is now stable, use tgpu.vertexLayout.
         */
        vertexLayout: typeof vertexLayout;
        derived: typeof derived;
        /**
         * @deprecated This feature is now stable, use tgpu.slot.
         */
        slot: typeof slot;
        accessor: typeof accessor;
        privateVar: typeof privateVar;
        workgroupVar: typeof workgroupVar;
        const: typeof constant;
        declare: typeof declare;
        sampler: typeof sampler;
        comparisonSampler: typeof comparisonSampler;
    };
};

export { type InitFromDeviceOptions, type InitOptions, MissingBindGroupsError, MissingLinksError, MissingSlotValueError, MissingVertexBuffersError, NotUniformError, ResolutionError, TgpuAccessor, TgpuBindGroup, TgpuBindGroupLayout, TgpuBuffer, TgpuDerived, TgpuFn, TgpuRoot, TgpuSlot, TgpuVertexLayout, tgpu as default, tgpu };