typegpu/data/snippet.d.ts

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

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;
}
export interface ResolvedSnippet extends Snippet {
    readonly value: string;
    readonly dataType: BaseData;
}
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;