@forgeax/engine-runtime 0.1.2

package/src/__tests__/render-feature-prepared-graphics.integration.test.ts

@@ -0,0 +1,264 @@
+import { World } from '@forgeax/engine-ecs';
+import type {
+  RenderFeature,
+  RenderFeatureDrawRecord,
+  RenderFeaturePreparedRef,
+  RenderPipeline,
+} from '@forgeax/engine-render';
+import { createRenderFeatureTarget, createRenderPipelineTarget } from '@forgeax/engine-render';
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { err, ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { createRenderer } from '../createRenderer';
+
+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: '' },
+    ],
+    materialShaders: [
+      {
+        identifier: 'forgeax::default-standard-pbr',
+        sourcePath: 'forgeax::default-standard-pbr.wgsl',
+        composedWgsl: '/* stub */',
+        paramSchema: '[]',
+        variants: [],
+      },
+      {
+        identifier: 'forgeax::default-unlit',
+        sourcePath: 'forgeax::default-unlit.wgsl',
+        composedWgsl: '/* stub */',
+        paramSchema: '[]',
+        variants: [],
+      },
+    ],
+  }),
+)}`;
+
+function canvas(): HTMLCanvasElement {
+  return {
+    width: 64,
+    height: 64,
+    getContext: () => null,
+    addEventListener: () => undefined,
+    removeEventListener: () => undefined,
+  } as unknown as HTMLCanvasElement;
+}
+
+function observeDrawCalls(device: RhiDevice): () => number {
+  let count = 0;
+  const createCommandEncoder = device.createCommandEncoder.bind(device);
+  device.createCommandEncoder = (descriptor) => {
+    const result = createCommandEncoder(descriptor);
+    if (!result.ok) return result;
+    const encoder = result.value;
+    const beginRenderPass = encoder.beginRenderPass.bind(encoder);
+    encoder.beginRenderPass = (passDescriptor) => {
+      const pass = beginRenderPass(passDescriptor);
+      const draw = pass.draw.bind(pass);
+      const drawIndexed = pass.drawIndexed.bind(pass);
+      pass.draw = (...args) => {
+        count += 1;
+        draw(...args);
+      };
+      pass.drawIndexed = (...args) => {
+        count += 1;
+        drawIndexed(...args);
+      };
+      return pass;
+    };
+    return result;
+  };
+  return () => count;
+}
+
+function pipeline(): RenderPipeline {
+  return {
+    build: ({ graph, contributeFeatures }) => {
+      const scene = createRenderPipelineTarget(graph, 'prepared-scene', {
+        format: 'rgba8unorm',
+        size: 'surface',
+      });
+      if (!scene.ok) return scene;
+      const base = graph.addRasterPass('base', {
+        accesses: [{ resource: scene.value.view, usage: 'color-attachment' }],
+        colorAttachments: [
+          {
+            view: scene.value.view,
+            loadOp: 'clear',
+            storeOp: 'store',
+            clearValue: { r: 0, g: 0, b: 0, a: 1 },
+          },
+        ],
+        encode: () => undefined,
+      });
+      if (!base.ok) return base;
+      return contributeFeatures([
+        {
+          kind: 'scene-color',
+          texture: scene.value.texture,
+          view: scene.value.view,
+          format: scene.value.format,
+          sampleCount: 1,
+        },
+      ]);
+    },
+  };
+}
+
+function preparedFeature(
+  identity: string,
+  draws: readonly RenderFeatureDrawRecord[],
+): RenderFeature<{ readonly draws: readonly RenderFeatureDrawRecord[] }> {
+  let pipelineRef: RenderFeaturePreparedRef<'pipeline'> | undefined;
+  let bindingsRef: RenderFeaturePreparedRef<'bindings'> | undefined;
+  let verticesRef: RenderFeaturePreparedRef<'vertex-data'> | undefined;
+  let indicesRef: RenderFeaturePreparedRef<'index-data'> | undefined;
+
+  return {
+    identity,
+    extract: () => ok({ draws }),
+    prepare: (_data, context) => {
+      const pipelineResult = context.graphics.preparePipeline('forward', {
+        shader: 'synthetic.unlit',
+        vertexLayout: 'position',
+        colorFormats: ['rgba8unorm'],
+      });
+      if (!pipelineResult.ok) return pipelineResult;
+      const bindingsResult = context.graphics.prepareBindings('forward', {
+        pipeline: pipelineResult.value,
+        values: { opacity: 1 },
+      });
+      if (!bindingsResult.ok) return bindingsResult;
+      const verticesResult = context.graphics.prepareVertexData('quad', {
+        layout: 'position',
+        data: new Float32Array([0, 0, 0]),
+      });
+      if (!verticesResult.ok) return verticesResult;
+      const indicesResult = context.graphics.prepareIndexData('quad', {
+        format: 'uint16',
+        data: new Uint16Array([0, 1, 2]),
+      });
+      if (!indicesResult.ok) return indicesResult;
+      pipelineRef = pipelineResult.value;
+      bindingsRef = bindingsResult.value;
+      verticesRef = verticesResult.value;
+      indicesRef = indicesResult.value;
+      return ok(undefined);
+    },
+    contribute: (data, context) => {
+      if (data.draws.length === 0) return ok(undefined);
+      if (
+        pipelineRef === undefined ||
+        bindingsRef === undefined ||
+        verticesRef === undefined ||
+        indicesRef === undefined
+      ) {
+        return err(new Error('prepared refs missing') as never);
+      }
+      const preparedPipeline = pipelineRef;
+      const preparedBindings = bindingsRef;
+      const preparedVertices = verticesRef;
+      const preparedIndices = indicesRef;
+      const normalized: RenderFeatureDrawRecord[] = data.draws.map((draw) => ({
+        ...draw,
+        pipeline: preparedPipeline,
+        bindings: [preparedBindings],
+        vertexData: [{ slot: 0, resource: preparedVertices }],
+        ...(draw.kind === 'draw-indexed'
+          ? { indexData: { resource: preparedIndices, format: 'uint16' as const } }
+          : {}),
+      }));
+      return context.staging.addGraphicsPass('forward', {
+        attachments: {
+          colors: [
+            {
+              resource: createRenderFeatureTarget({
+                kind: 'scene-color',
+                format: 'rgba8unorm',
+                sampleCount: 1,
+              }),
+              format: 'rgba8unorm',
+              loadOp: 'load',
+              storeOp: 'store',
+            },
+          ],
+        },
+        draws: normalized,
+      });
+    },
+  };
+}
+
+describe('prepared graphics null integration', () => {
+  it('records vertex-only and indexed work through one graph and submit boundary', async () => {
+    const vertex: RenderFeatureDrawRecord = {
+      kind: 'draw',
+      pipeline: { kind: 'pipeline', generation: 0 },
+      bindings: [{ kind: 'bindings', generation: 0 }],
+      vertexData: [{ slot: 0, resource: { kind: 'vertex-data', generation: 0 } }],
+      command: { vertexCount: 3, instanceCount: 1 },
+    };
+    const indexed: RenderFeatureDrawRecord = {
+      kind: 'draw-indexed',
+      pipeline: vertex.pipeline,
+      bindings: vertex.bindings,
+      vertexData: vertex.vertexData,
+      indexData: { resource: { kind: 'index-data', generation: 0 }, format: 'uint16' },
+      command: { indexCount: 3, instanceCount: 1 },
+    };
+    const renderer = await createRenderer(
+      canvas(),
+      { rhi, features: [preparedFeature('synthetic.prepared', [vertex, indexed])] },
+      { shaderManifestUrl: manifest },
+    );
+    renderer.registerPipeline('synthetic::prepared', pipeline());
+    expect(
+      renderer.installPipeline({ kind: 'render-pipeline', pipelineId: 'synthetic::prepared' }).ok,
+    ).toBe(true);
+    expect((await renderer.ready).ok).toBe(true);
+    const drawCount = observeDrawCalls(renderer.device);
+    const queue = renderer.device.queue;
+    let submitCount = 0;
+    const submit = queue.submit.bind(queue);
+    queue.submit = (buffers) => {
+      submitCount += 1;
+      return submit(buffers);
+    };
+
+    const world = new World();
+    const attachment = renderer.attachWorld(world);
+    if (!attachment.ok) throw attachment.error;
+    world.update().unwrap();
+    const result = renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+    expect(result.ok).toBe(true);
+    expect(renderer.perFramePassNames).toContain('synthetic.prepared::forward');
+    expect(drawCount()).toBeGreaterThanOrEqual(2);
+    expect(submitCount).toBe(1);
+    renderer.dispose();
+  });
+
+  it('keeps empty prepared work out of the active graph', async () => {
+    const renderer = await createRenderer(
+      canvas(),
+      { rhi, features: [preparedFeature('synthetic.empty', [])] },
+      { shaderManifestUrl: manifest },
+    );
+    renderer.registerPipeline('synthetic::empty', pipeline());
+    expect(
+      renderer.installPipeline({ kind: 'render-pipeline', pipelineId: 'synthetic::empty' }).ok,
+    ).toBe(true);
+    expect((await renderer.ready).ok).toBe(true);
+    const world = new World();
+    const attachment = renderer.attachWorld(world);
+    if (!attachment.ok) throw attachment.error;
+    world.update().unwrap();
+    expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+    expect(renderer.perFramePassNames).not.toContain('synthetic.empty::forward');
+    renderer.dispose();
+  });
+});

package/src/__tests__/render-feature-prepared-graphics.regression.integration.test.ts

@@ -0,0 +1,361 @@
+import { World } from '@forgeax/engine-ecs';
+import type {
+  RenderFeature,
+  RenderFeatureDrawRecord,
+  RenderFeaturePreparedRef,
+  RenderPipeline,
+} from '@forgeax/engine-render';
+import {
+  Camera,
+  createRenderFeatureTarget,
+  createRenderPipelineTarget,
+  RenderFeatureStageFailedError,
+} from '@forgeax/engine-render';
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { Transform } from '@forgeax/engine-scene';
+import { err, ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { createRenderer } from '../createRenderer';
+
+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: '' },
+    ],
+    materialShaders: [
+      {
+        identifier: 'forgeax::default-standard-pbr',
+        sourcePath: 'forgeax::default-standard-pbr.wgsl',
+        composedWgsl: '/* stub */',
+        paramSchema: '[]',
+        variants: [],
+      },
+      {
+        identifier: 'forgeax::default-unlit',
+        sourcePath: 'forgeax::default-unlit.wgsl',
+        composedWgsl: '/* stub */',
+        paramSchema: '[]',
+        variants: [],
+      },
+    ],
+  }),
+)}`;
+
+function canvas(): HTMLCanvasElement {
+  return {
+    width: 64,
+    height: 64,
+    getContext: () => null,
+    addEventListener: () => undefined,
+    removeEventListener: () => undefined,
+  } as unknown as HTMLCanvasElement;
+}
+
+function observeDrawCalls(device: RhiDevice): () => number {
+  let count = 0;
+  const createCommandEncoder = device.createCommandEncoder.bind(device);
+  device.createCommandEncoder = (descriptor) => {
+    const result = createCommandEncoder(descriptor);
+    if (!result.ok) return result;
+    const encoder = result.value;
+    const beginRenderPass = encoder.beginRenderPass.bind(encoder);
+    encoder.beginRenderPass = (passDescriptor) => {
+      const pass = beginRenderPass(passDescriptor);
+      const draw = pass.draw.bind(pass);
+      const drawIndexed = pass.drawIndexed.bind(pass);
+      pass.draw = (...args) => {
+        count += 1;
+        draw(...args);
+      };
+      pass.drawIndexed = (...args) => {
+        count += 1;
+        drawIndexed(...args);
+      };
+      return pass;
+    };
+    return result;
+  };
+  return () => count;
+}
+
+function pipeline(): RenderPipeline {
+  return {
+    build: ({ graph, contributeFeatures }) => {
+      const scene = createRenderPipelineTarget(graph, 'prepared-scene', {
+        format: 'rgba8unorm',
+        size: 'surface',
+      });
+      if (!scene.ok) return scene;
+      const base = graph.addRasterPass('base', {
+        accesses: [{ resource: scene.value.view, usage: 'color-attachment' }],
+        colorAttachments: [
+          {
+            view: scene.value.view,
+            loadOp: 'clear',
+            storeOp: 'store',
+            clearValue: { r: 0, g: 0, b: 0, a: 1 },
+          },
+        ],
+        encode: () => undefined,
+      });
+      if (!base.ok) return base;
+      return contributeFeatures([
+        {
+          kind: 'scene-color',
+          texture: scene.value.texture,
+          view: scene.value.view,
+          format: scene.value.format,
+          sampleCount: 1,
+        },
+      ]);
+    },
+  };
+}
+
+function world(): World {
+  const value = new World();
+  value.spawn(
+    { component: Transform, data: { pos: [0, 0, 3], quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
+    { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+  );
+  return value;
+}
+
+type MatrixCase = 'accepted' | 'mismatch' | 'empty' | 'multi-feature' | 'recovery';
+
+interface MatrixResult {
+  readonly case: MatrixCase;
+  readonly drawCount: number;
+  readonly featureStatuses: readonly string[];
+  readonly errorCodes: readonly string[];
+  readonly passNames: readonly string[];
+}
+
+interface FeatureState {
+  pipeline: RenderFeaturePreparedRef<'pipeline'> | undefined;
+  bindings: RenderFeaturePreparedRef<'bindings'> | undefined;
+  vertices: RenderFeaturePreparedRef<'vertex-data'> | undefined;
+  firstContribution: boolean;
+}
+
+function graphicsFeature(
+  identity: string,
+  state: FeatureState,
+  mode: Exclude<MatrixCase, 'multi-feature'>,
+): RenderFeature<{ readonly draw: boolean }> {
+  return {
+    identity,
+    extract: () => ok({ draw: mode !== 'empty' }),
+    prepare: (_data, context) => {
+      const pipelineResult = context.graphics.preparePipeline('forward', {
+        shader: 'synthetic.unlit',
+        vertexLayout: 'position',
+        colorFormats: ['rgba8unorm'],
+      });
+      if (!pipelineResult.ok) return pipelineResult;
+      const bindingsResult = context.graphics.prepareBindings('forward', {
+        pipeline: pipelineResult.value,
+        values: { opacity: 1 },
+      });
+      if (!bindingsResult.ok) return bindingsResult;
+      const verticesResult = context.graphics.prepareVertexData('triangle', {
+        layout: 'position',
+        data: new Float32Array([0, 0, 0]),
+      });
+      if (!verticesResult.ok) return verticesResult;
+      state.pipeline = pipelineResult.value;
+      state.bindings = bindingsResult.value;
+      state.vertices = verticesResult.value;
+      return ok(undefined);
+    },
+    contribute: (data, context) => {
+      if (!data.draw) return ok(undefined);
+      const { pipeline: preparedPipeline, bindings, vertices } = state;
+      if (preparedPipeline === undefined || bindings === undefined || vertices === undefined) {
+        return err(new RenderFeatureStageFailedError(identity, 0, 'contribute', 'next-frame'));
+      }
+      const drawPipeline =
+        mode === 'mismatch' || (mode === 'recovery' && state.firstContribution)
+          ? { kind: 'pipeline' as const, generation: 99 }
+          : preparedPipeline;
+      state.firstContribution = false;
+      const draw: RenderFeatureDrawRecord = {
+        kind: 'draw',
+        pipeline: drawPipeline,
+        bindings: [bindings],
+        vertexData: [{ slot: 0, resource: vertices }],
+        command: { vertexCount: 3, instanceCount: 1 },
+      };
+      return context.staging.addGraphicsPass('forward', {
+        attachments: {
+          colors: [
+            {
+              resource: createRenderFeatureTarget({
+                kind: 'scene-color',
+                format: 'rgba8unorm',
+                sampleCount: 1,
+              }),
+              format: 'rgba8unorm',
+              loadOp: 'load',
+              storeOp: 'store',
+            },
+          ],
+        },
+        draws: [draw],
+      });
+    },
+  };
+}
+
+async function rendererWith(
+  features: readonly RenderFeature<{ readonly draw: boolean }>[],
+): Promise<Awaited<ReturnType<typeof createRenderer>>> {
+  const renderer = await createRenderer(
+    canvas(),
+    { rhi, features },
+    { shaderManifestUrl: manifest },
+  );
+  renderer.registerPipeline('synthetic::regression', pipeline());
+  expect(
+    renderer.installPipeline({ kind: 'render-pipeline', pipelineId: 'synthetic::regression' }).ok,
+  ).toBe(true);
+  expect((await renderer.ready).ok).toBe(true);
+  return renderer;
+}
+
+async function runCase(
+  name: Exclude<MatrixCase, 'multi-feature'>,
+  feature = graphicsFeature(
+    `synthetic.${name}`,
+    {
+      pipeline: undefined,
+      bindings: undefined,
+      vertices: undefined,
+      firstContribution: true,
+    },
+    name,
+  ),
+): Promise<MatrixResult> {
+  const renderer = await rendererWith([feature]);
+  const drawCount = observeDrawCalls(renderer.device);
+  const activeWorld = world();
+  const attachment = renderer.attachWorld(activeWorld);
+  if (!attachment.ok) throw attachment.error;
+  activeWorld.update().unwrap();
+  const result = renderer.draw([activeWorld], { cameraOwner: 0, resourceOwner: 0 });
+  const firstDiagnostics = renderer.renderFeatureDiagnostics();
+  let featureStatuses = firstDiagnostics.map((diagnostic) => diagnostic.status);
+  const first: MatrixResult = {
+    case: name,
+    drawCount: drawCount(),
+    featureStatuses,
+    errorCodes: firstDiagnostics.flatMap((diagnostic) =>
+      diagnostic.latestError === undefined ? [] : [diagnostic.latestError.code],
+    ),
+    passNames: [...renderer.perFramePassNames],
+  };
+  expect(result.ok).toBe(true);
+  if (name === 'recovery') {
+    activeWorld.update().unwrap();
+    expect(renderer.draw([activeWorld], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+    featureStatuses = renderer.renderFeatureDiagnostics().map((diagnostic) => diagnostic.status);
+  }
+  renderer.dispose();
+  return { ...first, featureStatuses };
+}
+
+describe('prepared graphics full-stack regression matrix', () => {
+  it('emits machine-readable accepted, mismatch, empty, and recovery cases', async () => {
+    const accepted = await runCase('accepted');
+    const mismatch = await runCase('mismatch');
+    const empty = await runCase('empty');
+    const recovery = await runCase('recovery');
+
+    expect([accepted, mismatch, empty, recovery]).toEqual([
+      expect.objectContaining({
+        case: 'accepted',
+        featureStatuses: ['active'],
+        errorCodes: [],
+      }),
+      expect.objectContaining({
+        case: 'mismatch',
+        featureStatuses: ['failed'],
+        errorCodes: ['render-feature-prepared-state-mismatch'],
+        drawCount: 0,
+      }),
+      expect.objectContaining({
+        case: 'empty',
+        featureStatuses: ['active'],
+        errorCodes: [],
+        drawCount: 0,
+      }),
+      expect.objectContaining({
+        case: 'recovery',
+        featureStatuses: ['active'],
+        errorCodes: ['render-feature-prepared-state-mismatch'],
+      }),
+    ]);
+  });
+
+  it('isolates one failed feature while retaining another feature and the base graph', async () => {
+    const healthyState: FeatureState = {
+      pipeline: undefined,
+      bindings: undefined,
+      vertices: undefined,
+      firstContribution: true,
+    };
+    const failingState: FeatureState = {
+      pipeline: undefined,
+      bindings: undefined,
+      vertices: undefined,
+      firstContribution: true,
+    };
+    const renderer = await rendererWith([
+      graphicsFeature('synthetic.healthy', healthyState, 'accepted'),
+      graphicsFeature('synthetic.failing', failingState, 'mismatch'),
+    ]);
+    const drawCount = observeDrawCalls(renderer.device);
+    const activeWorld = world();
+    const attachment = renderer.attachWorld(activeWorld);
+    if (!attachment.ok) throw attachment.error;
+    activeWorld.update().unwrap();
+    const result = renderer.draw([activeWorld], { cameraOwner: 0, resourceOwner: 0 });
+    const diagnostics = renderer.renderFeatureDiagnostics();
+
+    expect(result.ok).toBe(true);
+    expect(diagnostics.map((diagnostic) => diagnostic.status)).toEqual(['active', 'failed']);
+    expect(diagnostics[1]?.latestError?.code).toBe('render-feature-prepared-state-mismatch');
+    expect(renderer.perFramePassNames).toContain('synthetic.healthy::forward');
+    expect(renderer.perFramePassNames).not.toContain('synthetic.failing::forward');
+    expect(drawCount()).toBe(1);
+    renderer.dispose();
+  });
+
+  it('keeps an unregistered feature identical to the baseline renderer path', async () => {
+    const renderer = await rendererWith([]);
+    const drawCount = observeDrawCalls(renderer.device);
+    let submits = 0;
+    const submit = renderer.device.queue.submit.bind(renderer.device.queue);
+    renderer.device.queue.submit = (buffers) => {
+      submits += 1;
+      return submit(buffers);
+    };
+
+    const activeWorld = world();
+    const attachment = renderer.attachWorld(activeWorld);
+    if (!attachment.ok) throw attachment.error;
+    activeWorld.update().unwrap();
+    const result = renderer.draw([activeWorld], { cameraOwner: 0, resourceOwner: 0 });
+
+    expect(result.ok).toBe(true);
+    expect(renderer.renderFeatureDiagnostics()).toEqual([]);
+    expect(renderer.perFramePassNames).toEqual(['base']);
+    expect(drawCount()).toBe(0);
+    expect(submits).toBe(1);
+    renderer.dispose();
+  });
+});