@forgeax/engine-render 0.1.2

package/src/__tests__/render-feature-gpu-work.integration.test.ts

@@ -0,0 +1,377 @@
+import { RenderGraph, RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import {
+  type BindGroup,
+  type Buffer,
+  type ComputePipeline,
+  type RenderPipeline,
+  type RhiCommandEncoder,
+  RhiError,
+} from '@forgeax/engine-rhi';
+import { type RhiNullDevice, rhi } from '@forgeax/engine-rhi-null';
+import { err, ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import {
+  composeRenderFeatureGraph,
+  type RenderFeatureGraphContribution,
+} from '../features/graph-contribution';
+import { createRenderFeatureGpuWorkResolver } from '../features/prepared-gpu-work';
+import { RenderFeatureComputeGraphProjection } from '../features/render-graph-compute';
+import { RenderFeatureRasterGraphProjection } from '../features/render-graph-raster';
+import { RenderFeatureGraphBufferRegistry } from '../features/render-graph-resources';
+import type { PreparedGraphicsResolvedResource } from '../prepare/prepared-graphics-resolver';
+
+describe('RenderFeature persistent GPU work', () => {
+  it('projects compute output and indirect raster consumption into one typed graph', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const indirectBuffer = device
+      .createBuffer({ size: 16, usage: 0x0080 | 0x0100 | 0x0020 | 0x0008 })
+      .unwrap();
+    const graph = new RenderGraphBuilder<{ readonly encoder: RhiCommandEncoder }>();
+    const output = graph
+      .createTexture('output', { format: 'rgba8unorm', size: { width: 1, height: 1 } })
+      .unwrap();
+    const outputView = graph.view(output, { label: 'output.view' }).unwrap();
+    const buffers = new RenderFeatureGraphBufferRegistry(graph);
+    const compute = new RenderFeatureComputeGraphProjection(graph, buffers);
+    expect(
+      compute.addPass('vfx.simulate-and-project', 'forgeax.vfx', 0, {
+        buffers: [
+          {
+            name: 'draw-args',
+            buffer: indirectBuffer,
+            size: 16,
+            physicalUsage: 0x0080 | 0x0100 | 0x0020 | 0x0008,
+            access: 'storage-write',
+          },
+        ],
+        dispatches: [
+          {
+            pipeline: {} as ComputePipeline,
+            bindGroup: {} as BindGroup,
+            workgroups: [1, 1, 1],
+          },
+        ],
+      }).ok,
+    ).toBe(true);
+
+    const pipeline = { kind: 'pipeline', generation: 1 } as const;
+    const binding = { kind: 'bindings', generation: 1 } as const;
+    const vertices = { kind: 'vertex-data', generation: 1 } as const;
+    const gpuArgs = { name: 'draw-args', generation: 1 } as never;
+    const resources = new Map<object, PreparedGraphicsResolvedResource>([
+      [
+        pipeline,
+        {
+          kind: 'pipeline',
+          reference: pipeline as never,
+          handle: {} as RenderPipeline,
+        },
+      ],
+      [
+        vertices,
+        {
+          kind: 'vertex-data',
+          reference: vertices as never,
+          handle: indirectBuffer,
+          size: 16,
+          physicalUsage: 0x0080 | 0x0100 | 0x0020 | 0x0008,
+        },
+      ],
+      [
+        binding,
+        {
+          kind: 'bindings',
+          reference: binding as never,
+          handle: {} as BindGroup,
+        },
+      ],
+    ]);
+    const raster = new RenderFeatureRasterGraphProjection(
+      graph,
+      () => ({ texture: output, view: outputView }),
+      undefined,
+      buffers,
+    );
+    expect(
+      raster.addPass(
+        'vfx.draw',
+        'vfx',
+        0,
+        {
+          attachments: {
+            colors: [
+              {
+                resource: 'output',
+                format: 'rgba8unorm',
+                loadOp: 'clear',
+                storeOp: 'store',
+              },
+            ],
+          },
+          draws: [
+            {
+              kind: 'draw-indirect',
+              pipeline: pipeline as never,
+              bindings: [binding as never],
+              vertexData: [{ slot: 0, resource: vertices as never }],
+              command: { buffer: gpuArgs, offset: 0 },
+            },
+          ],
+        },
+        {
+          capabilityAvailable: true,
+          generation: 1,
+          attachments: [{ resource: 'output', format: 'rgba8unorm' }],
+          pipeline: pipeline as never,
+          pipelines: [pipeline as never],
+          bindings: [binding as never],
+          vertexData: [vertices as never],
+          indexData: [],
+        },
+        {
+          generation: 1,
+          resolve: (reference) => resources.get(reference),
+          resolveGpuBuffer: () => ({
+            buffer: indirectBuffer as Buffer,
+            size: 16,
+            physicalUsage: 0x0080 | 0x0100 | 0x0020 | 0x0008,
+          }),
+        },
+      ).ok,
+    ).toBe(true);
+
+    const compiled = graph.compile({ device, surfaceSize: { width: 1, height: 1 } }).unwrap();
+    expect(compiled.inspect().passes).toMatchObject([
+      { name: 'vfx.simulate-and-project', kind: 'compute', dependencies: [] },
+      { name: 'vfx.draw', kind: 'raster', dependencies: ['vfx.simulate-and-project'] },
+    ]);
+    const encoder = device.createCommandEncoder({ label: 'vfx-mixed-frame' }).unwrap();
+    expect(compiled.execute({ encoder }).ok).toBe(true);
+    expect(encoder.finish().ok).toBe(true);
+  });
+
+  it('classifies an asynchronous shader warmup as a next-frame retry', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const resolver = createRenderFeatureGpuWorkResolver({
+      device,
+      generation: 0,
+      featureIdentity: 'synthetic.gpu',
+      shaderModuleFactory: {
+        createShaderModule: () =>
+          err(
+            new RhiError({
+              code: 'rhi-not-available',
+              expected: 'asynchronous shader compilation to finish',
+              hint: 'retry on the next frame',
+            }),
+          ),
+      },
+    });
+
+    const prepared = resolver.prepareProgram('program', {
+      wgsl: 'synthetic',
+      entryPoints: ['simulate'],
+    });
+
+    expect(prepared.ok).toBe(false);
+    if (!prepared.ok) {
+      expect(prepared.error).toMatchObject({
+        code: 'render-feature-preparation-failed',
+        detail: {
+          operation: 'prepare-gpu-program',
+          reason: 'rhi-not-available:retry on the next frame',
+          recovery: 'next-frame',
+        },
+      });
+    }
+  });
+
+  it('reuses the shader-module cache label across instance-scoped programs', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const shader = (await rhi.createShaderModule(device, { code: 'synthetic' })).unwrap();
+    const labels: string[] = [];
+    const resolver = createRenderFeatureGpuWorkResolver({
+      device,
+      generation: 0,
+      featureIdentity: 'synthetic.gpu',
+      shaderModuleFactory: {
+        createShaderModule: ({ label }) => {
+          labels.push(label ?? '');
+          return ok(shader);
+        },
+      },
+    });
+    const descriptor = { wgsl: 'synthetic', entryPoints: ['simulate'] } as const;
+
+    expect(resolver.prepareProgram('player-a.program', descriptor).ok).toBe(true);
+    expect(resolver.prepareProgram('player-b.program', descriptor).ok).toBe(true);
+    expect(labels).toEqual(['synthetic.gpu.program.0', 'synthetic.gpu.program.0']);
+  });
+
+  it('records compute against persistent storage and releases it once', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const shader = (await rhi.createShaderModule(device, { code: 'synthetic' })).unwrap();
+    const resolver = createRenderFeatureGpuWorkResolver({
+      device,
+      generation: 4,
+      featureIdentity: 'synthetic.gpu',
+      shaderModuleFactory: { createShaderModule: () => ok(shader) },
+    });
+    resolver.beginFrame();
+    const program = resolver
+      .prepareProgram('program', {
+        wgsl: 'synthetic',
+        entryPoints: ['simulate', 'compact'],
+        bindings: [
+          {
+            entries: [
+              {
+                binding: 0,
+                visibility: 0x4,
+                buffer: { type: 'storage', hasDynamicOffset: false, minBindingSize: 0 },
+              },
+              {
+                binding: 1,
+                visibility: 0x4,
+                buffer: { type: 'storage', hasDynamicOffset: false, minBindingSize: 0 },
+              },
+            ],
+          },
+        ],
+      })
+      .unwrap();
+    const storage = resolver
+      .prepareBuffer('particles', {
+        size: 4096,
+        usage: ['storage', 'vertex'],
+        data: new Uint32Array([1, 2, 3, 4]),
+      })
+      .unwrap();
+    const indirect = resolver
+      .prepareBuffer('indirect', {
+        size: 20,
+        usage: ['storage', 'indirect'],
+        data: new Uint32Array([6, 0, 0, 0, 0]),
+      })
+      .unwrap();
+    const dispatchArgs = resolver
+      .prepareBuffer('dispatch-args', {
+        size: 12,
+        usage: ['indirect'],
+        data: new Uint32Array([1, 1, 1]),
+      })
+      .unwrap();
+    const bindings = resolver
+      .prepareBindings('bindings', {
+        program,
+        entries: [
+          { binding: 0, buffer: storage },
+          { binding: 1, buffer: indirect },
+        ],
+      })
+      .unwrap();
+    const computeDescriptor = {
+      program,
+      bindings,
+      dispatches: [
+        { entryPoint: 'simulate', workgroups: [16] as const },
+        { entryPoint: 'compact', workgroups: [1] as const },
+        { entryPoint: 'simulate', indirect: { buffer: dispatchArgs, offset: 0 } },
+      ],
+    } as const;
+    const missingUsage = resolver.resolveComputePass('synthetic.gpu', {
+      program,
+      bindings,
+      dispatches: [{ entryPoint: 'simulate', indirect: { buffer: storage, offset: 0 } }],
+    });
+    expect(missingUsage.ok).toBe(false);
+    if (!missingUsage.ok && missingUsage.error.code === 'render-feature-preparation-failed') {
+      expect(missingUsage.error.detail.reason).toBe('indirect-dispatch-invalid');
+    }
+    const outOfBounds = resolver.resolveComputePass('synthetic.gpu', {
+      program,
+      bindings,
+      dispatches: [{ entryPoint: 'simulate', indirect: { buffer: dispatchArgs, offset: 4 } }],
+    });
+    expect(outOfBounds.ok).toBe(false);
+    if (!outOfBounds.ok && outOfBounds.error.code === 'render-feature-preparation-failed') {
+      expect(outOfBounds.error.detail.reason).toBe('indirect-dispatch-invalid');
+    }
+    const work = resolver.resolveComputePass('synthetic.gpu', computeDescriptor).unwrap();
+    expect(work.buffers.map((buffer) => [buffer.name, buffer.access])).toEqual([
+      ['particles', 'storage-read-write'],
+      ['indirect', 'storage-read-write'],
+      ['dispatch-args', 'indirect-read'],
+    ]);
+    const graph = new RenderGraphBuilder<{ readonly encoder: RhiCommandEncoder }>();
+    const projection = new RenderFeatureComputeGraphProjection(graph);
+    expect(projection.addPass('synthetic.gpu.compute', 'synthetic.gpu', 0, work).ok).toBe(true);
+    const compiled = graph.compile({ device, surfaceSize: { width: 1, height: 1 } }).unwrap();
+    expect(compiled.inspect().passes[0]).toMatchObject({
+      name: 'synthetic.gpu.compute',
+      kind: 'compute',
+      accesses: [
+        { resource: 'synthetic.gpu.compute.particles', usage: 'storage-read-write' },
+        { resource: 'synthetic.gpu.compute.indirect', usage: 'storage-read-write' },
+        { resource: 'synthetic.gpu.compute.dispatch-args', usage: 'indirect-read' },
+      ],
+    });
+    const encoder = device.createCommandEncoder({ label: 'gpu-feature-frame' }).unwrap();
+    expect(compiled.execute({ encoder }).ok).toBe(true);
+    expect(encoder.finish().ok).toBe(true);
+
+    const productionGraph = new RenderGraph<{ readonly encoder: RhiCommandEncoder }>();
+    const contribution: RenderFeatureGraphContribution = {
+      featureIdentity: 'synthetic.gpu',
+      order: 0,
+      resources: [],
+      passes: [
+        {
+          featureIdentity: 'synthetic.gpu',
+          order: 0,
+          name: 'synthetic.gpu::compute',
+          descriptor: { reads: [], writes: [] },
+          dependsOn: [],
+          gpuCompute: {
+            program,
+            bindings,
+            dispatches: [{ entryPoint: 'simulate', workgroups: [1] }],
+          },
+          resolvedGpuCompute: work,
+        },
+      ],
+      topologySignature: 'synthetic.gpu::compute',
+    };
+    expect(composeRenderFeatureGraph(productionGraph, [contribution]).ok).toBe(true);
+    expect(productionGraph.compile({ backendKind: 'null', caps: device.caps, device }).ok).toBe(
+      true,
+    );
+    const productionEncoder = device.createCommandEncoder({ label: 'production-feature' }).unwrap();
+    productionGraph.execute({ encoder: productionEncoder });
+    expect(productionEncoder.finish().ok).toBe(true);
+    expect((device as RhiNullDevice).framePassNames).toContain('synthetic.gpu::compute');
+
+    expect(resolver.resolveBuffer(storage)).toBeDefined();
+    expect(resolver.resolveBuffer(indirect)).toBeDefined();
+    expect(resolver.resolveBuffer(dispatchArgs)).toBeDefined();
+    expect(resolver.retireUntouched()).toEqual([]);
+
+    resolver.beginFrame();
+    expect(resolver.retainBindings([bindings]).ok).toBe(true);
+    expect(resolver.resolveComputePass('synthetic.gpu', computeDescriptor).ok).toBe(true);
+    expect(resolver.retireUntouched()).toEqual([]);
+
+    resolver.beginFrame();
+    const retired = resolver.retireUntouched();
+    expect(retired).toHaveLength(1);
+    expect(resolver.resolveBuffer(storage)).toBeUndefined();
+    expect(retired[0]?.release().ok).toBe(true);
+    expect(retired[0]?.release().ok).toBe(true);
+    expect(resolver.dispose().ok).toBe(true);
+    expect(resolver.dispose().ok).toBe(true);
+  });
+});

package/src/__tests__/render-feature-graph.integration.test.ts

@@ -0,0 +1,205 @@
+import { World } from '@forgeax/engine-ecs';
+import type { RhiCanvasContext } from '@forgeax/engine-rhi';
+import { RhiNullCanvasContext, type RhiNullDevice, rhi } from '@forgeax/engine-rhi-null';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { constructRenderer } from '../construct-renderer';
+import type { RenderPipeline } from '../render-pipeline';
+
+const manifest = `data:application/json,${encodeURIComponent(
+  JSON.stringify({
+    schemaVersion: '1.0.0',
+    entries: [
+      { hash: 'pbr00000', wgsl: '/* pbr stub */', glsl: '', bindings: '' },
+      { hash: 'unlit000', wgsl: '/* unlit stub */', glsl: '', bindings: '' },
+      { hash: 'tonemap0', wgsl: '/* tonemap stub */', glsl: '', bindings: '' },
+    ],
+  }),
+)}`;
+
+function canvas(): HTMLCanvasElement {
+  return {
+    width: 1,
+    height: 1,
+    getContext: () => null,
+    addEventListener: () => undefined,
+    removeEventListener: () => undefined,
+  } as unknown as HTMLCanvasElement;
+}
+
+function pipeline(trace: string[], builds: { count: number }, passName: string): RenderPipeline {
+  return {
+    build: ({ graph, contributeFeatures }, topology) => {
+      builds.count += 1;
+      const surface = graph.importTexture(
+        `${passName}.surface`,
+        {
+          format: topology.surface.storageFormat,
+          size: 'surface',
+          usage: 0x10,
+          viewFormats:
+            topology.surface.storageFormat === topology.surface.viewFormat
+              ? []
+              : [topology.surface.viewFormat],
+        },
+        (frame) => frame.currentTexture,
+      );
+      if (!surface.ok) return surface;
+      const view = graph.importView(
+        surface.value,
+        { label: `${passName}.view`, format: topology.surface.viewFormat },
+        (frame) => frame.view,
+      );
+      if (!view.ok) return view;
+      const added = graph.addRasterPass(passName, {
+        accesses: [{ resource: view.value, usage: 'color-attachment' }],
+        colorAttachments: [
+          {
+            view: view.value,
+            loadOp: 'clear',
+            storeOp: 'store',
+            clearValue: { r: 0, g: 0, b: 0, a: 1 },
+          },
+        ],
+        encode: () => trace.push(passName),
+      });
+      if (!added.ok) return added;
+      return contributeFeatures([]);
+    },
+  };
+}
+
+describe('renderer-owned typed frame graph', () => {
+  it('removes pipeline installations by lease without reviving a disposed predecessor', async () => {
+    const renderer = await constructRenderer(canvas(), { rhi }, { shaderManifestUrl: manifest });
+    expect((await renderer.ready).ok).toBe(true);
+    renderer.registerPipeline('synthetic::first', pipeline([], { count: 0 }, 'first'));
+    renderer.registerPipeline('synthetic::second', pipeline([], { count: 0 }, 'second'));
+    const first = renderer.installPipeline({
+      kind: 'render-pipeline',
+      pipelineId: 'synthetic::first',
+    });
+    const second = renderer.installPipeline({
+      kind: 'render-pipeline',
+      pipelineId: 'synthetic::second',
+    });
+    expect(first.ok && second.ok).toBe(true);
+    if (!first.ok || !second.ok) return;
+    const world = new World();
+    expect(renderer.attachWorld(world).ok).toBe(true);
+    world.update().unwrap();
+    expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+    expect(renderer.perFramePassNames).toEqual(['second']);
+
+    first.value();
+    world.update().unwrap();
+    expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+    expect(renderer.perFramePassNames).toEqual(['second']);
+
+    second.value();
+    world.update().unwrap();
+    expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+    expect(renderer.perFramePassNames).not.toContain('first');
+    expect(renderer.perFramePassNames).not.toContain('second');
+    renderer.dispose();
+  });
+
+  it('builds once and executes through one submit boundary', async () => {
+    const trace: string[] = [];
+    const builds = { count: 0 };
+    const renderer = await constructRenderer(canvas(), { rhi }, { shaderManifestUrl: manifest });
+    expect((await renderer.ready).ok).toBe(true);
+    renderer.registerPipeline('synthetic::pipeline', pipeline(trace, builds, 'base'));
+    expect(
+      renderer.installPipeline({ kind: 'render-pipeline', pipelineId: 'synthetic::pipeline' }).ok,
+    ).toBe(true);
+    const device = renderer.device as RhiNullDevice;
+    const submit = device.queue.submit.bind(device.queue);
+    let submitCount = 0;
+    device.queue.submit = (buffers) => {
+      submitCount += 1;
+      return submit(buffers);
+    };
+    const world = new World();
+    expect(renderer.attachWorld(world).ok).toBe(true);
+    world.update().unwrap();
+    expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+    expect(renderer.perFramePassNames).toEqual(['base']);
+    expect(trace).toEqual(['base']);
+    expect(builds.count).toBe(1);
+    expect(submitCount).toBe(1);
+
+    trace.length = 0;
+    submitCount = 0;
+    world.update().unwrap();
+    expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+    expect(trace).toEqual(['base']);
+    expect(builds.count).toBe(1);
+    expect(submitCount).toBe(1);
+  });
+
+  it('keeps the last known good graph when replacement compilation fails', async () => {
+    let currentTextureCalls = 0;
+    const countedRhi = {
+      ...rhi,
+      acquireCanvasContext: (): { ok: true; value: RhiCanvasContext } => {
+        const base = new RhiNullCanvasContext();
+        return {
+          ok: true,
+          value: {
+            configure: base.configure.bind(base),
+            unconfigure: base.unconfigure.bind(base),
+            getConfiguration: base.getConfiguration.bind(base),
+            getCurrentTexture: () => {
+              currentTextureCalls += 1;
+              return base.getCurrentTexture();
+            },
+          },
+        };
+      },
+    };
+    const renderer = await constructRenderer(
+      canvas(),
+      { rhi: countedRhi },
+      { shaderManifestUrl: manifest },
+    );
+    expect((await renderer.ready).ok).toBe(true);
+    const trace: string[] = [];
+    renderer.registerPipeline('synthetic::healthy', pipeline(trace, { count: 0 }, 'healthy'));
+    renderer.registerPipeline('synthetic::invalid', {
+      build: ({ graph }) => {
+        const texture = graph.createTexture('uninitialized', {
+          format: 'rgba8unorm',
+          size: 'surface',
+        });
+        if (!texture.ok) return texture;
+        const view = graph.view(texture.value);
+        if (!view.ok) return view;
+        const pass = graph.addRasterPass('future-read', {
+          accesses: [{ resource: view.value, usage: 'sampled-read' }],
+          colorAttachments: [],
+          encode: () => undefined,
+        });
+        return pass.ok ? ok(undefined) : pass;
+      },
+    });
+    expect(
+      renderer.installPipeline({ kind: 'render-pipeline', pipelineId: 'synthetic::healthy' }).ok,
+    ).toBe(true);
+    const world = new World();
+    expect(renderer.attachWorld(world).ok).toBe(true);
+    world.update().unwrap();
+    expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+    expect(renderer.perFramePassNames).toEqual(['healthy']);
+    expect(trace).toEqual(['healthy']);
+    currentTextureCalls = 0;
+    expect(
+      renderer.installPipeline({ kind: 'render-pipeline', pipelineId: 'synthetic::invalid' }).ok,
+    ).toBe(true);
+    world.update().unwrap();
+    expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+    expect(renderer.perFramePassNames).toEqual(['healthy']);
+    expect(trace).toEqual(['healthy']);
+    expect(currentTextureCalls).toBe(0);
+  });
+});