typegpu 0.10.1 → 0.11.0-rc.1

package/types.d.ts

@@ -0,0 +1,265 @@
+import { $cast, $gpuCallable, $internal } from "./shared/symbols.js";
+import { MapValueToSnippet, ResolvedSnippet, Snippet } from "./data/snippet.js";
+import { TgpuBufferUsage } from "./core/buffer/bufferUsage.js";
+import { SeparatedEntryArgs } from "./core/function/fnTypes.js";
+import { TgpuComputeFn } from "./core/function/tgpuComputeFn.js";
+import { TgpuVar } from "./core/variable/tgpuVariable.js";
+import { Eventual, SlotValuePair, TgpuAccessor, TgpuSlot } from "./core/slot/slotTypes.js";
+import { TgpuComputePipeline } from "./core/pipeline/computePipeline.js";
+import { TgpuFragmentFn } from "./core/function/tgpuFragmentFn.js";
+import { TgpuVertexFn } from "./core/function/tgpuVertexFn.js";
+import { TgpuRenderPipeline } from "./core/pipeline/renderPipeline.js";
+import { TgpuSampler } from "./core/sampler/sampler.js";
+import { TgpuExternalTexture } from "./core/texture/externalTexture.js";
+import { TgpuBindGroupLayout, TgpuLayoutEntry } from "./tgpuBindGroupLayout.js";
+import { ShaderGenerator } from "./tgsl/shaderGenerator.js";
+import { TgpuBuffer } from "./core/buffer/buffer.js";
+import { TgpuDeclare } from "./core/declare/tgpuDeclare.js";
+import { TgpuFn } from "./core/function/tgpuFn.js";
+import { WgslExtension } from "./wgslExtensions.js";
+import { AnyMatInstance, AnyVecInstance, BaseData } from "./data/wgslTypes.js";
+import { TgpuTexture, TgpuTextureView } from "./core/texture/texture.js";
+import { Infer } from "./shared/repr.js";
+import { AnyData, UnknownData } from "./data/dataTypes.js";
+import { TgpuConst } from "./core/constant/tgpuConstant.js";
+import { Block, FuncParameter } from "tinyest";
+
+//#region src/types.d.ts
+type ResolvableObject = SelfResolvable | TgpuBufferUsage | TgpuConst | TgpuDeclare | TgpuBindGroupLayout | TgpuFn | TgpuComputeFn | TgpuFragmentFn | TgpuComputePipeline | TgpuRenderPipeline | TgpuVertexFn | TgpuSampler | TgpuAccessor | TgpuExternalTexture | TgpuTexture | TgpuTextureView | TgpuVar | AnyVecInstance | AnyMatInstance | AnyData | ((...args: never[]) => unknown);
+type Wgsl = Eventual<string | number | boolean | ResolvableObject>;
+type TgpuShaderStage = 'compute' | 'vertex' | 'fragment';
+interface FnToWgslOptions {
+  functionType: 'normal' | TgpuShaderStage;
+  argTypes: BaseData[];
+  /**
+   * The return type of the function. If undefined, the type should be inferred
+   * from the implementation (relevant for shellless functions).
+   */
+  returnType: BaseData | undefined;
+  body: Block;
+  params: FuncParameter[];
+  externalMap: Record<string, unknown>;
+  /**
+   * For entry functions: positional args and optional data struct.
+   * When provided, takes precedence over `argTypes` for WGSL header generation.
+   */
+  entryInput?: SeparatedEntryArgs | undefined;
+}
+type ItemLayer = {
+  type: 'item';
+  usedSlots: Set<TgpuSlot<unknown>>;
+};
+type FunctionScopeLayer = {
+  type: 'functionScope';
+  functionType: 'normal' | 'compute' | 'vertex' | 'fragment';
+  args: Snippet[];
+  argAliases: Record<string, Snippet>;
+  externalMap: Record<string, unknown>;
+  /**
+   * The return type of the function. If undefined, the type should be inferred
+   * from the implementation (relevant for shellless functions).
+   */
+  returnType: BaseData | undefined;
+  /**
+   * All types used in `return` statements.
+   */
+  reportedReturnTypes: Set<BaseData>;
+};
+type SlotBindingLayer = {
+  type: 'slotBinding';
+  bindingMap: WeakMap<TgpuSlot<unknown>, unknown>;
+};
+type BlockScopeLayer = {
+  type: 'blockScope';
+  declarations: Map<string, Snippet>;
+  externals: Map<string, Snippet>;
+};
+type StackLayer = ItemLayer | SlotBindingLayer | FunctionScopeLayer | BlockScopeLayer;
+interface ItemStateStack {
+  readonly itemDepth: number;
+  readonly topItem: ItemLayer;
+  readonly topFunctionScope: FunctionScopeLayer | undefined;
+  pushItem(): void;
+  pushSlotBindings(pairs: SlotValuePair[]): void;
+  pushFunctionScope(functionType: 'normal' | TgpuShaderStage, args: Snippet[], argAliases: Record<string, Snippet>,
+  /**
+   * The return type of the function. If undefined, the type should be inferred
+   * from the implementation (relevant for shellless functions).
+   */
+
+  returnType: BaseData | undefined, externalMap: Record<string, unknown>): FunctionScopeLayer;
+  pushBlockScope(): void;
+  setBlockExternals(externals: Record<string, Snippet>): void;
+  clearBlockExternals(): void;
+  pop<T extends StackLayer['type']>(type: T): Extract<StackLayer, {
+    type: T;
+  }>;
+  pop(): StackLayer | undefined;
+  readSlot<T>(slot: TgpuSlot<T>): T | undefined;
+  getSnippetById(id: string): Snippet | undefined;
+  defineBlockVariable(id: string, snippet: Snippet): void;
+}
+/**
+ * # What are execution modes/states? 🤷
+ * They're used to control how each TypeGPU resource reacts
+ * to actions upon them.
+ *
+ * ## Normal mode
+ * This is the default mode, where resources are acted upon
+ * by code either:
+ * - Not wrapped inside any of our execution-altering APIs
+ * like tgpu.resolve or tgpu.simulate.
+ * - Inside tgpu.lazy definitions, where we're taking a break
+ *   from codegen/simulation to create resources on-demand.
+ *
+ * ```ts
+ * const count = tgpu.privateVar(d.f32);
+ * count.$ += 1; // Illegal in top-level
+ *
+ * const root = await tgpu.init();
+ * const countMutable = root.createMutable(d.f32);
+ * countMutable.$ = [1, 2, 3]; // Illegal in top-level
+ * countMutable.write([1, 2, 3]); // OK!
+ * ```
+ *
+ * ## Codegen mode
+ * Brought upon by `tgpu.resolve()` (or higher-level APIs using it like our pipelines).
+ * Resources are expected to generate WGSL code that represents them, instead of
+ * fulfilling their task in JS.
+ *
+ * ```ts
+ * const foo = tgpu.fn([], d.f32)(() => 123);
+ * // The following is running in `codegen` mode
+ * console.log(foo()); // Prints `foo_0()`
+ * ```
+ *
+ * ## Simulate mode
+ * Callbacks passed to `tgpu.simulate()` are executed in this mode. Each 'simulation'
+ * is isolated, and does not share state with other simulations (even nested ones).
+ * Variables and buffers can be accessed and mutated directly, and their state
+ * is returned at the end of the simulation.
+ *
+ * ```ts
+ * const var = tgpu.privateVar(d.f32, 0);
+ *
+ * const result = tgpu.simulate(() => {
+ *   // This is running in `simulate` mode
+ *   var.$ += 1; // Direct access is legal
+ *   return var.$; // Returns 1
+ * });
+ *
+ * console.log(result.value); // Prints 1
+ * ```
+ */
+type ExecMode = 'normal' | 'codegen' | 'simulate';
+declare class NormalState {
+  readonly type: "normal";
+}
+declare class CodegenState {
+  readonly type: "codegen";
+}
+declare class SimulationState {
+  readonly type: "simulate";
+  readonly buffers: Map<TgpuBuffer<BaseData>, unknown>;
+  readonly vars: {
+    private: Map<TgpuVar, unknown>;
+    workgroup: Map<TgpuVar, unknown>;
+  };
+  constructor(buffers: Map<TgpuBuffer<BaseData>, unknown>, vars: {
+    private: Map<TgpuVar, unknown>;
+    workgroup: Map<TgpuVar, unknown>;
+  });
+}
+type ExecState = NormalState | CodegenState | SimulationState;
+/**
+ * Passed into each resolvable item. All items in a tree share a resolution ctx,
+ * but there can be layers added and removed from the item stack when going down
+ * and up the tree.
+ */
+interface ResolutionCtx {
+  [$internal]: {
+    itemStateStack: ItemStateStack;
+  };
+  readonly mode: ExecState;
+  readonly enableExtensions: WgslExtension[] | undefined;
+  readonly gen: ShaderGenerator;
+  addDeclaration(declaration: string): void;
+  withResetIndentLevel<T>(callback: () => T): T;
+  /**
+   * Reserves a bind group number, and returns a placeholder that will be replaced
+   * with a concrete number at the end of the resolution process.
+   */
+  allocateLayoutEntry(layout: TgpuBindGroupLayout): string;
+  /**
+   * Reserves a spot in the catch-all bind group, without the indirection of a bind-group.
+   * This means the resource is 'fixed', and cannot be swapped between code execution.
+   */
+  allocateFixedEntry(layoutEntry: TgpuLayoutEntry, resource: object): {
+    group: string;
+    binding: number;
+  };
+  withSlots<T>(pairs: SlotValuePair[], callback: () => T): T;
+  pushMode(state: ExecState): void;
+  popMode(expected?: ExecMode): void;
+  /**
+   * Unwraps all layers of slot/lazy indirection and returns the concrete value if available.
+   * @throws {MissingSlotValueError}
+   */
+  unwrap<T>(eventual: Eventual<T>): T;
+  /**
+   * Returns the snippet representing `item`.
+   *
+   * @param item The value to resolve
+   * @param schema Additional information about the item's data type
+   */
+  resolve(item: unknown, schema?: BaseData | UnknownData): ResolvedSnippet;
+  /**
+   * Equivalent to `snip(ctx.resolve(snippet.value, snippet.dataType).value, snippet.dataType, snippet.origin)`.
+   */
+  resolveSnippet(snippet: Snippet): ResolvedSnippet;
+  fnToWgsl(options: FnToWgslOptions): {
+    head: Wgsl;
+    body: Wgsl;
+    returnType: BaseData;
+  };
+  withVaryingLocations<T>(locations: Record<string, number>, callback: () => T): T;
+  get varyingLocations(): Record<string, number> | undefined;
+  /**
+   * Temporarily renames the item.
+   * Useful for resolutions with slots,
+   * since functions with different slots should have different names,
+   * and all hold the same inner function that is being resolved multiple times.
+   * @param item the item to rename
+   * @param name the temporary name to assign to the item (if missing, just returns `callback()`)
+   */
+  withRenamed<T>(item: object, name: string | undefined, callback: () => T): T;
+  getUniqueName(resource: object): string;
+  makeNameValid(name: string): string;
+}
+/**
+ * Houses a method on the symbol '$resolve` that returns a
+ * code string representing it, as opposed to offloading the
+ * resolution to another mechanism.
+ */
+interface SelfResolvable {
+  [$internal]: unknown;
+  [$resolve](ctx: ResolutionCtx): ResolvedSnippet;
+  toString(): string;
+}
+interface GPUCallable<TArgs extends unknown[] = unknown[]> {
+  [$gpuCallable]: {
+    strictSignature?: {
+      argTypes: (BaseData | BaseData[])[];
+      returnType: BaseData;
+    } | undefined;
+    call(ctx: ResolutionCtx, args: MapValueToSnippet<TArgs>): Snippet;
+  };
+}
+type WithCast<T = BaseData> = GPUCallable<[v?: Infer<T>]> & {
+  readonly [$cast]: (v?: Infer<T>) => Infer<T>;
+};
+type AnyFn = (...args: never[]) => unknown;
+type DualFn<T extends AnyFn> = T & GPUCallable<Parameters<T>>;
+type BindableBufferUsage = 'uniform' | 'readonly' | 'mutable';
+//#endregion
+export { BindableBufferUsage, DualFn, FunctionScopeLayer, GPUCallable, ResolutionCtx, ResolvableObject, SelfResolvable, TgpuShaderStage, Wgsl, WithCast };

package/types.js

@@ -0,0 +1,43 @@
+import { $cast, $gpuCallable, $ownSnippet, $resolve } from "./shared/symbols.js";
+import { isWgslData } from "./data/wgslTypes.js";
+import { UnknownData } from "./data/dataTypes.js";
+import { isLazy, isProviding, isSlot } from "./core/slot/slotTypes.js";
+//#region src/types.ts
+var NormalState = class {
+	type = "normal";
+};
+var CodegenState = class {
+	type = "codegen";
+};
+var SimulationState = class {
+	type = "simulate";
+	buffers;
+	vars;
+	constructor(buffers, vars) {
+		this.buffers = buffers;
+		this.vars = vars;
+	}
+};
+function isSelfResolvable(value) {
+	return !!value?.[$resolve];
+}
+function getOwnSnippet(value) {
+	return value?.[$ownSnippet];
+}
+function isGPUCallable(value) {
+	return !!value?.[$gpuCallable];
+}
+function hasCast(value) {
+	return !!value?.[$cast];
+}
+function isKnownAtComptime(snippet) {
+	return (typeof snippet.value !== "string" || snippet.dataType === UnknownData) && getOwnSnippet(snippet.value) === void 0;
+}
+function isWgsl(value) {
+	return typeof value === "number" || typeof value === "boolean" || typeof value === "string" || isSelfResolvable(value) || isWgslData(value) || isSlot(value) || isLazy(value) || isProviding(value);
+}
+function isGPUBuffer(value) {
+	return !!value && typeof value === "object" && "getMappedRange" in value && "mapAsync" in value;
+}
+//#endregion
+export { CodegenState, NormalState, SimulationState, getOwnSnippet, hasCast, isGPUBuffer, isGPUCallable, isKnownAtComptime, isSelfResolvable, isWgsl };

package/unwrapper.d.ts

@@ -0,0 +1,27 @@
+import { TgpuQuerySet } from "./core/querySet/querySet.js";
+import { TgpuComputePipeline } from "./core/pipeline/computePipeline.js";
+import { TgpuVertexLayout } from "./core/vertexLayout/vertexLayout.js";
+import { TgpuRenderPipeline } from "./core/pipeline/renderPipeline.js";
+import { TgpuComparisonSampler, TgpuSampler } from "./core/sampler/sampler.js";
+import { TgpuBindGroup, TgpuBindGroupLayout } from "./tgpuBindGroupLayout.js";
+import { TgpuBuffer } from "./core/buffer/buffer.js";
+import { BaseData } from "./data/wgslTypes.js";
+import { TgpuTexture, TgpuTextureView } from "./core/texture/texture.js";
+
+//#region src/unwrapper.d.ts
+interface Unwrapper {
+  readonly device: GPUDevice;
+  unwrap(resource: TgpuComputePipeline): GPUComputePipeline;
+  unwrap(resource: TgpuRenderPipeline): GPURenderPipeline;
+  unwrap(resource: TgpuBindGroupLayout): GPUBindGroupLayout;
+  unwrap(resource: TgpuBindGroup): GPUBindGroup;
+  unwrap(resource: TgpuBuffer<BaseData>): GPUBuffer;
+  unwrap(resource: TgpuTextureView): GPUTextureView;
+  unwrap(resource: TgpuVertexLayout): GPUVertexBufferLayout;
+  unwrap(resource: TgpuSampler): GPUSampler;
+  unwrap(resource: TgpuComparisonSampler): GPUSampler;
+  unwrap(resource: TgpuQuerySet<GPUQueryType>): GPUQuerySet;
+  unwrap(resource: TgpuTexture): GPUTexture;
+}
+//#endregion
+export { Unwrapper };

package/wgslExtensions.d.ts

@@ -0,0 +1,5 @@
+//#region src/wgslExtensions.d.ts
+declare const wgslExtensions: readonly ["f16", "clip_distances", "dual_source_blending", "subgroups", "primitive_index"];
+type WgslExtension = (typeof wgslExtensions)[number];
+//#endregion
+export { WgslExtension };

package/wgslExtensions.js

@@ -0,0 +1,17 @@
+//#region src/wgslExtensions.ts
+const wgslExtensions = [
+	"f16",
+	"clip_distances",
+	"dual_source_blending",
+	"subgroups",
+	"primitive_index"
+];
+const wgslExtensionToFeatureName = {
+	f16: "shader-f16",
+	clip_distances: "clip-distances",
+	dual_source_blending: "dual-source-blending",
+	subgroups: "subgroups",
+	primitive_index: "primitive-index"
+};
+//#endregion
+export { wgslExtensionToFeatureName, wgslExtensions };