@forgeax/engine-render 0.1.2

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

@@ -0,0 +1,122 @@
+import type { RhiCaps } from '@forgeax/engine-rhi';
+import { err, ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { RenderFeatureStageFailedError } from '../errors/render';
+import { createRenderFeatureHost, runRenderFeatureFrame } from '../features/host';
+import type { RenderFeature } from '../features/types';
+
+const caps = { backendKind: 'null' } as unknown as Readonly<RhiCaps>;
+
+function ordinaryFeature(identity: string): RenderFeature<{ readonly work: true }> {
+  return {
+    identity,
+    extract: () => ok({ work: true }),
+    prepare: () => ok(undefined),
+    contribute: (_data, context) => {
+      context.staging.addResource('base', { kind: 'texture', lifetime: 'transient' });
+      return context.staging.addPass('base', {
+        reads: [],
+        writes: ['base'],
+        execute: () => undefined,
+      });
+    },
+  };
+}
+
+function preparedFeature(
+  identity: string,
+  mode: 'healthy' | 'invalid' | 'empty',
+): RenderFeature<{ readonly work: true }> {
+  let pipeline: { kind: 'pipeline'; generation: number } | undefined;
+  let bindings: { kind: 'bindings'; generation: number } | undefined;
+  let vertices: { kind: 'vertex-data'; generation: number } | undefined;
+  return {
+    identity,
+    extract: () => ok({ work: true }),
+    prepare: (_data, context) => {
+      const preparedPipeline = context.graphics.preparePipeline('forward', {
+        shader: 'synthetic',
+        vertexLayout: 'position',
+        colorFormats: ['rgba8unorm'],
+      });
+      if (!preparedPipeline.ok) return preparedPipeline;
+      const preparedBindings = context.graphics.prepareBindings('forward', {
+        pipeline: preparedPipeline.value,
+        values: {},
+      });
+      if (!preparedBindings.ok) return preparedBindings;
+      const preparedVertices = context.graphics.prepareVertexData('triangle', {
+        layout: 'position',
+        data: [0, 0, 0],
+      });
+      if (!preparedVertices.ok) return preparedVertices;
+      pipeline = preparedPipeline.value;
+      bindings = preparedBindings.value;
+      vertices = preparedVertices.value;
+      return ok(undefined);
+    },
+    contribute: (_data, context) => {
+      if (mode === 'empty') return ok(undefined);
+      if (pipeline === undefined || bindings === undefined || vertices === undefined) {
+        return err(new RenderFeatureStageFailedError(identity, 0, 'contribute', 'next-frame'));
+      }
+      context.staging.addResource('color', { kind: 'texture', lifetime: 'transient' });
+      return context.staging.addGraphicsPass('forward', {
+        attachments: {
+          colors:
+            mode === 'healthy'
+              ? [{ resource: 'color', format: 'rgba8unorm', loadOp: 'load', storeOp: 'store' }]
+              : [{ resource: 'missing', format: 'rgba8unorm', loadOp: 'load', storeOp: 'store' }],
+        },
+        draws: [
+          {
+            kind: 'draw',
+            pipeline,
+            bindings: [bindings],
+            vertexData: [{ slot: 0, resource: vertices }],
+            command: { vertexCount: 3, instanceCount: 1 },
+          },
+        ],
+      });
+    },
+  };
+}
+
+describe('prepared graphics feature isolation', () => {
+  it('aborts only the failed feature while preserving healthy and base contributions', () => {
+    const host = createRenderFeatureHost([
+      preparedFeature('synthetic.failed', 'invalid'),
+      ordinaryFeature('synthetic.healthy'),
+    ]).unwrap();
+    const result = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      caps,
+    });
+
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0]).toMatchObject({
+      detail: { featureIdentity: 'synthetic.failed' },
+    });
+    expect(result.contributions.map((contribution) => contribution.featureIdentity)).toEqual([
+      'synthetic.healthy',
+    ]);
+    expect(result.contributions[0]?.passes.map((pass) => pass.name)).toEqual([
+      'synthetic.healthy::base',
+    ]);
+  });
+
+  it('treats an empty feature as successful no-work without a phantom graphics pass', () => {
+    const host = createRenderFeatureHost([preparedFeature('synthetic.empty', 'empty')]).unwrap();
+    const result = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 2,
+      caps,
+    });
+    expect(result.errors).toEqual([]);
+    expect(result.contributions).toEqual([]);
+    expect(host.diagnostics()[0]?.status).toBe('active');
+  });
+});

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

@@ -0,0 +1,59 @@
+import { ok } from '@forgeax/engine-types';
+import type { RenderFeature } from '../index';
+
+interface Frame {
+  readonly count: number;
+}
+
+const feature = {
+  identity: 'prepared.graphics.negative',
+  extract: () => ok<Frame>({ count: 1 }),
+  prepare(data, context) {
+    void data;
+    void context.graphics;
+
+    // @ts-expect-error prepared callbacks cannot access a raw device
+    context.graphics.device;
+    // @ts-expect-error prepared callbacks cannot access a command encoder
+    context.graphics.commandEncoder;
+    // @ts-expect-error prepared callbacks cannot access the full pipeline context
+    context.graphics.pipelineContext;
+    // @ts-expect-error prepared callbacks cannot issue submit work
+    context.graphics.submit;
+    // @ts-expect-error prepared callbacks cannot issue compute work
+    context.graphics.compute;
+    // @ts-expect-error prepared callbacks cannot access storage buffers
+    context.graphics.storageBuffer;
+    // @ts-expect-error prepared callbacks cannot issue indirect draws
+    context.graphics.drawIndirect;
+    // @ts-expect-error prepared callbacks cannot access backend-specific handles
+    context.graphics.backendHandle;
+    return ok(undefined);
+  },
+  contribute(data, context) {
+    void data;
+    void context.graphics;
+    // The legacy graph-only entry remains the only way to add ordinary graph work.
+    void context.staging.addPass;
+
+    // @ts-expect-error contribution cannot access a raw device
+    context.graphics.device;
+    // @ts-expect-error contribution cannot access a command encoder
+    context.graphics.commandEncoder;
+    // @ts-expect-error contribution cannot access the full pipeline context
+    context.graphics.pipelineContext;
+    // @ts-expect-error contribution cannot issue submit work
+    context.graphics.submit;
+    // @ts-expect-error contribution cannot issue compute work
+    context.graphics.compute;
+    // @ts-expect-error contribution cannot access storage buffers
+    context.graphics.storageBuffer;
+    // @ts-expect-error contribution cannot issue indirect draws
+    context.graphics.drawIndirect;
+    // @ts-expect-error contribution cannot access backend-specific handles
+    context.graphics.backendHandle;
+    return ok(undefined);
+  },
+} satisfies RenderFeature<Frame>;
+
+void feature;

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

@@ -0,0 +1,107 @@
+import { describe, expect, it } from 'vitest';
+import type {
+  RenderFeatureGraphicsPassDescriptor,
+  RenderFeaturePreparedGraphicsState,
+  RenderFeaturePreparedRef,
+} from '../features/prepared-graphics';
+import { recordRenderFeatureGraphicsPass } from '../record/frame-targets';
+
+type RecordingLedger = {
+  pipeline: number;
+  binding: number;
+  vertex: number;
+  index: number;
+  draw: number;
+};
+
+function ledger(): RecordingLedger {
+  return { pipeline: 0, binding: 0, vertex: 0, index: 0, draw: 0 };
+}
+
+function ref<Kind extends RenderFeaturePreparedRef['kind']>(
+  kind: Kind,
+  generation = 3,
+): RenderFeaturePreparedRef<Kind> {
+  return { kind, generation };
+}
+
+const pipeline = ref('pipeline');
+const bindings = ref('bindings');
+const vertices = ref('vertex-data');
+const indices = ref('index-data');
+
+const pass: RenderFeatureGraphicsPassDescriptor = {
+  attachments: {
+    colors: [{ resource: 'color', format: 'rgba8unorm', loadOp: 'load', storeOp: 'store' }],
+  },
+  draws: [
+    {
+      kind: 'draw',
+      pipeline,
+      bindings: [bindings],
+      vertexData: [{ slot: 0, resource: vertices }],
+      command: { vertexCount: 3, instanceCount: 1 },
+    },
+  ],
+};
+
+const state: RenderFeaturePreparedGraphicsState = {
+  capabilityAvailable: true,
+  generation: 3,
+  attachments: [{ resource: 'color', format: 'rgba8unorm' }],
+  pipeline,
+  bindings: [bindings],
+  vertexData: [vertices],
+  indexData: [indices],
+};
+
+describe('host-owned prepared graphics recording', () => {
+  it.each([
+    ['pipeline', { pipeline: undefined }],
+    ['bindings', { bindings: [] }],
+    ['vertex', { vertexData: [] }],
+    ['attachment', { attachments: [] }],
+  ] as const)('rejects missing %s before any RHI mutation', (_label, change) => {
+    const calls = ledger();
+    const result = recordRenderFeatureGraphicsPass(
+      'synthetic.invalid',
+      pass,
+      { ...state, ...change },
+      calls,
+    );
+    expect(result.ok).toBe(false);
+    expect(calls).toEqual(ledger());
+  });
+
+  it('rejects stale and foreign-kind records before recording the healthy feature', () => {
+    const stale = ledger();
+    const staleResult = recordRenderFeatureGraphicsPass(
+      'synthetic.invalid',
+      pass,
+      { ...state, generation: 4 },
+      stale,
+    );
+    expect(staleResult.ok).toBe(false);
+    expect(stale).toEqual(ledger());
+
+    const originalDraw = pass.draws[0];
+    expect(originalDraw).toBeDefined();
+    if (originalDraw === undefined) return;
+    const foreign = ledger();
+    const foreignResult = recordRenderFeatureGraphicsPass(
+      'synthetic.invalid',
+      { ...pass, draws: [{ ...originalDraw, pipeline: ref('bindings') as never }] },
+      state,
+      foreign,
+    );
+    expect(foreignResult.ok).toBe(false);
+    expect(foreign).toEqual(ledger());
+  });
+
+  it('records a complete draw only after all validation succeeds', () => {
+    const calls = ledger();
+    const result = recordRenderFeatureGraphicsPass('synthetic.valid', pass, state, calls);
+    expect(result).toMatchObject({ ok: true, value: { acceptedDrawCount: 1 } });
+    expect(calls).toEqual({ pipeline: 1, binding: 1, vertex: 1, index: 0, draw: 1 });
+  });
+});

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

@@ -0,0 +1,96 @@
+import { ok } from '@forgeax/engine-types';
+import type {
+  PreparedKind,
+  RenderFeature,
+  RenderFeatureDrawRecord,
+  RenderFeatureGraphicsPassDescriptor,
+  RenderFeaturePreparedRef,
+} from '../index';
+
+interface Frame {
+  readonly vertexCount: number;
+  readonly indexCount: number;
+}
+
+const feature = {
+  identity: 'prepared.graphics.positive',
+  extract: () => ok<Frame>({ vertexCount: 6, indexCount: 6 }),
+  prepare(data, context) {
+    const pipeline = context.graphics.preparePipeline('forward', {
+      shader: 'unlit',
+      vertexLayout: 'position',
+      colorFormats: ['rgba8unorm'],
+    });
+    if (!pipeline.ok) return pipeline;
+
+    const bindings = context.graphics.prepareBindings('forward', {
+      pipeline: pipeline.value,
+      values: { opacity: 1 },
+    });
+    if (!bindings.ok) return bindings;
+
+    const vertices = context.graphics.prepareVertexData('quad', {
+      layout: 'position',
+      data: new Float32Array(data.vertexCount),
+    });
+    if (!vertices.ok) return vertices;
+
+    const indices = context.graphics.prepareIndexData('quad', {
+      format: 'uint16',
+      data: new Uint16Array(data.indexCount),
+    });
+    if (!indices.ok) return indices;
+
+    const refs: readonly RenderFeaturePreparedRef<PreparedKind>[] = [
+      pipeline.value,
+      bindings.value,
+      vertices.value,
+      indices.value,
+    ];
+    void refs;
+    return ok(undefined);
+  },
+  contribute(data, context) {
+    const pipeline: RenderFeaturePreparedRef<'pipeline'> = {
+      kind: 'pipeline',
+      generation: 1,
+    };
+    const bindings: RenderFeaturePreparedRef<'bindings'> = {
+      kind: 'bindings',
+      generation: 1,
+    };
+    const vertices: RenderFeaturePreparedRef<'vertex-data'> = {
+      kind: 'vertex-data',
+      generation: 1,
+    };
+    const indices: RenderFeaturePreparedRef<'index-data'> = {
+      kind: 'index-data',
+      generation: 1,
+    };
+
+    const vertexOnly: RenderFeatureDrawRecord = {
+      kind: 'draw',
+      pipeline,
+      bindings: [bindings],
+      vertexData: [{ slot: 0, resource: vertices }],
+      command: { vertexCount: data.vertexCount, instanceCount: 1 },
+    };
+    const indexed: RenderFeatureDrawRecord = {
+      kind: 'draw-indexed',
+      pipeline,
+      bindings: [bindings],
+      vertexData: [{ slot: 0, resource: vertices }],
+      indexData: { resource: indices, format: 'uint16' },
+      command: { indexCount: data.indexCount, instanceCount: 1 },
+    };
+    const pass: RenderFeatureGraphicsPassDescriptor = {
+      attachments: {
+        colors: [{ resource: 'color', format: 'rgba8unorm', loadOp: 'load', storeOp: 'store' }],
+      },
+      draws: [vertexOnly, indexed],
+    };
+    return context.staging.addGraphicsPass('forward', pass);
+  },
+} satisfies RenderFeature<Frame>;
+
+void feature;

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

@@ -0,0 +1,121 @@
+import { describe, expect, it } from 'vitest';
+import type {
+  PreparedKind,
+  RenderFeatureDrawRecord,
+  RenderFeatureGraphicsPassDescriptor,
+  RenderFeaturePreparedGraphicsState,
+  RenderFeaturePreparedRef,
+} from '../features/prepared-graphics';
+import { validateRenderFeatureGraphicsPass } from '../features/prepared-graphics';
+
+function ref<Kind extends PreparedKind>(
+  kind: Kind,
+  generation = 1,
+): RenderFeaturePreparedRef<Kind> {
+  return { kind, generation };
+}
+
+const pipeline = ref('pipeline');
+const bindings = ref('bindings');
+const vertices = ref('vertex-data');
+const indices = ref('index-data');
+
+const vertexDraw: RenderFeatureDrawRecord = {
+  kind: 'draw',
+  pipeline,
+  bindings: [bindings],
+  vertexData: [{ slot: 0, resource: vertices }],
+  command: { vertexCount: 3, instanceCount: 1 },
+};
+
+const indexedDraw: RenderFeatureDrawRecord = {
+  kind: 'draw-indexed',
+  pipeline,
+  bindings: [bindings],
+  vertexData: [{ slot: 0, resource: vertices }],
+  indexData: { resource: indices, format: 'uint16' },
+  command: { indexCount: 3, instanceCount: 1 },
+};
+
+const validPass: RenderFeatureGraphicsPassDescriptor = {
+  attachments: {
+    colors: [{ resource: 'color', format: 'rgba8unorm', loadOp: 'load', storeOp: 'store' }],
+  },
+  draws: [vertexDraw, indexedDraw],
+};
+
+const validState: RenderFeaturePreparedGraphicsState = {
+  capabilityAvailable: true,
+  generation: 1,
+  attachments: [{ resource: 'color', format: 'rgba8unorm' }],
+  pipeline,
+  bindings: [bindings],
+  vertexData: [vertices],
+  indexData: [indices],
+};
+
+function expectFailure(
+  pass: RenderFeatureGraphicsPassDescriptor,
+  state: RenderFeaturePreparedGraphicsState,
+): void {
+  const result = validateRenderFeatureGraphicsPass('prepared.graphics.unit', pass, state);
+  expect(result.ok).toBe(false);
+  if (result.ok) return;
+  expect(result.error.code).toMatch(/^render-feature-/);
+  expect(result.error.expected).toBeTypeOf('string');
+  expect(result.error.hint).toBeTypeOf('string');
+  expect(result.error).toHaveProperty('detail.featureIdentity', 'prepared.graphics.unit');
+}
+
+describe('prepared graphics descriptor validation', () => {
+  it('accepts complete vertex-only and indexed records', () => {
+    const result = validateRenderFeatureGraphicsPass(
+      'prepared.graphics.unit',
+      validPass,
+      validState,
+    );
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.value.acceptedDrawCount).toBe(2);
+  });
+
+  it('rejects missing capability before recording', () => {
+    expectFailure(validPass, { ...validState, capabilityAvailable: false });
+  });
+
+  it('rejects missing pipeline, binding, vertex, index, and attachment state', () => {
+    expectFailure(validPass, { ...validState, pipeline: undefined });
+    expectFailure(validPass, { ...validState, bindings: [] });
+    expectFailure(validPass, { ...validState, vertexData: [] });
+    expectFailure(validPass, { ...validState, indexData: [] });
+    expectFailure(validPass, { ...validState, attachments: [] });
+  });
+
+  it('rejects foreign kind and stale generation references', () => {
+    expectFailure(validPass, { ...validState, pipeline: ref('bindings') });
+    expectFailure(validPass, { ...validState, pipeline: ref('pipeline', 2) });
+  });
+
+  it('rejects layout and attachment format mismatches', () => {
+    expectFailure(validPass, {
+      ...validState,
+      vertexData: [ref('vertex-data', 2)],
+    });
+    expectFailure(validPass, {
+      ...validState,
+      attachments: [{ resource: 'color', format: 'bgra8unorm' }],
+    });
+  });
+
+  it('rejects indexed records without index data and vertex records with index data', () => {
+    const missingIndex: RenderFeatureGraphicsPassDescriptor = {
+      ...validPass,
+      draws: [{ ...indexedDraw, indexData: undefined }],
+    };
+    const unexpectedIndex: RenderFeatureGraphicsPassDescriptor = {
+      ...validPass,
+      draws: [{ ...vertexDraw, indexData: { resource: indices, format: 'uint16' } }],
+    };
+    expectFailure(missingIndex, validState);
+    expectFailure(unexpectedIndex, validState);
+  });
+});

package/src/__tests__/render-feature-public-surface.test-d.ts

@@ -0,0 +1,75 @@
+import type {
+  RenderError,
+  Renderer,
+  RendererOptions,
+  RenderFeature,
+  RenderFeatureContributeContext,
+  RenderFeatureDiagnostics,
+  RenderFeatureErrorDescriptor,
+  RenderFeatureExtractContext,
+  RenderFeaturePassContext,
+  RenderFeaturePrepareContext,
+} from '@forgeax/engine-render';
+import { ok } from '@forgeax/engine-types';
+
+type FrameData = {
+  readonly visibleCount: number;
+};
+
+const feature = {
+  identity: 'test.public-surface',
+  extract(context: RenderFeatureExtractContext) {
+    const owner: number = context.owner;
+    return ok<FrameData>({ visibleCount: owner });
+  },
+  prepare(data: FrameData, context: RenderFeaturePrepareContext) {
+    const count: number = data.visibleCount;
+    const frameNumber: number = context.frame.frameNumber;
+    void count;
+    void frameNumber;
+    return ok(undefined);
+  },
+  contribute(data: FrameData, context: RenderFeatureContributeContext) {
+    const count: number = data.visibleCount;
+    void count;
+    void context.staging;
+    return ok(undefined);
+  },
+} satisfies RenderFeature<FrameData>;
+
+const options: RendererOptions = { features: [feature] };
+const diagnostics = (renderer: Renderer): readonly RenderFeatureDiagnostics[] =>
+  renderer.renderFeatureDiagnostics();
+
+const errorDescriptor = (error: RenderError): RenderFeatureErrorDescriptor | undefined => {
+  switch (error.code) {
+    case 'render-feature-registration-conflict':
+      return error;
+    case 'render-feature-stage-failed':
+      return error;
+    case 'render-feature-capability-missing':
+      return error;
+    case 'render-feature-pass-order-conflict':
+      return error;
+    default:
+      return undefined;
+  }
+};
+
+const passContext = (context: RenderFeaturePassContext): number => context.frame.frameNumber;
+// @ts-expect-error Wave1 pass execution does not expose incomplete GPU draw state
+passContext.commands;
+void errorDescriptor;
+void options;
+void diagnostics;
+void passContext;
+
+// The renderer host and construction context are internal implementation seams.
+// @ts-expect-error host internals are not part of the render root surface
+type _NoPublicFeatureHost = typeof import('@forgeax/engine-render')['RenderFeatureHost'];
+// @ts-expect-error frame input is not a producer-facing public declaration
+type _NoPublicFrameInput = typeof import('@forgeax/engine-render')['RenderFeatureFrameInput'];
+// @ts-expect-error bundler manifest wiring is not a render feature API
+type _NoPublicBundlerOptions = typeof import('@forgeax/engine-render')['BundlerOptions'];
+// @ts-expect-error remote inspection/RPC symbols do not belong to the render root
+type _NoPublicRpcClient = typeof import('@forgeax/engine-render')['InspectorClient'];