typegpu 0.1.2 → 0.2.0-alpha.0

package/index.d.cts

@@ -1,40 +1,296 @@
+import { T as TgpuRenderResource, a as TgpuNamable, b as TgpuBuffer, A as AnyTgpuData, O as OmitProps, c as TgpuBufferUsage, U as Uniform, S as Storage, d as TgpuBufferUniform, e as TgpuShaderStage, f as TgpuBufferReadonly, g as TgpuBufferMutable, h as U32, I as I32, F as F32, V as Vec4u, i as Vec4i, j as Vec4f, k as TgpuPlum, E as ExtractPlumValue, l as Unsubscribe, m as TgpuCode, B as BoundTgpuCode, n as Block, v as vecBase, o as vec3f, p as vec3i, q as vec3u } from './types-qmW7FFqN.cjs';
+export { r as TgpuData, w as Vertex, s as isUsableAsStorage, t as isUsableAsUniform, u as isUsableAsVertex } from './types-qmW7FFqN.cjs';
 import { Parsed } from 'typed-binary';
-import { A as AnyTgpuData, T as TgpuAllocatable, a as TgpuNamable, b as TgpuPlum, v as vecBase, c as vec3f, d as vec3i, e as vec3u } from './vector-D5Vx-xhb.cjs';
-export { f as TgpuData } from './vector-D5Vx-xhb.cjs';
 
-interface Unmanaged {
+declare const TgpuSettableTrait: unique symbol;
+interface TgpuSettable {
+    readonly [TgpuSettableTrait]: true;
+}
+
+type PlumListener<T> = (newValue: T) => unknown;
+
+interface TgpuSampler extends TgpuRenderResource, TgpuNamable {
+    readonly descriptor: GPUSamplerDescriptor;
+}
+
+interface Unwrapper {
     readonly device: GPUDevice;
-    readonly buffer: GPUBuffer;
+    unwrap(resource: TgpuBuffer<AnyTgpuData>): GPUBuffer;
+    unwrap(resource: TgpuBindGroupLayout): GPUBindGroupLayout;
+    unwrap(resource: TgpuBindGroup): GPUBindGroup;
 }
-interface Uniform {
-    usableAsUniform: true;
+
+type TgpuLayoutEntryBase = {
+    /**
+     * Limits this resource's visibility to specific shader stages.
+     *
+     * By default, each resource is visible to all shader stage types, but
+     * depending on the underlying implementation, this may have performance implications.
+     *
+     * @default ['compute'] for mutable resources
+     * @default ['compute','vertex','fragment'] for everything else
+     */
+    visibility?: TgpuShaderStage[];
+};
+type TgpuLayoutUniform = TgpuLayoutEntryBase & {
+    uniform: AnyTgpuData | ((arrayLength: number) => AnyTgpuData);
+};
+type TgpuLayoutStorage = TgpuLayoutEntryBase & {
+    storage: AnyTgpuData | ((arrayLength: number) => AnyTgpuData);
+    /** @default 'readonly' */
+    access?: 'mutable' | 'readonly';
+};
+type TgpuLayoutSampler = TgpuLayoutEntryBase & {
+    sampler: GPUSamplerBindingType;
+};
+type TgpuLayoutTexture<TSampleType extends GPUTextureSampleType = GPUTextureSampleType> = TgpuLayoutEntryBase & {
+    /**
+     * - 'float' - f32
+     * - 'unfilterable-float' - f32, cannot be used with filtering samplers
+     * - 'depth' - f32
+     * - 'sint' - i32
+     * - 'uint' - u32
+     */
+    texture: TSampleType;
+    /**
+     * @default '2d'
+     */
+    viewDimension?: GPUTextureViewDimension;
+    /**
+     * @default false
+     */
+    multisampled?: boolean;
+};
+type TgpuLayoutStorageTexture<TFormat extends GPUTextureFormat = GPUTextureFormat> = TgpuLayoutEntryBase & {
+    storageTexture: TFormat;
+    /** @default 'writeonly' */
+    access?: 'readonly' | 'writeonly' | 'mutable';
+    /** @default '2d' */
+    viewDimension?: GPUTextureViewDimension;
+};
+type TgpuLayoutExternalTexture = TgpuLayoutEntryBase & {
+    externalTexture: Record<string, never>;
+};
+type TgpuLayoutEntry = TgpuLayoutUniform | TgpuLayoutStorage | TgpuLayoutSampler | TgpuLayoutTexture | TgpuLayoutStorageTexture | TgpuLayoutExternalTexture;
+type UnwrapRuntimeConstructorInner<T extends AnyTgpuData | ((_: number) => AnyTgpuData)> = T extends AnyTgpuData ? T : T extends (_: number) => infer Return ? Return : never;
+type UnwrapRuntimeConstructor<T extends AnyTgpuData | ((_: number) => AnyTgpuData)> = T extends unknown ? UnwrapRuntimeConstructorInner<T> : never;
+interface TgpuBindGroupLayout<Entries extends Record<string, TgpuLayoutEntry | null> = Record<string, TgpuLayoutEntry | null>> extends TgpuNamable {
+    readonly resourceType: 'bind-group-layout';
+    readonly label: string | undefined;
+    readonly entries: Entries;
+    populate(entries: {
+        [K in keyof OmitProps<Entries, null>]: LayoutEntryToInput<Entries[K]>;
+    }): TgpuBindGroup<Entries>;
+    /**
+     * Creates a raw WebGPU resource based on the typed descriptor.
+     * NOTE: This creates a new resource every time, better to use `root.unwrap(...)` instead.
+     * @param unwrapper Used to unwrap any resources that this resource depends on.
+     */
+    unwrap(unwrapper: Unwrapper): GPUBindGroupLayout;
 }
-declare const Uniform: Uniform;
-interface Storage {
-    usableAsStorage: true;
+type StorageUsageForEntry<T extends TgpuLayoutStorage> = T extends {
+    access?: infer Access;
+} ? 'mutable' | 'readonly' extends Access ? TgpuBufferReadonly<UnwrapRuntimeConstructor<T['storage']>> | TgpuBufferMutable<UnwrapRuntimeConstructor<T['storage']>> : 'readonly' extends Access ? TgpuBufferReadonly<UnwrapRuntimeConstructor<T['storage']>> : 'mutable' extends Access ? TgpuBufferMutable<UnwrapRuntimeConstructor<T['storage']>> : TgpuBufferReadonly<UnwrapRuntimeConstructor<T['storage']>> | TgpuBufferMutable<UnwrapRuntimeConstructor<T['storage']>> : TgpuBufferReadonly<UnwrapRuntimeConstructor<T['storage']>>;
+type LayoutEntryToInput<T extends TgpuLayoutEntry | null> = T extends TgpuLayoutUniform ? TgpuBufferUsage<UnwrapRuntimeConstructor<T['uniform']>, 'uniform'> | (TgpuBuffer<UnwrapRuntimeConstructor<T['uniform']>> & Uniform) | GPUBuffer : T extends TgpuLayoutStorage ? StorageUsageForEntry<T> | (TgpuBuffer<UnwrapRuntimeConstructor<T['storage']>> & Storage) | GPUBuffer : T extends TgpuLayoutSampler ? GPUSampler : T extends TgpuLayoutTexture ? GPUTextureView : T extends TgpuLayoutStorageTexture ? GPUTextureView : T extends TgpuLayoutExternalTexture ? GPUExternalTexture : never;
+type BindLayoutEntry<T extends TgpuLayoutEntry | null> = T extends TgpuLayoutUniform ? TgpuBufferUniform<UnwrapRuntimeConstructor<T['uniform']>> : T extends TgpuLayoutStorage ? StorageUsageForEntry<T> : T extends TgpuLayoutSampler ? TgpuSampler : never;
+type TgpuBindGroup<Entries extends Record<string, TgpuLayoutEntry | null> = Record<string, TgpuLayoutEntry | null>> = {
+    readonly resourceType: 'bind-group';
+    readonly layout: TgpuBindGroupLayout<Entries>;
+    unwrap(unwrapper: Unwrapper): GPUBindGroup;
+};
+declare function bindGroupLayout<Entries extends Record<string, TgpuLayoutEntry | null>>(entries: Entries): TgpuBindGroupLayout<Entries>;
+
+type StorageTextureAccess = 'read' | 'write' | 'read_write';
+type TextureScalarFormat = U32 | I32 | F32;
+type TexelFormat = Vec4u | Vec4i | Vec4f;
+
+type Optional<T> = {
+    [P in keyof T]?: T[P] | undefined;
+};
+interface TgpuAnyTextureView extends TgpuRenderResource {
+    readonly descriptor: GPUTextureViewDescriptor;
+    readonly texture: TgpuAnyTexture;
+    readonly dataType: TextureScalarFormat | TexelFormat;
+    readonly access: StorageTextureAccess | undefined;
 }
-declare const Storage: Storage;
-interface Vertex {
-    usableAsVertex: true;
+interface TgpuAnyTexture {
+    readonly descriptor: Omit<GPUTextureDescriptor, 'usage'>;
+    get flags(): GPUTextureUsageFlags;
 }
-declare const Vertex: Vertex;
-type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
-interface TgpuBuffer<TData extends AnyTgpuData> extends TgpuAllocatable<TData>, TgpuNamable {
-    readonly destroyed: boolean;
-    readonly label: string | undefined;
-    $usage<T extends (Uniform | Storage | Vertex)[]>(...usages: T): this & UnionToIntersection<T[number]>;
-    $addFlags(flags: GPUBufferUsageFlags): this;
-    $device(device: GPUDevice): this & Unmanaged;
+interface TgpuTextureExternal extends TgpuRenderResource, TgpuNamable {
+    readonly descriptor: Optional<GPUExternalTextureDescriptor>;
+    get source(): HTMLVideoElement | VideoFrame | undefined;
+}
+
+type SetPlumAction<T> = T | ((prev: T) => T);
+interface TgpuRoot extends Unwrapper {
+    /**
+     * The GPU device associated with this root.
+     */
+    readonly device: GPUDevice;
+    /**
+     * @param typeSchema The type of data that this buffer will hold.
+     * @param initial The initial value of the buffer. (optional)
+     */
+    createBuffer<TData extends AnyTgpuData>(typeSchema: TData, initial?: Parsed<TData> | TgpuPlum<Parsed<TData>> | undefined): TgpuBuffer<TData>;
+    /**
+     * @param typeSchema The type of data that this buffer will hold.
+     * @param gpuBuffer A vanilla WebGPU buffer.
+     */
+    createBuffer<TData extends AnyTgpuData>(typeSchema: TData, gpuBuffer: GPUBuffer): TgpuBuffer<TData>;
+    unwrap(resource: TgpuBuffer<AnyTgpuData>): GPUBuffer;
+    unwrap(resource: TgpuBindGroupLayout): GPUBindGroupLayout;
+    unwrap(resource: TgpuBindGroup): GPUBindGroup;
     destroy(): void;
 }
+interface ExperimentalTgpuRoot extends TgpuRoot {
+    readonly jitTranspiler?: JitTranspiler | undefined;
+    /**
+     * The current command encoder. This property will
+     * hold the same value until `flush()` is called.
+     */
+    readonly commandEncoder: GPUCommandEncoder;
+    readPlum<TPlum extends TgpuPlum>(plum: TPlum): ExtractPlumValue<TPlum>;
+    setPlum<TPlum extends TgpuPlum & TgpuSettable>(plum: TPlum, value: SetPlumAction<ExtractPlumValue<TPlum>>): void;
+    onPlumChange<TValue>(plum: TgpuPlum<TValue>, listener: PlumListener<TValue>): Unsubscribe;
+    setSource(texture: TgpuTextureExternal, source: HTMLVideoElement | VideoFrame): void;
+    isDirty(texture: TgpuTextureExternal): boolean;
+    markClean(texture: TgpuTextureExternal): void;
+    textureFor(view: TgpuAnyTexture | TgpuAnyTextureView): GPUTexture;
+    viewFor(view: TgpuAnyTextureView): GPUTextureView;
+    externalTextureFor(texture: TgpuTextureExternal): GPUExternalTexture;
+    samplerFor(sampler: TgpuSampler): GPUSampler;
+    /**
+     * Causes all commands enqueued by pipelines to be
+     * submitted to the GPU.
+     */
+    flush(): void;
+    makeRenderPipeline(options: RenderPipelineOptions): RenderPipelineExecutor;
+    makeComputePipeline(options: ComputePipelineOptions): ComputePipelineExecutor;
+}
+interface RenderPipelineOptions {
+    vertex: {
+        code: TgpuCode | BoundTgpuCode;
+        output: {
+            [K in symbol]: string;
+        } & {
+            [K in string]: AnyTgpuData;
+        };
+    };
+    fragment: {
+        code: TgpuCode | BoundTgpuCode;
+        target: Iterable<GPUColorTargetState | null>;
+    };
+    primitive: GPUPrimitiveState;
+    externalLayouts?: GPUBindGroupLayout[];
+    label?: string;
+}
+interface ComputePipelineOptions {
+    code: TgpuCode | BoundTgpuCode;
+    workgroupSize?: readonly [number, number?, number?];
+    externalLayouts?: GPUBindGroupLayout[];
+    label?: string;
+}
+type RenderPipelineExecutorOptions = GPURenderPassDescriptor & {
+    vertexCount: number;
+    instanceCount?: number;
+    firstVertex?: number;
+    firstInstance?: number;
+    externalBindGroups?: GPUBindGroup[];
+};
+interface RenderPipelineExecutor {
+    execute(options: RenderPipelineExecutorOptions): void;
+}
+type ComputePipelineExecutorOptions = {
+    workgroups?: readonly [number, number?, number?];
+    externalBindGroups?: GPUBindGroup[];
+};
+interface ComputePipelineExecutor {
+    execute(options?: ComputePipelineExecutorOptions): void;
+}
+
+/**
+ * Information extracted from transpiling a JS function.
+ */
+type TranspilationResult = {
+    argNames: string[];
+    body: Block;
+    /**
+     * All identifiers found in the function code that are not declared in the
+     * function itself, or in the block that is accessing that identifier.
+     */
+    externalNames: string[];
+};
+
+/**
+ * Used to transpile JS resources into SMoL on demand.
+ */
+interface JitTranspiler {
+    transpileFn(rawJs: string): TranspilationResult;
+}
+
+/**
+ * Options passed into {@link init}.
+ */
+type InitOptions = {
+    adapter?: GPURequestAdapterOptions | undefined;
+    device?: GPUDeviceDescriptor | undefined;
+    unstable_jitTranspiler?: JitTranspiler | undefined;
+};
+/**
+ * Options passed into {@link initFromDevice}.
+ */
+type InitFromDeviceOptions = {
+    device: GPUDevice;
+    unstable_jitTranspiler?: JitTranspiler | 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<ExperimentalTgpuRoot>;
+/**
+ * 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): ExperimentalTgpuRoot;
+
+/**
+ * @deprecated Use the `root.createBuffer` API instead, accessible through `await tgpu.init()`
+ *
+ * @param typeSchema The type of data that this buffer will hold.
+ * @param initial The initial value of the buffer. (optional)
+ */
 declare function createBuffer<TData extends AnyTgpuData>(typeSchema: TData, initial?: Parsed<TData> | TgpuPlum<Parsed<TData>> | undefined): TgpuBuffer<TData>;
+/**
+ * @deprecated Use the `root.createBuffer` API instead, accessible through `await tgpu.init()`
+ *
+ * @param typeSchema The type of data that this buffer will hold.
+ * @param gpuBuffer A vanilla WebGPU buffer.
+ */
 declare function createBuffer<TData extends AnyTgpuData>(typeSchema: TData, gpuBuffer: GPUBuffer): TgpuBuffer<TData>;
-declare function isUsableAsUniform<T extends TgpuBuffer<AnyTgpuData>>(buffer: T): buffer is T & Uniform;
-declare function isUsableAsStorage<T extends TgpuBuffer<AnyTgpuData>>(buffer: T): buffer is T & Storage;
-declare function isUsableAsVertex<T extends TgpuBuffer<AnyTgpuData>>(buffer: T): buffer is T & Vertex;
 
-declare function write<TData extends AnyTgpuData>(buffer: TgpuBuffer<TData> & Unmanaged, data: Parsed<TData>): void;
-declare function read<TData extends AnyTgpuData>(buffer: TgpuBuffer<TData> & Unmanaged): Promise<Parsed<TData>>;
+declare function write<TData extends AnyTgpuData>(buffer: TgpuBuffer<TData>, data: Parsed<TData>): void;
+declare function read<TData extends AnyTgpuData>(buffer: TgpuBuffer<TData>): Promise<Parsed<TData>>;
 
 /**
  * @category Errors
@@ -44,16 +300,16 @@ declare class RecursiveDataTypeError extends Error {
 }
 
 declare const std: {
-    add: <T extends vecBase>(lhs: T, rhs: T) => T;
-    sub: <T extends vecBase>(lhs: T, rhs: T) => T;
+    add<T extends vecBase>(lhs: T, rhs: T): T;
+    sub<T extends vecBase>(lhs: T, rhs: T): T;
     mul: <T extends vecBase>(s: number, v: T) => T;
-    dot: <T extends vecBase>(lhs: T, rhs: T) => number;
+    dot<T extends vecBase>(lhs: T, rhs: T): number;
     normalize: <T extends vecBase>(v: T) => T;
-    cross: <T extends vec3f | vec3i | vec3u>(a: T, b: T) => T;
-    fract: (a: number) => number;
-    length: <T extends vecBase>(vector: T) => number;
-    sin: (x: number) => number;
-    cos: (x: number) => number;
+    cross<T extends vec3f | vec3i | vec3u>(a: T, b: T): T;
+    fract(a: number): number;
+    length<T extends vecBase>(vector: T): number;
+    sin(radians: number): number;
+    cos(radians: number): number;
 };
 
 /**
@@ -61,12 +317,18 @@ declare const std: {
  */
 
 declare const tgpu: {
-    Uniform: Uniform;
-    Storage: Storage;
-    Vertex: Vertex;
+    /** @deprecated Use `'uniform'` string literal instead. */
+    Uniform: "uniform";
+    /** @deprecated Use `'storage'` string literal instead. */
+    Storage: "storage";
+    /** @deprecated Use `'vertex'` string literal instead. */
+    Vertex: "vertex";
+    bindGroupLayout: typeof bindGroupLayout;
+    init: typeof init;
+    initFromDevice: typeof initFromDevice;
     createBuffer: typeof createBuffer;
     read: typeof read;
     write: typeof write;
 };
 
-export { AnyTgpuData, RecursiveDataTypeError, type TgpuBuffer, type Unmanaged, tgpu as default, isUsableAsStorage, isUsableAsUniform, isUsableAsVertex, std, tgpu };
+export { AnyTgpuData, type BindLayoutEntry, type LayoutEntryToInput, RecursiveDataTypeError, Storage, type TgpuBindGroup, type TgpuBindGroupLayout, TgpuBuffer, type TgpuLayoutEntry, type TgpuLayoutSampler, type TgpuLayoutUniform, Uniform, tgpu as default, std, tgpu };