typegpu 0.11.8 → 0.12.0

package/tgpuBindGroupLayout.d.ts

@@ -1,165 +1,145 @@
-import { TgpuNamable } from "./shared/meta.js";
-import { $gpuValueOf, $internal } from "./shared/symbols.js";
-import { Default, NullableToOptional, Prettify } from "./shared/utilityTypes.js";
-import { WgslComparisonSampler, WgslSampler } from "./data/sampler.js";
-import { StorageFlag } from "./extension.js";
-import { TgpuBufferMutable, TgpuBufferReadonly, TgpuBufferUniform } from "./core/buffer/bufferUsage.js";
-import { SampledFlag } from "./core/texture/usageExtension.js";
-import { Unwrapper } from "./unwrapper.js";
-import { TgpuComparisonSampler, TgpuSampler } from "./core/sampler/sampler.js";
-import { TgpuExternalTexture } from "./core/texture/externalTexture.js";
-import { TgpuBuffer, UniformFlag } from "./core/buffer/buffer.js";
-import { TgpuShaderStage } from "./types.js";
-import { AnyWgslData, BaseData, F32, I32, U32 } from "./data/wgslTypes.js";
-import { StorageTextureFormats } from "./core/texture/textureFormats.js";
-import { StorageTextureDimension, TextureSchemaForDescriptor, WgslExternalTexture, WgslStorageTexture, WgslTexture } from "./data/texture.js";
-import { PropsForSchema, TgpuTexture, TgpuTextureView } from "./core/texture/texture.js";
-import { InferGPU, MemIdentity } from "./shared/repr.js";
-
-//#region src/tgpuBindGroupLayout.d.ts
-
-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','fragment'] for mutable resources
-   * @default ['compute','vertex','fragment'] for everything else
-   */
-  visibility?: TgpuShaderStage[];
-};
-type TgpuLayoutUniform = TgpuLayoutEntryBase & {
-  uniform: BaseData;
-};
-type TgpuLayoutStorage = TgpuLayoutEntryBase & {
-  storage: BaseData | ((arrayLength: number) => BaseData);
-  /** @default 'readonly' */
-  access?: 'mutable' | 'readonly';
-};
-type TgpuLayoutSampler = TgpuLayoutEntryBase & {
-  sampler: 'filtering' | 'non-filtering';
-};
-type TgpuLayoutComparisonSampler = TgpuLayoutEntryBase & {
-  sampler: 'comparison';
-};
-type TgpuLayoutTexture<TSchema$1 extends WgslTexture = WgslTexture> = TgpuLayoutEntryBase & {
-  texture: TSchema$1;
-  sampleType?: GPUTextureSampleType;
+import { type TgpuBuffer, type UniformFlag } from './core/buffer/buffer.ts';
+import { type TgpuComparisonSampler, type TgpuSampler } from './core/sampler/sampler.ts';
+import { type PropsForSchema, type TgpuTexture, type TgpuTextureView } from './core/texture/texture.ts';
+import { type SampledFlag } from './core/texture/usageExtension.ts';
+import { type WgslExternalTexture, type WgslStorageTexture, type WgslTexture } from './data/texture.ts';
+import type { TgpuRoot } from './core/root/rootTypes.ts';
+import type { RestoreContext } from './serial/types.ts';
+import type { BaseData } from './data/wgslTypes.ts';
+import { type StorageFlag } from './extension.ts';
+import type { TgpuNamable } from './shared/meta.ts';
+import type { InferGPU, MemIdentity } from './shared/repr.ts';
+import type { TgpuDeviceOwningSoul, TgpuSoul } from './shared/soul.ts';
+import { $gpuValueOf, $internal, $soul } from './shared/symbols.ts';
+import type { NullableToOptional, Prettify } from './shared/utilityTypes.ts';
+import type { ResolvableObject, ShaderStage } from './types.ts';
+import type { Unwrapper } from './unwrapper.ts';
+import type { WgslComparisonSampler, WgslSampler } from './data/sampler.ts';
+import { type TgpuBufferBinding, type TgpuMutable, type TgpuReadonly, type TgpuUniform } from './core/buffer/bufferBinding.ts';
+export interface LayoutMembership {
+    layout: TgpuBindGroupLayout;
+    key: string;
+    idx: number;
+}
+export 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','fragment'] for mutable resources
+     * @default ['compute','vertex','fragment'] for everything else
+     */
+    visibility?: ShaderStage[];
 };
-type TgpuLayoutStorageTexture<TSchema$1 extends WgslStorageTexture = WgslStorageTexture> = TgpuLayoutEntryBase & {
-  storageTexture: TSchema$1;
+export type TgpuLayoutUniform = TgpuLayoutEntryBase & {
+    uniform: BaseData;
 };
-type TgpuLayoutExternalTexture = TgpuLayoutEntryBase & {
-  externalTexture: WgslExternalTexture;
+export type TgpuLayoutStorage = TgpuLayoutEntryBase & {
+    storage: BaseData | ((arrayLength: number) => BaseData);
+    /** @default 'readonly' */
+    access?: 'mutable' | 'readonly';
 };
-type TgpuLegacyLayoutTexture<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;
+export type TgpuLayoutSampler = TgpuLayoutEntryBase & {
+    sampler: 'filtering' | 'non-filtering';
 };
-type TgpuLegacyLayoutStorageTexture<TFormat extends StorageTextureFormats = StorageTextureFormats> = TgpuLayoutEntryBase & {
-  storageTexture: TFormat;
-  /** @default 'writeonly' */
-  access?: 'readonly' | 'writeonly' | 'mutable';
-  /** @default '2d' */
-  viewDimension?: StorageTextureDimension;
+export type TgpuLayoutComparisonSampler = TgpuLayoutEntryBase & {
+    sampler: 'comparison';
 };
-type TgpuLegacyLayoutExternalTexture = TgpuLayoutEntryBase & {
-  externalTexture: Record<string, never>;
+export type TgpuLayoutTexture<TSchema extends WgslTexture = WgslTexture> = TgpuLayoutEntryBase & {
+    texture: TSchema;
+    sampleType?: GPUTextureSampleType;
 };
-type TgpuLegacyLayoutEntry = TgpuLayoutUniform | TgpuLayoutStorage | TgpuLayoutSampler | TgpuLayoutComparisonSampler | TgpuLegacyLayoutTexture | TgpuLegacyLayoutStorageTexture | TgpuLegacyLayoutExternalTexture;
-type TgpuLayoutEntry = TgpuLayoutUniform | TgpuLayoutStorage | TgpuLayoutSampler | TgpuLayoutComparisonSampler | TgpuLayoutTexture | TgpuLayoutStorageTexture | TgpuLayoutExternalTexture;
-type SampleTypeToPrimitive = {
-  float: F32;
-  'unfilterable-float': F32;
-  depth: F32;
-  sint: I32;
-  uint: U32;
+export type TgpuLayoutStorageTexture<TSchema extends WgslStorageTexture = WgslStorageTexture> = TgpuLayoutEntryBase & {
+    storageTexture: TSchema;
 };
-type LeagcyAccessToAccess = {
-  writeonly: 'write-only';
-  readonly: 'read-only';
-  mutable: 'read-write';
+export type TgpuLayoutExternalTexture = TgpuLayoutEntryBase & {
+    externalTexture: WgslExternalTexture;
 };
-type MapLegacyTextureToUpToDate<T extends Record<string, TgpuLegacyLayoutEntry | TgpuLayoutEntry | null>> = { [K in keyof T]: T[K] extends TgpuLayoutEntry | null ? T[K] : T[K] extends TgpuLegacyLayoutTexture<infer SampleType> ? TgpuLayoutTexture<TextureSchemaForDescriptor<{
-  dimension: Default<T[K]['viewDimension'], '2d'>;
-  sampleType: SampleTypeToPrimitive[SampleType];
-  multisampled: Default<T[K]['multisampled'], false>;
-}>> : T[K] extends TgpuLegacyLayoutStorageTexture<infer Format> ? TgpuLayoutStorageTexture<TextureSchemaForDescriptor<{
-  access: LeagcyAccessToAccess[Default<T[K]['access'], 'writeonly'>];
-  format: Format;
-  dimension: Default<T[K]['viewDimension'], '2d'>;
-}>> : T[K] extends TgpuLegacyLayoutExternalTexture ? TgpuLayoutExternalTexture : never };
-type UnwrapRuntimeConstructorInner<T extends BaseData | ((_: number) => BaseData)> = T extends ((_: number) => BaseData) ? ReturnType<T> : T;
-type UnwrapRuntimeConstructor<T extends BaseData | ((_: number) => BaseData)> = T extends unknown ? UnwrapRuntimeConstructorInner<T> : never;
-interface BindGroupLayoutInternals<Entries extends Record<string, TgpuLayoutEntry | null>> {
-  bound: { [K in keyof Entries]: BindLayoutEntry<Entries[K]> };
+export type TgpuLayoutEntry = TgpuLayoutUniform | TgpuLayoutStorage | TgpuLayoutSampler | TgpuLayoutComparisonSampler | TgpuLayoutTexture | TgpuLayoutStorageTexture | TgpuLayoutExternalTexture;
+type UnwrapRuntimeConstructorInner<T extends BaseData | ((_: number) => BaseData)> = T extends (_: number) => BaseData ? ReturnType<T> : T;
+export type UnwrapRuntimeConstructor<T extends BaseData | ((_: number) => BaseData)> = T extends unknown ? UnwrapRuntimeConstructorInner<T> : never;
+export interface TgpuBindGroupLayoutSoul extends TgpuSoul<'bind-group-layout'> {
+    readonly entries: Record<string, TgpuLayoutEntry | null>;
+    index?: number | undefined;
 }
-interface TgpuBindGroupLayout<Entries extends Record<string, TgpuLayoutEntry | null> = Record<string, TgpuLayoutEntry | null>> extends TgpuNamable {
-  readonly [$internal]: BindGroupLayoutInternals<Entries>;
-  readonly resourceType: 'bind-group-layout';
-  readonly entries: Entries;
-  /**
-   * @deprecated Use `layout.$.foo` instead of `layout.bound.foo.$`
-   */
-  readonly bound: { [K in keyof Entries]: BindLayoutEntry<Entries[K]> };
-  readonly [$gpuValueOf]: { [K in keyof Entries]: InferLayoutEntry<Entries[K]> };
-  /**
-   * @deprecated Use `.$` instead, works the same way.
-   */
-  readonly value: { [K in keyof Entries]: InferLayoutEntry<Entries[K]> };
-  readonly $: { [K in keyof Entries]: InferLayoutEntry<Entries[K]> };
-  /**
-   * An explicit numeric index assigned to this bind group layout. If undefined, a unique
-   * index is assigned automatically during resolution. This can be changed with the
-   * `.$idx()` method.
-   */
-  readonly index: number | undefined;
-  /**
-   * Associates this bind group layout with an explicit numeric index. When a call to this
-   * method is omitted, a unique numeric index is assigned to it automatically.
-   *
-   * Used when generating WGSL code: `@group(${index}) @binding(...) ...;`
-   */
-  $idx(index?: number): this;
-  /**
-   * 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;
+/**
+ * A residue soul: entries may hold runtime-local resources (texture views), so
+ * the soul holds the layout and the created bind group instead of the recipe.
+ * It is completed by `[$internal].materialize()`.
+ */
+export interface TgpuBindGroupSoul<Entries extends Record<string, TgpuLayoutEntry | null> = Record<string, TgpuLayoutEntry | null>> extends TgpuDeviceOwningSoul<'bind-group', GPUBindGroup> {
+    readonly layout: TgpuBindGroupLayout<Entries>;
+}
+export interface TgpuBindGroupLayout<Entries extends Record<string, TgpuLayoutEntry | null> = Record<string, TgpuLayoutEntry | null>> extends TgpuNamable {
+    readonly [$internal]: ResolvableObject[];
+    readonly [$soul]: TgpuBindGroupLayoutSoul;
+    readonly resourceType: 'bind-group-layout';
+    readonly entries: Entries;
+    readonly [$gpuValueOf]: {
+        [K in keyof Entries]: InferLayoutEntry<Entries[K]>;
+    };
+    readonly $: {
+        [K in keyof Entries]: InferLayoutEntry<Entries[K]>;
+    };
+    /**
+     * An explicit numeric index assigned to this bind group layout. If undefined, a unique
+     * index is assigned automatically during resolution. This can be changed with the
+     * `.$idx()` method.
+     */
+    readonly index: number | undefined;
+    /**
+     * Associates this bind group layout with an explicit numeric index. When a call to this
+     * method is omitted, a unique numeric index is assigned to it automatically.
+     *
+     * Used when generating WGSL code: `@group(${index}) @binding(...) ...;`
+     */
+    $idx(index?: number): this;
+    /**
+     * 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;
 }
-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> = TgpuLayoutEntry | null extends T ? TgpuBuffer<AnyWgslData> | GPUBuffer | TgpuSampler | GPUSampler | TgpuComparisonSampler | TgpuTexture | GPUTextureView | GPUExternalTexture : T extends TgpuLayoutUniform ? (TgpuBuffer<MemIdentity<UnwrapRuntimeConstructor<T['uniform']>>> & UniformFlag) | GPUBuffer : T extends TgpuLayoutStorage ? (TgpuBuffer<MemIdentity<UnwrapRuntimeConstructor<T['storage']>>> & StorageFlag) | GPUBuffer : T extends TgpuLayoutSampler ? TgpuSampler | GPUSampler : T extends TgpuLayoutComparisonSampler ? TgpuComparisonSampler | GPUSampler : T extends TgpuLayoutTexture ? GPUTextureView | GPUTexture | (SampledFlag & TgpuTexture<Prettify<PropsForSchema<T['texture']>>>) | TgpuTextureView<WgslTexture> : T extends TgpuLayoutStorageTexture ? GPUTextureView | GPUTexture | (StorageFlag & TgpuTexture<Prettify<PropsForSchema<T['storageTexture']>>>) | TgpuTextureView<WgslStorageTexture> : T extends TgpuLayoutExternalTexture ? GPUExternalTexture : never;
-type BindLayoutEntry<T extends TgpuLayoutEntry | null> = T extends TgpuLayoutUniform ? TgpuBufferUniform<T['uniform']> : T extends TgpuLayoutStorage ? StorageUsageForEntry<T> : T extends TgpuLayoutSampler ? TgpuSampler : T extends TgpuLayoutComparisonSampler ? TgpuComparisonSampler : T extends TgpuLayoutTexture<infer TSchema> ? TgpuTextureView<TSchema> : T extends TgpuLayoutStorageTexture<infer TSchema> ? TgpuTextureView<TSchema> : T extends TgpuLayoutExternalTexture ? TgpuExternalTexture : never;
-type InferLayoutEntry<T extends TgpuLayoutEntry | null> = T extends TgpuLayoutUniform ? InferGPU<T['uniform']> : T extends TgpuLayoutStorage ? InferGPU<UnwrapRuntimeConstructor<T['storage']>> : T extends TgpuLayoutSampler ? InferGPU<WgslSampler> : T extends TgpuLayoutComparisonSampler ? InferGPU<WgslComparisonSampler> : T extends TgpuLayoutTexture<infer TSchema> ? InferGPU<TSchema> : T extends TgpuLayoutStorageTexture<infer TSchema> ? InferGPU<TSchema> : T extends TgpuLayoutExternalTexture ? InferGPU<T['externalTexture']> : never;
-type ExtractBindGroupInputFromLayout<T extends Record<string, TgpuLayoutEntry | null>> = NullableToOptional<{ [K in keyof T]: LayoutEntryToInput<T[K]> }>;
-type TgpuBindGroup<Entries extends Record<string, TgpuLayoutEntry | null> = Record<string, TgpuLayoutEntry | null>> = {
-  readonly resourceType: 'bind-group';
-  readonly layout: TgpuBindGroupLayout<Entries>;
-  unwrap(unwrapper: Unwrapper): GPUBindGroup;
+export type LayoutEntryToInput<T extends TgpuLayoutEntry | null> = TgpuLayoutEntry | null extends T ? TgpuBuffer<BaseData> | TgpuBufferBinding<BaseData> | GPUBuffer | TgpuSampler | GPUSampler | TgpuComparisonSampler | TgpuTexture | GPUTextureView | GPUExternalTexture : T extends TgpuLayoutUniform ? (TgpuBuffer<MemIdentity<UnwrapRuntimeConstructor<T['uniform']>>> & UniformFlag) | TgpuUniform<MemIdentity<UnwrapRuntimeConstructor<T['uniform']>>> | GPUBuffer : T extends TgpuLayoutStorage ? (TgpuBuffer<MemIdentity<UnwrapRuntimeConstructor<T['storage']>>> & StorageFlag) | (T extends {
+    access: 'mutable';
+} ? TgpuMutable<MemIdentity<UnwrapRuntimeConstructor<T['storage']>>> : TgpuReadonly<MemIdentity<UnwrapRuntimeConstructor<T['storage']>>>) | GPUBuffer : T extends TgpuLayoutSampler ? TgpuSampler | GPUSampler : T extends TgpuLayoutComparisonSampler ? TgpuComparisonSampler | GPUSampler : T extends TgpuLayoutTexture ? GPUTextureView | GPUTexture | (SampledFlag & TgpuTexture<Prettify<PropsForSchema<T['texture']>>>) | TgpuTextureView<WgslTexture> : T extends TgpuLayoutStorageTexture ? GPUTextureView | GPUTexture | (StorageFlag & TgpuTexture<Prettify<PropsForSchema<T['storageTexture']>>>) | TgpuTextureView<WgslStorageTexture> : T extends TgpuLayoutExternalTexture ? GPUExternalTexture : never;
+export type InferLayoutEntry<T extends TgpuLayoutEntry | null> = T extends TgpuLayoutUniform ? InferGPU<T['uniform']> : T extends TgpuLayoutStorage ? InferGPU<UnwrapRuntimeConstructor<T['storage']>> : T extends TgpuLayoutSampler ? InferGPU<WgslSampler> : T extends TgpuLayoutComparisonSampler ? InferGPU<WgslComparisonSampler> : T extends TgpuLayoutTexture<infer TSchema> ? InferGPU<TSchema> : T extends TgpuLayoutStorageTexture<infer TSchema> ? InferGPU<TSchema> : T extends TgpuLayoutExternalTexture ? InferGPU<T['externalTexture']> : never;
+export type ExtractBindGroupInputFromLayout<T extends Record<string, TgpuLayoutEntry | null>> = NullableToOptional<{
+    [K in keyof T]: LayoutEntryToInput<T[K]>;
+}>;
+export type TgpuBindGroup<Entries extends Record<string, TgpuLayoutEntry | null> = Record<string, TgpuLayoutEntry | null>> = {
+    readonly [$internal]: {
+        readonly materialize: () => GPUBindGroup;
+    };
+    readonly [$soul]: TgpuBindGroupSoul<Entries>;
+    readonly resourceType: 'bind-group';
+    readonly layout: TgpuBindGroupLayout<Entries>;
+    unwrap(unwrapper: Unwrapper): GPUBindGroup;
 };
-declare function bindGroupLayout<Entries extends Record<string, TgpuLayoutEntry | null>>(entries: Entries): TgpuBindGroupLayout<Prettify<Entries>>;
+export declare function bindGroupLayout<Entries extends Record<string, TgpuLayoutEntry | null>>(entries: Entries): TgpuBindGroupLayout<Prettify<Entries>>;
+export declare function INTERNAL_restoreBindGroupLayout(soul: TgpuBindGroupLayoutSoul): TgpuBindGroupLayout;
+export declare function INTERNAL_restoreBindGroup(soul: TgpuBindGroupSoul, ctx: RestoreContext): TgpuBindGroup;
+export declare function isBindGroupLayout(value: unknown): value is TgpuBindGroupLayout;
+export declare function isBindGroup(value: unknown): value is TgpuBindGroup;
 /**
- * @deprecated Layouts containing the legacy texture api entries are deprecated and will be removed in future versions. Please use the up-to-date texture api entries instead.
+ * @category Errors
  */
-declare function bindGroupLayout<Entries extends Record<string, TgpuLegacyLayoutEntry | null>>(entries: Entries): TgpuBindGroupLayout<Prettify<MapLegacyTextureToUpToDate<Entries>>>;
-//#endregion
-export { BindLayoutEntry, ExtractBindGroupInputFromLayout, LayoutEntryToInput, TgpuBindGroup, TgpuBindGroupLayout, TgpuLayoutComparisonSampler, TgpuLayoutEntry, TgpuLayoutExternalTexture, TgpuLayoutSampler, TgpuLayoutStorage, TgpuLayoutTexture, TgpuLayoutUniform, UnwrapRuntimeConstructor, bindGroupLayout };
+export declare class MissingBindingError extends Error {
+    constructor(groupLabel: string | undefined, key: string);
+}
+export declare class TgpuBindGroupImpl<Entries extends Record<string, TgpuLayoutEntry | null> = Record<string, TgpuLayoutEntry | null>> implements TgpuBindGroup<Entries> {
+    #private;
+    readonly [$internal]: {
+        readonly materialize: () => GPUBindGroup;
+    };
+    readonly [$soul]: TgpuBindGroupSoul<Entries>;
+    readonly resourceType: "bind-group";
+    constructor(root: TgpuRoot | undefined, layout: TgpuBindGroupLayout<Entries>, entries: ExtractBindGroupInputFromLayout<Entries>, raw?: GPUBindGroup);
+    get layout(): TgpuBindGroupLayout<Entries>;
+    get entries(): ExtractBindGroupInputFromLayout<Entries>;
+    unwrap(unwrapper: Unwrapper): GPUBindGroup;
+}
+export {};