🎁: Add an alternate slot-value propagation mechanism, allowing for slot values to pass through a derived boundary (#697)

* Improved error reporting for missing bind groups and vertex buffers

Author: iwoplaza

packages/typegpu/src/core/function/tgpuFn.ts

@@ -12,6 +12,8 @@ import type {
 import type { TgpuBufferUsage } from '../buffer/bufferUsage';
 import {
   type Eventual,
+  type Providing,
+  type SlotValuePair,
   type TgpuAccessor,
   type TgpuSlot,
   isAccessor,
@@ -56,6 +58,7 @@ interface TgpuFnBase<
     Labelled {
   readonly resourceType: 'function';
   readonly shell: TgpuFnShell<Args, Return>;
+  readonly '~providing'?: Providing | undefined;
 
   $uses(dependencyMap: Record<string, unknown>): this;
   with<T>(slot: TgpuSlot<T>, value: Eventual<T>): TgpuFn<Args, Return>;
@@ -108,6 +111,10 @@ export function isTgpuFn<
 // Implementation
 // --------------
 
+function stringifyPair([slot, value]: SlotValuePair): string {
+  return `${slot.label ?? '<unnamed>'}=${value}`;
+}
+
 function createFn<
   Args extends AnyWgslData[],
   Return extends AnyWgslData | undefined,
@@ -137,11 +144,9 @@ function createFn<
       slot: TgpuSlot<T> | TgpuAccessor<T>,
       value: T | TgpuFn<[], T> | TgpuBufferUsage<T> | Infer<T>,
     ): TgpuFn<Args, Return> {
-      return createBoundFunction(
-        fn,
-        isAccessor(slot) ? slot.slot : slot,
-        value,
-      );
+      return createBoundFunction(fn, [
+        [isAccessor(slot) ? slot.slot : slot, value],
+      ]);
     },
 
     '~resolve'(ctx: ResolutionCtx): string {
@@ -181,16 +186,16 @@ function createFn<
 function createBoundFunction<
   Args extends AnyWgslData[],
   Return extends AnyWgslData | undefined,
->(
-  innerFn: TgpuFn<Args, Return>,
-  slot: TgpuSlot<unknown>,
-  slotValue: unknown,
-): TgpuFn<Args, Return> {
-  type This = TgpuFnBase<Args, Return> & SelfResolvable;
+>(innerFn: TgpuFn<Args, Return>, pairs: SlotValuePair[]): TgpuFn<Args, Return> {
+  type This = TgpuFnBase<Args, Return>;
 
   const fnBase: This = {
     resourceType: 'function',
     shell: innerFn.shell,
+    '~providing': {
+      inner: innerFn,
+      pairs,
+    },
 
     $uses(newExternals) {
       innerFn.$uses(newExternals);
@@ -206,15 +211,10 @@ function createBoundFunction<
       slot: TgpuSlot<T> | TgpuAccessor<T>,
       value: T | TgpuFn<[], T> | TgpuBufferUsage<T> | Infer<T>,
     ): TgpuFn<Args, Return> {
-      return createBoundFunction(
-        fn,
-        isAccessor(slot) ? slot.slot : slot,
-        value,
-      );
-    },
-
-    '~resolve'(ctx: ResolutionCtx): string {
-      return ctx.withSlots([[slot, slotValue]], () => ctx.resolve(innerFn));
+      return createBoundFunction(fn, [
+        ...pairs,
+        [isAccessor(slot) ? slot.slot : slot, value],
+      ]);
     },
   };
 
@@ -236,7 +236,9 @@ function createBoundFunction<
 
   Object.defineProperty(fn, 'toString', {
     value() {
-      return `fn:${innerFn.label ?? '<unnamed>'}[${slot.label ?? '<unnamed>'}=${slotValue}]`;
+      const fnLabel = innerFn.label ?? '<unnamed>';
+
+      return `fn:${fnLabel}[${pairs.map(stringifyPair).join(', ')}]`;
     },
   });
 

packages/typegpu/src/core/pipeline/computePipeline.ts

@@ -1,4 +1,4 @@
-import { MissingBindGroupError } from '../../errors';
+import { MissingBindGroupsError } from '../../errors';
 import type { TgpuNamable } from '../../namable';
 import { resolve } from '../../resolutionCtx';
 import type {
@@ -100,26 +100,34 @@ class TgpuComputePipelineImpl
     z?: number | undefined,
   ): void {
     const memo = this._core.unwrap();
+    const { branch, label } = this._core;
 
-    const pass = this._core.branch.commandEncoder.beginComputePass({
-      label: this._core.label ?? '<unnamed>',
+    const pass = branch.commandEncoder.beginComputePass({
+      label: label ?? '<unnamed>',
     });
 
     pass.setPipeline(memo.pipeline);
 
+    const missingBindGroups = new Set(memo.bindGroupLayouts);
+
     memo.bindGroupLayouts.forEach((layout, idx) => {
       if (memo.catchall && idx === memo.catchall[0]) {
         // Catch-all
-        pass.setBindGroup(idx, this._core.branch.unwrap(memo.catchall[1]));
+        pass.setBindGroup(idx, branch.unwrap(memo.catchall[1]));
+        missingBindGroups.delete(layout);
       } else {
         const bindGroup = this._priors.bindGroupLayoutMap?.get(layout);
-        if (bindGroup === undefined) {
-          throw new MissingBindGroupError(layout.label);
+        if (bindGroup !== undefined) {
+          missingBindGroups.delete(layout);
+          pass.setBindGroup(idx, branch.unwrap(bindGroup));
         }
-        pass.setBindGroup(idx, this._core.branch.unwrap(bindGroup));
       }
     });
 
+    if (missingBindGroups.size > 0) {
+      throw new MissingBindGroupsError(missingBindGroups);
+    }
+
     pass.dispatchWorkgroups(x, y, z);
     pass.end();
   }

packages/typegpu/src/core/pipeline/renderPipeline.ts

@@ -1,7 +1,10 @@
 import type { TgpuBuffer, Vertex } from '../../core/buffer/buffer';
 import type { Disarray } from '../../data/dataTypes';
 import type { AnyWgslData, WgslArray } from '../../data/wgslTypes';
-import { MissingBindGroupError } from '../../errors';
+import {
+  MissingBindGroupsError,
+  MissingVertexBuffersError,
+} from '../../errors';
 import type { TgpuNamable } from '../../namable';
 import { resolve } from '../../resolutionCtx';
 import type { AnyVertexAttribs } from '../../shared/vertexFormat';
@@ -48,6 +51,10 @@ export interface TgpuRenderPipeline<Output extends IOLayout = IOLayout>
     attachment: FragmentOutToColorAttachment<Output>,
   ): TgpuRenderPipeline<IOLayout>;
 
+  withDepthStencilAttachment(
+    attachment: DepthStencilAttachment,
+  ): TgpuRenderPipeline<IOLayout>;
+
   draw(
     vertexCount: number,
     instanceCount?: number,
@@ -111,6 +118,60 @@ export interface ColorAttachment {
   storeOp: GPUStoreOp;
 }
 
+export interface DepthStencilAttachment {
+  /**
+   * A {@link GPUTextureView} | ({@link TgpuTexture} & {@link Render}) describing the texture subresource that will be output to
+   * and read from for this depth/stencil attachment.
+   */
+  view: (TgpuTexture & Render) | GPUTextureView;
+  /**
+   * Indicates the value to clear {@link GPURenderPassDepthStencilAttachment#view}'s depth component
+   * to prior to executing the render pass. Ignored if {@link GPURenderPassDepthStencilAttachment#depthLoadOp}
+   * is not {@link GPULoadOp#"clear"}. Must be between 0.0 and 1.0, inclusive (unless unrestricted depth is enabled).
+   */
+  depthClearValue?: number;
+  /**
+   * Indicates the load operation to perform on {@link GPURenderPassDepthStencilAttachment#view}'s
+   * depth component prior to executing the render pass.
+   * Note: It is recommended to prefer clearing; see {@link GPULoadOp#"clear"} for details.
+   */
+  depthLoadOp?: GPULoadOp;
+  /**
+   * The store operation to perform on {@link GPURenderPassDepthStencilAttachment#view}'s
+   * depth component after executing the render pass.
+   */
+  depthStoreOp?: GPUStoreOp;
+  /**
+   * Indicates that the depth component of {@link GPURenderPassDepthStencilAttachment#view}
+   * is read only.
+   */
+  depthReadOnly?: boolean;
+  /**
+   * Indicates the value to clear {@link GPURenderPassDepthStencilAttachment#view}'s stencil component
+   * to prior to executing the render pass. Ignored if {@link GPURenderPassDepthStencilAttachment#stencilLoadOp}
+   * is not {@link GPULoadOp#"clear"}.
+   * The value will be converted to the type of the stencil aspect of `view` by taking the same
+   * number of LSBs as the number of bits in the stencil aspect of one texel block|texel of `view`.
+   */
+  stencilClearValue?: GPUStencilValue;
+  /**
+   * Indicates the load operation to perform on {@link GPURenderPassDepthStencilAttachment#view}'s
+   * stencil component prior to executing the render pass.
+   * Note: It is recommended to prefer clearing; see {@link GPULoadOp#"clear"} for details.
+   */
+  stencilLoadOp?: GPULoadOp;
+  /**
+   * The store operation to perform on {@link GPURenderPassDepthStencilAttachment#view}'s
+   * stencil component after executing the render pass.
+   */
+  stencilStoreOp?: GPUStoreOp;
+  /**
+   * Indicates that the stencil component of {@link GPURenderPassDepthStencilAttachment#view}
+   * is read only.
+   */
+  stencilReadOnly?: boolean;
+}
+
 export type AnyFragmentColorAttachment =
   | ColorAttachment
   | Record<string, ColorAttachment>;
@@ -122,6 +183,7 @@ export type RenderPipelineCoreOptions = {
   vertexFn: TgpuVertexFn;
   fragmentFn: TgpuFragmentFn;
   primitiveState: GPUPrimitiveState | undefined;
+  depthStencilState: GPUDepthStencilState | undefined;
   targets: AnyFragmentTargets;
 };
 
@@ -143,6 +205,7 @@ type TgpuRenderPipelinePriors = {
     | Map<TgpuBindGroupLayout, TgpuBindGroup>
     | undefined;
   readonly colorAttachment?: AnyFragmentColorAttachment | undefined;
+  readonly depthStencilAttachment?: DepthStencilAttachment | undefined;
 };
 
 type Memo = {
@@ -212,6 +275,15 @@ class TgpuRenderPipelineImpl implements TgpuRenderPipeline {
     });
   }
 
+  withDepthStencilAttachment(
+    attachment: DepthStencilAttachment,
+  ): TgpuRenderPipeline {
+    return new TgpuRenderPipelineImpl(this._core, {
+      ...this._priors,
+      depthStencilAttachment: attachment,
+    });
+  }
+
   draw(
     vertexCount: number,
     instanceCount?: number,
@@ -235,37 +307,68 @@ class TgpuRenderPipelineImpl implements TgpuRenderPipeline {
       return attachment;
     }) as GPURenderPassColorAttachment[];
 
-    const pass = branch.commandEncoder.beginRenderPass({
-      label: this._core.label ?? '<unnamed>',
+    const renderPassDescriptor: GPURenderPassDescriptor = {
       colorAttachments,
-    });
+    };
+
+    if (this._core.label !== undefined) {
+      renderPassDescriptor.label = this._core.label;
+    }
+
+    if (this._priors.depthStencilAttachment !== undefined) {
+      const attachment = this._priors.depthStencilAttachment;
+      if (isTexture(attachment.view)) {
+        renderPassDescriptor.depthStencilAttachment = {
+          ...attachment,
+          view: branch.unwrap(attachment.view).createView(),
+        };
+      } else {
+        renderPassDescriptor.depthStencilAttachment =
+          attachment as GPURenderPassDepthStencilAttachment;
+      }
+    }
+
+    const pass = branch.commandEncoder.beginRenderPass(renderPassDescriptor);
 
     pass.setPipeline(memo.pipeline);
 
+    const missingBindGroups = new Set(memo.bindGroupLayouts);
+
     memo.bindGroupLayouts.forEach((layout, idx) => {
       if (memo.catchall && idx === memo.catchall[0]) {
         // Catch-all
         pass.setBindGroup(idx, branch.unwrap(memo.catchall[1]));
+        missingBindGroups.delete(layout);
       } else {
         const bindGroup = this._priors.bindGroupLayoutMap?.get(layout);
-        if (bindGroup === undefined) {
-          throw new MissingBindGroupError(layout.label);
+        if (bindGroup !== undefined) {
+          missingBindGroups.delete(layout);
+          pass.setBindGroup(idx, branch.unwrap(bindGroup));
         }
-        pass.setBindGroup(idx, branch.unwrap(bindGroup));
       }
     });
 
-    this._core.usedVertexLayouts.forEach((vertexLayout, idx) => {
+    const missingVertexLayouts = new Set(this._core.usedVertexLayouts);
+
+    const usedVertexLayouts = this._core.usedVertexLayouts;
+    usedVertexLayouts.forEach((vertexLayout, idx) => {
       const buffer = this._priors.vertexLayoutMap?.get(vertexLayout);
-      if (!buffer) {
-        throw new Error(
-          `Missing vertex buffer for layout '${vertexLayout.label ?? '<unnamed>'}'. Please provide it using pipeline.with(layout, buffer).(...)`,
-        );
+      if (buffer) {
+        missingVertexLayouts.delete(vertexLayout);
+        pass.setVertexBuffer(idx, branch.unwrap(buffer));
       }
-      pass.setVertexBuffer(idx, branch.unwrap(buffer));
     });
 
+    if (missingBindGroups.size > 0) {
+      throw new MissingBindGroupsError(missingBindGroups);
+    }
+
+    if (missingVertexLayouts.size > 0) {
+      throw new MissingVertexBuffersError(missingVertexLayouts);
+    }
+
     pass.draw(vertexCount, instanceCount, firstVertex, firstInstance);
+
     pass.end();
   }
 }
@@ -295,8 +398,14 @@ class RenderPipelineCore {
 
   public unwrap(): Memo {
     if (this._memo === undefined) {
-      const { branch, vertexFn, fragmentFn, slotBindings, primitiveState } =
-        this.options;
+      const {
+        branch,
+        vertexFn,
+        fragmentFn,
+        slotBindings,
+        primitiveState,
+        depthStencilState,
+      } = this.options;
 
       // Resolving code
       const { code, bindGroupLayouts, catchall } = resolve(
@@ -353,6 +462,10 @@ class RenderPipelineCore {
         descriptor.primitive = primitiveState;
       }
 
+      if (depthStencilState) {
+        descriptor.depthStencil = depthStencilState;
+      }
+
       this._memo = {
         pipeline: device.createRenderPipeline(descriptor),
         bindGroupLayouts,

packages/typegpu/src/core/root/init.ts

@@ -103,6 +103,7 @@ class WithBindingImpl implements WithBinding {
     return new WithVertexImpl({
       branch: this._getRoot(),
       primitiveState: undefined,
+      depthStencilState: undefined,
       slotBindings: this._slotBindings,
       vertexFn,
       vertexAttribs: attribs as AnyVertexAttribs,
@@ -157,6 +158,12 @@ class WithFragmentImpl implements WithFragment {
     return new WithFragmentImpl({ ...this._options, primitiveState });
   }
 
+  withDepthStencil(
+    depthStencilState: GPUDepthStencilState | undefined,
+  ): WithFragment {
+    return new WithFragmentImpl({ ...this._options, depthStencilState });
+  }
+
   createPipeline(): TgpuRenderPipeline {
     return INTERNAL_createRenderPipeline(this._options);
   }