@forgeax/engine-render-graph 0.0.0-dev.8d955ade1c79

package/src/__tests__/render-graph-errors.test-d.ts

@@ -0,0 +1,207 @@
+import { describe, expectTypeOf, it } from 'vitest';
+import {
+  type AliasSourceDetail,
+  type CapabilityDetail,
+  type CapMissingDetail,
+  type ColorDomainDetail,
+  type DanglingReadDetail,
+  type DeclarationDetail,
+  type DescriptorDetail,
+  type DuplicateResourceDetail,
+  type InvalidFormatDetail,
+  type LifecycleDetail,
+  type ObservationDetail,
+  type PassFailureDetail,
+  RenderGraphError,
+  type RenderGraphErrorCode,
+  type RenderGraphErrorDetail,
+  type ResourceAccessDetail,
+  type ResourceAllocFailedDetail,
+} from '../errors.js';
+import type { GraphPassKind, GraphResourceKind } from '../types.js';
+
+describe('RenderGraphError code/detail correlation', () => {
+  it('accepts every existing code with its matching detail interface', () => {
+    new RenderGraphError({
+      code: 'dangling-read',
+      expected: '',
+      hint: '',
+      detail: { resourceKey: 'resource', passName: 'pass' } satisfies DanglingReadDetail,
+    });
+    new RenderGraphError({
+      code: 'cap-missing',
+      expected: '',
+      hint: '',
+      detail: { cap: 'compute', passName: 'pass' } satisfies CapMissingDetail,
+    });
+    new RenderGraphError({
+      code: 'duplicate-resource',
+      expected: '',
+      hint: '',
+      detail: { resourceKey: 'resource' } satisfies DuplicateResourceDetail,
+    });
+    new RenderGraphError({
+      code: 'alias-source-missing',
+      expected: '',
+      hint: '',
+      detail: { aliasKey: 'alias', sourceKey: 'source' } satisfies AliasSourceDetail,
+    });
+    new RenderGraphError({
+      code: 'unknown-resource',
+      expected: '',
+      hint: '',
+      detail: { resourceKey: 'resource', passName: 'pass' } satisfies DanglingReadDetail,
+    });
+    new RenderGraphError({
+      code: 'resource-alloc-failed',
+      expected: '',
+      hint: '',
+      detail: {
+        resourceKey: 'resource',
+        passName: 'pass',
+        rhiCode: 'lost',
+      } satisfies ResourceAllocFailedDetail,
+    });
+    new RenderGraphError({
+      code: 'invalid-format',
+      expected: '',
+      hint: '',
+      detail: {
+        resourceKey: 'resource',
+        format: 'rgba16float',
+        expected: ['rgba16float'],
+      } satisfies InvalidFormatDetail,
+    });
+    for (const code of [
+      'observation-absent',
+      'observation-invalid-format',
+      'observation-invalid-size',
+      'observation-missing-copy-src',
+      'observation-stale',
+      'observation-retired',
+    ] as const) {
+      new RenderGraphError({
+        code,
+        expected: '',
+        hint: '',
+        detail: { frameId: 1, expected: 'frame' } satisfies ObservationDetail,
+      });
+    }
+    for (const code of [
+      'invalid-color-domain',
+      'missing-color-domain',
+      'color-domain-mismatch',
+    ] as const) {
+      new RenderGraphError({
+        code,
+        expected: '',
+        hint: '',
+        detail: { value: 'linear' } satisfies ColorDomainDetail,
+      });
+    }
+  });
+
+  it('keeps detail optional, including explicit undefined', () => {
+    new RenderGraphError({ code: 'dangling-read', expected: '', hint: '' });
+    new RenderGraphError({ code: 'invalid-format', expected: '', hint: '', detail: undefined });
+  });
+
+  it('rejects a detail belonging to a different code', () => {
+    new RenderGraphError({
+      code: 'dangling-read',
+      expected: '',
+      hint: '',
+      // @ts-expect-error -- dangling-read accepts DanglingReadDetail, not CapMissingDetail.
+      detail: { cap: 'compute', passName: 'pass' },
+    });
+  });
+
+  it('preserves the closed code and detail-shape public unions', () => {
+    expectTypeOf<RenderGraphErrorCode>().toEqualTypeOf<
+      | 'dangling-read'
+      | 'cap-missing'
+      | 'duplicate-resource'
+      | 'alias-source-missing'
+      | 'unknown-resource'
+      | 'resource-alloc-failed'
+      | 'invalid-format'
+      | 'observation-absent'
+      | 'observation-invalid-format'
+      | 'observation-invalid-size'
+      | 'observation-missing-copy-src'
+      | 'observation-stale'
+      | 'observation-retired'
+      | 'invalid-color-domain'
+      | 'missing-color-domain'
+      | 'color-domain-mismatch'
+      | 'duplicate-pass-name'
+      | 'duplicate-resource-label'
+      | 'builder-sealed'
+      | 'foreign-resource-handle'
+      | 'resource-not-declared-by-pass'
+      | 'uninitialized-read'
+      | 'access-conflict'
+      | 'capability-missing'
+      | 'resource-descriptor-invalid'
+      | 'import-usage-mismatch'
+      | 'resource-allocation-failed'
+      | 'resource-resolution-failed'
+      | 'pass-encode-failed'
+      | 'compiled-graph-retired'
+      | 'resource-retire-failed'
+    >();
+    expectTypeOf<RenderGraphErrorDetail>().toEqualTypeOf<
+      | DanglingReadDetail
+      | CapMissingDetail
+      | DuplicateResourceDetail
+      | AliasSourceDetail
+      | ResourceAllocFailedDetail
+      | InvalidFormatDetail
+      | ObservationDetail
+      | ColorDomainDetail
+      | DeclarationDetail
+      | ResourceAccessDetail
+      | CapabilityDetail
+      | DescriptorDetail
+      | PassFailureDetail
+      | LifecycleDetail
+    >();
+  });
+});
+
+function assertNever(value: never): never {
+  throw new Error(String(value));
+}
+
+function exhaustivePass(kind: GraphPassKind): string {
+  switch (kind) {
+    case 'raster':
+      return kind;
+    case 'compute':
+      return kind;
+    case 'copy':
+      return kind;
+  }
+  return assertNever(kind);
+}
+
+function exhaustiveResource(kind: GraphResourceKind): string {
+  switch (kind) {
+    case 'texture':
+      return kind;
+    case 'buffer':
+      return kind;
+  }
+  return assertNever(kind);
+}
+
+describe('M4 render graph closed unions', () => {
+  it('keeps pass and resource variants exhaustively handled without a default branch', () => {
+    expectTypeOf(exhaustivePass).returns.toEqualTypeOf<string>();
+    expectTypeOf(exhaustiveResource).returns.toEqualTypeOf<string>();
+  });
+
+  it('keeps RenderGraphErrorCode closed', () => {
+    expectTypeOf<RenderGraphErrorCode>().not.toEqualTypeOf<string>();
+  });
+});

package/src/__tests__/render-graph-regressions.unit.test.ts

@@ -0,0 +1,126 @@
+import type { Buffer, RhiCommandEncoder } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import { RenderGraphBuilder } from '../builder.js';
+import { RenderGraph } from '../graph.js';
+
+interface Frame {
+  readonly encoder: RhiCommandEncoder;
+  readonly external: Buffer;
+}
+
+describe('RenderGraph fixed temporal regressions', () => {
+  it('accepts write-read-write without depending on a future writer', async () => {
+    const device = (await (await rhi.requestAdapter()).unwrap().requestDevice()).unwrap();
+    const graph = new RenderGraphBuilder<Frame>();
+    const x = graph.createBuffer('x', { size: 16 }).unwrap();
+    const y = graph.createBuffer('y', { size: 16 }).unwrap();
+    graph.addCopyPass('seed-x', {
+      accesses: [{ resource: x, usage: 'copy-dst' }],
+      encode: () => undefined,
+    });
+    graph.addCopyPass('consume-x', {
+      accesses: [
+        { resource: x, usage: 'copy-src' },
+        { resource: y, usage: 'copy-dst' },
+      ],
+      encode: () => undefined,
+    });
+    graph.addCopyPass('rewrite-x', {
+      accesses: [
+        { resource: y, usage: 'copy-src' },
+        { resource: x, usage: 'copy-dst' },
+      ],
+      encode: () => undefined,
+    });
+
+    const result = graph.compile({ device, surfaceSize: { width: 1, height: 1 } });
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.inspect().passes.map((pass) => pass.name)).toEqual([
+        'seed-x',
+        'consume-x',
+        'rewrite-x',
+      ]);
+    }
+  });
+
+  it('accepts first read only when a resource is imported from its owner', async () => {
+    const device = (await (await rhi.requestAdapter()).unwrap().requestDevice()).unwrap();
+    const graph = new RenderGraphBuilder<Frame>();
+    const input = graph
+      .importBuffer('external-input', { size: 16, usage: 0x0040 }, (frame) => frame.external)
+      .unwrap();
+    graph.addComputePass('consume-external', {
+      accesses: [{ resource: input, usage: 'uniform-read' }],
+      encode: () => undefined,
+    });
+
+    expect(graph.compile({ device, surfaceSize: { width: 1, height: 1 } }).ok).toBe(true);
+  });
+
+  it('rejects a repeated pass label at declaration time', () => {
+    const graph = new RenderGraphBuilder<Frame>();
+    expect(graph.addCopyPass('duplicate-label', { accesses: [], encode: () => undefined }).ok).toBe(
+      true,
+    );
+    const duplicate = graph.addCopyPass('duplicate-label', {
+      accesses: [],
+      encode: () => undefined,
+    });
+    expect(duplicate.ok).toBe(false);
+    if (!duplicate.ok) expect(duplicate.error.code).toBe('duplicate-pass-name');
+  });
+
+  it('owns compute pass begin and end for the current RenderGraph facade', async () => {
+    const device = (await (await rhi.requestAdapter()).unwrap().requestDevice()).unwrap();
+    const graph = new RenderGraph<Frame>();
+    graph.addResource('external', { kind: 'buffer', lifetime: 'persistent' });
+    graph.addComputePass('compute', {
+      reads: ['external'],
+      writes: [],
+      encode: ({ pass }) => pass.dispatchWorkgroups(1),
+    });
+    expect(graph.compile({ backendKind: 'null', caps: device.caps, device }).ok).toBe(true);
+    const encoder = device.createCommandEncoder({ label: 'facade-compute' }).unwrap();
+    graph.execute({ encoder, external: device.createBuffer({ size: 16, usage: 0x40 }).unwrap() });
+    expect(encoder.finish().ok).toBe(true);
+  });
+
+  it('runs compute after-work only after ending the graph-owned pass', async () => {
+    const device = (await (await rhi.requestAdapter()).unwrap().requestDevice()).unwrap();
+    const graph = new RenderGraph<Frame>();
+    const events: string[] = [];
+    graph.addResource('external', { kind: 'buffer', lifetime: 'persistent' });
+    graph.addComputePass('timed-compute', {
+      reads: ['external'],
+      writes: [],
+      encode: ({ pass }) => {
+        events.push('encode');
+        pass.dispatchWorkgroups(1);
+      },
+      after: () => events.push('after'),
+    });
+    expect(graph.compile({ backendKind: 'null', caps: device.caps, device }).ok).toBe(true);
+    const rawEncoder = device.createCommandEncoder({ label: 'timed-compute' }).unwrap();
+    const encoder = {
+      beginComputePass: (...args: Parameters<RhiCommandEncoder['beginComputePass']>) => {
+        events.push('begin');
+        const pass = rawEncoder.beginComputePass(...args);
+        const end = pass.end.bind(pass);
+        pass.end = () => {
+          events.push('end');
+          end();
+        };
+        return pass;
+      },
+    } as RhiCommandEncoder;
+    graph.execute({
+      encoder,
+      external: device.createBuffer({ size: 16, usage: 0x40 }).unwrap(),
+    });
+
+    expect(events).toEqual(['begin', 'encode', 'end', 'after']);
+    expect(rawEncoder.finish().ok).toBe(true);
+  });
+});

package/src/__tests__/render-graph-rhi-null.integration.test.ts

@@ -0,0 +1,86 @@
+import type { RhiCommandEncoder } from '@forgeax/engine-rhi';
+import { type RhiNullDevice, rhi } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import { RenderGraphBuilder } from '../builder.js';
+
+describe('RenderGraphBuilder RhiNull integration', () => {
+  it('records copy and compute in declaration order on one command encoder', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const graph = new RenderGraphBuilder<{ readonly encoder: RhiCommandEncoder }>();
+    const data = graph.createBuffer('data', { size: 16 }).unwrap();
+    graph
+      .addCopyPass('seed', {
+        accesses: [{ resource: data, usage: 'copy-dst' }],
+        encode: ({ encoder, resources }) => {
+          encoder.clearBuffer(resources.buffer(data).unwrap());
+        },
+      })
+      .unwrap();
+    graph
+      .addComputePass('simulate', {
+        accesses: [{ resource: data, usage: 'storage-read-write' }],
+        encode: ({ pass, resources }) => {
+          expect(resources.buffer(data).ok).toBe(true);
+          pass.dispatchWorkgroups(1);
+        },
+      })
+      .unwrap();
+
+    const compiled = graph.compile({ device, surfaceSize: { width: 1, height: 1 } }).unwrap();
+    expect(compiled.inspect().passes).toMatchObject([
+      { name: 'seed', kind: 'copy', dependencies: [] },
+      { name: 'simulate', kind: 'compute', dependencies: ['seed'] },
+    ]);
+    const encoder = device.createCommandEncoder({ label: 'graph-frame' }).unwrap();
+    expect(compiled.execute({ encoder }).ok).toBe(true);
+    expect(encoder.finish().ok).toBe(true);
+    expect((device as RhiNullDevice).framePassNames).toEqual(['simulate']);
+    expect((await compiled.retire()).ok).toBe(true);
+  });
+
+  it('observes compute to indirect raster structure and command counts', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const graph = new RenderGraphBuilder<{ readonly encoder: RhiCommandEncoder }>();
+    const args = graph.createBuffer('draw-args', { size: 16 }).unwrap();
+    const output = graph
+      .createTexture('output', { format: 'rgba8unorm', size: { width: 1, height: 1 } })
+      .unwrap();
+    const outputView = graph.view(output, { label: 'output.view' }).unwrap();
+    graph
+      .addComputePass('build-args', {
+        accesses: [{ resource: args, usage: 'storage-write' }],
+        encode: ({ pass }) => pass.dispatchWorkgroups(1),
+      })
+      .unwrap();
+    graph
+      .addRasterPass('consume-args', {
+        accesses: [
+          { resource: args, usage: 'indirect-read' },
+          { resource: outputView, usage: 'color-attachment' },
+        ],
+        colorAttachments: [{ view: outputView, loadOp: 'clear', storeOp: 'store' }],
+        encode: ({ pass, resources }) => {
+          const layout = device.createBindGroupLayout({ entries: [] }).unwrap();
+          pass.setBindGroup(0, device.createBindGroup({ layout, entries: [] }).unwrap());
+          pass.drawIndirect(resources.buffer(args).unwrap(), 0);
+        },
+      })
+      .unwrap();
+
+    const compiled = graph.compile({ device, surfaceSize: { width: 1, height: 1 } }).unwrap();
+    expect(compiled.inspect().passes).toMatchObject([
+      { name: 'build-args', kind: 'compute', dependencies: [] },
+      { name: 'consume-args', kind: 'raster', dependencies: ['build-args'] },
+    ]);
+    const encoder = device.createCommandEncoder({ label: 'mixed-frame' }).unwrap();
+    expect(compiled.execute({ encoder }).ok).toBe(true);
+    expect(encoder.finish().ok).toBe(true);
+    expect((device as RhiNullDevice).framePassNames).toEqual(['build-args', 'consume-args']);
+    expect((device as RhiNullDevice).totalDispatchCount).toBe(1);
+    expect((device as RhiNullDevice).totalDrawCount).toBe(1);
+    expect((device as RhiNullDevice).totalBindGroupCount).toBe(1);
+    expect((await compiled.retire()).ok).toBe(true);
+  });
+});