@forgeax/engine-runtime 0.1.2

package/src/__tests__/dispatch-fullscreen-pass-composite-swapchain.dawn.test.ts

@@ -0,0 +1,204 @@
+// dispatch-fullscreen-pass-composite-swapchain.dawn.test.ts -
+// feat-20260621-learn-render-5-3-production-shadow-demos M4' (post-URP hook).
+//
+// Spy/mock unit-style tests for dispatchFullscreenPass's compositeOverSwapchain
+// branch -- the generalisation of the built-in FXAA copy idiom that lets a
+// built-in pipeline layer a registered effect over its FINAL swap-chain image
+// WITHOUT replacing the pipeline (and dropping its shadow / tonemap passes).
+//
+// The branch must:
+//   (a) copy the current swap-chain (ctx.currentTexture) into the `color`
+//       scratch texture (resolved via `${color}::tex`) BEFORE sampling, so the
+//       effect reads the already-composited image.
+//   (b) feed the scratch's TextureView (resolved via `${color}`) into the bind
+//       group input -- NOT ctx.view.
+//   (c) write through the swap-chain NON-srgb storage view
+//       (device.createTextureView(ctx.currentTexture)) -- R-COLORSPACE: the
+//       scratch holds an already-sRGB-encoded copy, so the srgb view would
+//       double-encode (mirrors recordFxaaPass).
+//   (d) throw PostProcessError{fullscreen-input-not-found} when the scratch
+//       texture is unresolved (charter P3 fail-fast), before any encoder call.
+
+import type { RenderPipelineContext } from '@forgeax/engine-render/internal';
+import { addFullscreenPass } from '@forgeax/engine-render/internal';
+import { RenderGraph } from '@forgeax/engine-render-graph';
+import { describe, expect, it } from 'vitest';
+
+interface BindGroupEntry {
+  readonly binding: number;
+  readonly resource: { readonly kind: string; readonly value: unknown };
+}
+
+interface CopyCall {
+  readonly src: unknown;
+  readonly dst: unknown;
+}
+
+interface Spy {
+  readonly bindGroupCreates: { readonly entries: readonly BindGroupEntry[] }[];
+  readonly beginRenderPassCalls: { readonly view: unknown }[];
+  readonly copyCalls: CopyCall[];
+  readonly createdViewsFrom: unknown[];
+  drawCalls: number;
+}
+
+type ExecuteWithResolve = (c: unknown, r: { resolve: (n: string) => unknown }) => void;
+
+function findPassExecute(
+  graph: RenderGraph<RenderPipelineContext>,
+  passName: string,
+): ExecuteWithResolve | undefined {
+  const passes = (
+    graph as unknown as {
+      passes: {
+        list(): readonly { name: string; descriptor: { execute?: ExecuteWithResolve } }[];
+      };
+    }
+  ).passes.list();
+  return passes.find((p) => p.name === passName)?.descriptor.execute;
+}
+
+function makeSpyCtx(opts: {
+  lookup: (id: string) => { source: string } | undefined;
+  currentTexture: unknown;
+  storageView: unknown;
+}): { ctx: RenderPipelineContext; spy: Spy } {
+  const spy: Spy = {
+    bindGroupCreates: [],
+    beginRenderPassCalls: [],
+    copyCalls: [],
+    createdViewsFrom: [],
+    drawCalls: 0,
+  };
+
+  const passEncoder = {
+    setPipeline(_p: unknown): void {},
+    setBindGroup(_slot: number, _bg: unknown): void {},
+    draw(): void {
+      spy.drawCalls += 1;
+    },
+    end(): void {},
+  };
+
+  const ctx = {
+    runtime: {
+      lookupPostProcess: opts.lookup,
+      getPostProcessPipeline: (_id: string, _bgl: unknown, _format: string) => ({
+        __pipeline: true,
+      }),
+      device: {
+        createBindGroupLayout: (_d: unknown) => ({ ok: true, value: { __bgl: true } }),
+        createSampler: (_d: unknown) => ({ ok: true, value: { __sampler: true } }),
+        createBindGroup: (desc: { readonly entries: readonly BindGroupEntry[] }) => {
+          spy.bindGroupCreates.push({ entries: desc.entries });
+          return { ok: true, value: { __bg: true } };
+        },
+        createTextureView: (tex: unknown, _d: unknown) => {
+          spy.createdViewsFrom.push(tex);
+          return { ok: true, value: opts.storageView };
+        },
+      },
+      errorRegistry: { fire: (_e: unknown) => undefined },
+    },
+    pipelineState: { format: 'bgra8unorm', colorAttachmentFormat: 'bgra8unorm-srgb' },
+    currentTexture: opts.currentTexture,
+    targetW: 64,
+    targetH: 64,
+    view: { __swapchainSrgbView: true },
+    encoder: {
+      copyTextureToTexture: (src: { texture: unknown }, dst: { texture: unknown }) => {
+        spy.copyCalls.push({ src: src.texture, dst: dst.texture });
+      },
+      beginRenderPass: (desc: { colorAttachments: readonly { view: unknown }[] }) => {
+        spy.beginRenderPassCalls.push({ view: desc.colorAttachments[0]?.view });
+        return passEncoder;
+      },
+    },
+  } as unknown as RenderPipelineContext;
+  return { ctx, spy };
+}
+
+describe('feat-20260621 M4′: dispatchFullscreenPass compositeOverSwapchain', () => {
+  it('(a)(b)(c) copies swap-chain -> scratch, samples scratch view, writes swap-chain storage view', () => {
+    const swapTex = { __swapTexture: true };
+    const scratchTex = { __scratchTex: true };
+    const scratchView = { __scratchView: true };
+    const storageView = { __nonSrgbStorageView: true };
+    const { ctx, spy } = makeSpyCtx({
+      lookup: () => ({ source: 'fn vs_main(){} fn fs_main(){}' }),
+      currentTexture: swapTex,
+      storageView,
+    });
+    const graph = new RenderGraph<RenderPipelineContext>();
+    graph.addColorTarget('scratch', { format: 'bgra8unorm', size: { w: 64, h: 64 } });
+    addFullscreenPass(graph, 'post-effect-0', {
+      shader: 'test::composite',
+      color: 'scratch',
+      compositeOverSwapchain: true,
+    });
+
+    const execute = findPassExecute(graph, 'post-effect-0');
+    expect(execute).toBeDefined();
+    if (!execute) return;
+
+    const resolveCtx = {
+      resolve: (n: string) =>
+        n === 'scratch::tex' ? scratchTex : n === 'scratch' ? scratchView : undefined,
+    };
+    execute(ctx, resolveCtx);
+
+    // (a) copy swap-chain -> scratch fired exactly once, src=swapTex dst=scratchTex.
+    expect(spy.copyCalls.length).toBe(1);
+    expect(spy.copyCalls[0]?.src).toBe(swapTex);
+    expect(spy.copyCalls[0]?.dst).toBe(scratchTex);
+
+    // (b) bind-group input texture = the scratch view (the copied final image),
+    // NOT ctx.view.
+    const tvEntry = spy.bindGroupCreates[0]?.entries.find((e) => e.resource.kind === 'textureView');
+    expect(tvEntry?.resource.value).toBe(scratchView);
+
+    // (c) write target = the swap-chain non-srgb storage view, created from
+    // ctx.currentTexture (R-COLORSPACE), not the srgb ctx.view.
+    expect(spy.createdViewsFrom).toContain(swapTex);
+    expect(spy.beginRenderPassCalls[0]?.view).toBe(storageView);
+
+    // fullscreen draw fired.
+    expect(spy.drawCalls).toBe(1);
+  });
+
+  it('(d) unresolved scratch texture -> throws fullscreen-input-not-found before any encoder call', () => {
+    const { ctx, spy } = makeSpyCtx({
+      lookup: () => ({ source: 'fn vs_main(){} fn fs_main(){}' }),
+      currentTexture: { __swapTexture: true },
+      storageView: { __storage: true },
+    });
+    const graph = new RenderGraph<RenderPipelineContext>();
+    graph.addColorTarget('scratch', { format: 'bgra8unorm', size: { w: 64, h: 64 } });
+    addFullscreenPass(graph, 'post-effect-0', {
+      shader: 'test::composite-throw',
+      color: 'scratch',
+      compositeOverSwapchain: true,
+    });
+
+    const execute = findPassExecute(graph, 'post-effect-0');
+    if (!execute) return;
+
+    // resolveCtx returns undefined for scratch::tex (not yet compiled) -> throw.
+    const resolveCtx = { resolve: (_n: string) => undefined };
+    let caught: unknown = null;
+    try {
+      execute(ctx, resolveCtx);
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).not.toBeNull();
+    const err = caught as { code?: string; detail?: { readsKey?: string; passName?: string } };
+    expect(err.code).toBe('fullscreen-input-not-found');
+    expect(err.detail?.readsKey).toBe('scratch');
+    expect(err.detail?.passName).toBe('post-effect-0');
+
+    // Fail-fast: no copy, no render pass before the throw.
+    expect(spy.copyCalls.length).toBe(0);
+    expect(spy.beginRenderPassCalls.length).toBe(0);
+  });
+});

package/src/__tests__/dispatch-fullscreen-pass-custom-reads.dawn.test.ts

@@ -0,0 +1,297 @@
+// dispatch-fullscreen-pass-custom-reads.dawn.test.ts -
+// feat-20260609-learn-render-4-5-framebuffers-demo-offscreen-rt-an M1 / T-4.
+//
+// Spy/mock unit-style integration tests for dispatchFullscreenPass's generic
+// (non-FXAA) branch. The test bypasses real GPU pipeline build by spying on
+// the per-frame encoder; the dispatcher's structural call chain is validated:
+//
+//   (a) reads[0] resolves through the per-pass resolveCtx -> graph-owned
+//       TextureView; the dispatcher passes that resolved view into
+//       createFullscreenBindGroup (verified via spy on the bind-group
+//       textureView entry).
+//   (b) On the success path the dispatcher opens a render pass on
+//       ctx.encoder, calls pass.setBindGroup(1, bg), then handle.draw(pass)
+//       which internally does pass.setPipeline + pass.draw(3, 1, 0, 0).
+//   (c) When reads[0] is non-empty but resolveCtx returns undefined for the
+//       key (mis-spelled / un-declared color target), the dispatcher throws
+//       PostProcessError({code:'fullscreen-input-not-found',
+//       detail:{readsKey, passName}}) before any encoder call -- charter P3
+//       fail-fast.
+//   (d) reads === [] preserves the legacy ctx.view swap-chain path; the
+//       dispatcher samples ctx.view (no resolveCtx invocation for any key).
+//
+// File lives under .dawn.test.ts naming (per plan-decisions L-3) so the
+// dawn vitest project picks it up; a Node-only environment would also work
+// (no real GPU calls fire), but the dawn project is the canonical home for
+// per-frame-execute integration tests.
+
+import type { RenderPipelineContext } from '@forgeax/engine-render/internal';
+import { addFullscreenPass } from '@forgeax/engine-render/internal';
+import { RenderGraph } from '@forgeax/engine-render-graph';
+import { describe, expect, it } from 'vitest';
+
+interface BindGroupEntry {
+  readonly binding: number;
+  readonly resource: { readonly kind: string; readonly value: unknown };
+}
+
+interface BindGroupCall {
+  readonly slot: number;
+  readonly bindGroup: unknown;
+}
+
+interface DrawCall {
+  readonly vertexCount: number;
+  readonly instanceCount: number;
+  readonly firstVertex: number;
+  readonly firstInstance: number;
+}
+
+interface DispatchSpy {
+  readonly bindGroupCreates: { readonly entries: readonly BindGroupEntry[] }[];
+  readonly setBindGroupCalls: BindGroupCall[];
+  readonly setPipelineCalls: unknown[];
+  readonly drawCalls: DrawCall[];
+  readonly beginRenderPassCalls: { readonly view: unknown }[];
+}
+
+type ExecuteWithResolve = (c: unknown, r: { resolve: (n: string) => unknown }) => void;
+
+function findPassExecute(
+  graph: RenderGraph<RenderPipelineContext>,
+  passName: string,
+): ExecuteWithResolve | undefined {
+  // Reach into the package-private pass registry to recover descriptor.execute
+  // (mirrors post-process-register-roundtrip.dawn.test.ts pattern; the public
+  // RenderGraph surfaces only listPasses with name/reads/writes -- the executor
+  // body lives on the PassEntry).
+  const passes = (
+    graph as unknown as {
+      passes: {
+        list(): readonly {
+          name: string;
+          descriptor: { execute?: ExecuteWithResolve };
+        }[];
+      };
+    }
+  ).passes.list();
+  return passes.find((p) => p.name === passName)?.descriptor.execute;
+}
+
+function makeSpyCtx(opts: {
+  lookup: (id: string) => { source: string } | undefined;
+  view: unknown;
+}): { ctx: RenderPipelineContext; spy: DispatchSpy } {
+  const spy: DispatchSpy = {
+    bindGroupCreates: [],
+    setBindGroupCalls: [],
+    setPipelineCalls: [],
+    drawCalls: [],
+    beginRenderPassCalls: [],
+  };
+
+  const passEncoder = {
+    setPipeline(p: unknown): void {
+      spy.setPipelineCalls.push(p);
+    },
+    setBindGroup(slot: number, bg: unknown): void {
+      spy.setBindGroupCalls.push({ slot, bindGroup: bg });
+    },
+    draw(
+      vertexCount: number,
+      instanceCount: number,
+      firstVertex: number,
+      firstInstance: number,
+    ): void {
+      spy.drawCalls.push({ vertexCount, instanceCount, firstVertex, firstInstance });
+    },
+    end(): void {},
+  };
+
+  const ctx = {
+    runtime: {
+      lookupPostProcess: opts.lookup,
+      // T-10-a: dispatcher now reads runtime.getPostProcessPipeline; spy
+      // returns a stub pipeline so the success-path tests reach
+      // beginRenderPass / setBindGroup / setPipeline / draw. The stub object
+      // is opaque to the dispatcher (it forwards to setPipeline as-is).
+      getPostProcessPipeline: (_id: string, _bgl: unknown, _format: string) => ({
+        __pipeline: true,
+      }),
+      device: {
+        createBindGroupLayout: (_d: unknown) => ({ ok: true, value: { __bgl: true } }),
+        createSampler: (_d: unknown) => ({ ok: true, value: { __sampler: true } }),
+        createBindGroup: (desc: { readonly entries: readonly BindGroupEntry[] }) => {
+          spy.bindGroupCreates.push({ entries: desc.entries });
+          return { ok: true, value: { __bg: true } };
+        },
+      },
+      errorRegistry: { fire: (_e: unknown) => undefined },
+    },
+    view: opts.view,
+    encoder: {
+      beginRenderPass: (desc: { colorAttachments: readonly { view: unknown }[] }) => {
+        spy.beginRenderPassCalls.push({ view: desc.colorAttachments[0]?.view });
+        return passEncoder;
+      },
+    },
+  } as unknown as RenderPipelineContext;
+  return { ctx, spy };
+}
+
+describe('feat-20260609 M1 T-4: dispatchFullscreenPass custom reads spy', () => {
+  it('(a) reads[0] resolves via resolveCtx -> bindGroup samples the resolved input view', () => {
+    const inputView = { __resolvedInputView: 'offscreenColor' };
+    const writeView = { __writeView: 'rt' };
+    const swapView = { __swap: true };
+    const { ctx, spy } = makeSpyCtx({
+      lookup: () => ({ source: 'fn vs_main(){} fn fs_main(){}' }),
+      view: swapView,
+    });
+    const graph = new RenderGraph<RenderPipelineContext>();
+    graph.addColorTarget('rt', { format: 'rgba8unorm', size: { w: 64, h: 64 } });
+    addFullscreenPass(graph, 'pp', {
+      shader: 'test::reads-resolved',
+      color: 'rt',
+      reads: ['offscreenColor'],
+    });
+
+    const execute = findPassExecute(graph, 'pp');
+    expect(execute).toBeDefined();
+    if (!execute) return;
+
+    const resolveCtx = {
+      resolve: (n: string) =>
+        n === 'offscreenColor' ? inputView : n === 'rt' ? writeView : undefined,
+    };
+    execute(ctx, resolveCtx);
+
+    // (a) bindgroup binding 0 carries the resolved offscreenColor view, not the
+    // legacy ctx.view swap-chain view -- this confirms reads[0] -> graph-owned
+    // input is the real path.
+    expect(spy.bindGroupCreates.length).toBe(1);
+    const textureViewEntry = spy.bindGroupCreates[0]?.entries.find(
+      (e) => e.resource.kind === 'textureView',
+    );
+    expect(textureViewEntry).toBeDefined();
+    expect(textureViewEntry?.resource.value).toBe(inputView);
+  });
+
+  it('(b) success path -> setBindGroup(1, bg) + draw(3, 1, 0, 0) really fire on the encoder', () => {
+    const inputView = { __resolvedInputView: 'offscreenColor' };
+    const writeView = { __writeView: 'rt' };
+    const { ctx, spy } = makeSpyCtx({
+      lookup: () => ({ source: 'fn vs_main(){} fn fs_main(){}' }),
+      view: { __swap: true },
+    });
+    const graph = new RenderGraph<RenderPipelineContext>();
+    graph.addColorTarget('rt', { format: 'rgba8unorm', size: { w: 64, h: 64 } });
+    addFullscreenPass(graph, 'pp', {
+      shader: 'test::draw-fires',
+      color: 'rt',
+      reads: ['offscreenColor'],
+    });
+
+    const execute = findPassExecute(graph, 'pp');
+    if (!execute) return;
+
+    const resolveCtx = {
+      resolve: (n: string) =>
+        n === 'offscreenColor' ? inputView : n === 'rt' ? writeView : undefined,
+    };
+    execute(ctx, resolveCtx);
+
+    // beginRenderPass fired on the resolved write view (graph-owned 'rt').
+    expect(spy.beginRenderPassCalls.length).toBe(1);
+    expect(spy.beginRenderPassCalls[0]?.view).toBe(writeView);
+
+    // setBindGroup(1, bg) fired with slot=1 (plan-strategy convention; slot 0
+    // reserved for future view bind groups).
+    expect(spy.setBindGroupCalls.length).toBe(1);
+    expect(spy.setBindGroupCalls[0]?.slot).toBe(1);
+    expect(spy.setBindGroupCalls[0]?.bindGroup).toEqual({ __bg: true });
+
+    // handle.draw -> pass.draw(3, 1, 0, 0) for the fullscreen-triangle vertex
+    // shader covering the entire framebuffer.
+    expect(spy.drawCalls.length).toBe(1);
+    expect(spy.drawCalls[0]).toEqual({
+      vertexCount: 3,
+      instanceCount: 1,
+      firstVertex: 0,
+      firstInstance: 0,
+    });
+  });
+
+  it('(c) reads[0] unresolved -> throws PostProcessError fullscreen-input-not-found before any encoder call', () => {
+    const { ctx, spy } = makeSpyCtx({
+      lookup: () => ({ source: 'fn vs_main(){} fn fs_main(){}' }),
+      view: { __swap: true },
+    });
+    const graph = new RenderGraph<RenderPipelineContext>();
+    graph.addColorTarget('rt', { format: 'rgba8unorm', size: { w: 64, h: 64 } });
+    // reads[0] = 'never-declared': the resolveCtx below returns undefined for it
+    // -> dispatcher must throw.
+    addFullscreenPass(graph, 'pp', {
+      shader: 'test::reads-throw',
+      color: 'rt',
+      reads: ['never-declared'],
+    });
+
+    const execute = findPassExecute(graph, 'pp');
+    if (!execute) return;
+
+    const resolveCtx = { resolve: (_n: string) => undefined };
+    let caught: unknown = null;
+    try {
+      execute(ctx, resolveCtx);
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).not.toBeNull();
+    const err = caught as { code?: string; detail?: { readsKey?: string; passName?: string } };
+    expect(err.code).toBe('fullscreen-input-not-found');
+    expect(err.detail?.readsKey).toBe('never-declared');
+    expect(err.detail?.passName).toBe('pp');
+
+    // Charter P3 fail-fast: throw fires BEFORE any encoder call. The encoder
+    // remains untouched (no spurious render passes / bind groups created).
+    expect(spy.beginRenderPassCalls.length).toBe(0);
+    expect(spy.setBindGroupCalls.length).toBe(0);
+    expect(spy.drawCalls.length).toBe(0);
+  });
+
+  it('(d) reads === [] preserves legacy ctx.view swap-chain path (no resolveCtx call for input)', () => {
+    const swapView = { __swap: true };
+    const { ctx, spy } = makeSpyCtx({
+      lookup: () => ({ source: 'fn vs_main(){} fn fs_main(){}' }),
+      view: swapView,
+    });
+    const graph = new RenderGraph<RenderPipelineContext>();
+    graph.addColorTarget('rt', { format: 'rgba8unorm', size: { w: 64, h: 64 } });
+    addFullscreenPass(graph, 'pp', {
+      shader: 'test::no-reads',
+      color: 'rt',
+      // reads omitted -> defaults to []
+    });
+
+    const execute = findPassExecute(graph, 'pp');
+    if (!execute) return;
+
+    let resolveCalls = 0;
+    const resolveCtx = {
+      resolve: (n: string): unknown => {
+        resolveCalls += 1;
+        return n === 'rt' ? { __rt: true } : undefined;
+      },
+    };
+    execute(ctx, resolveCtx);
+
+    // ctx.view (swap-chain) feeds the bind-group input texture entry when reads
+    // is empty (preserving the FXAA-style legacy swap-chain sample contract).
+    expect(spy.bindGroupCreates.length).toBe(1);
+    const tvEntry = spy.bindGroupCreates[0]?.entries.find((e) => e.resource.kind === 'textureView');
+    expect(tvEntry?.resource.value).toBe(swapView);
+    // resolveCtx.resolve is still consulted for the writes target (color='rt').
+    expect(resolveCalls).toBeGreaterThanOrEqual(1);
+  });
+});