@forgeax/engine-render 0.1.2

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

@@ -0,0 +1,200 @@
+import { RenderGraph, type ResourceDescriptor } from '@forgeax/engine-render-graph';
+import { err } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { RenderFeaturePreparationFailedError } from '../errors/render';
+import type { RenderFeatureGraphContribution } from '../features/graph-contribution';
+import {
+  composeRenderFeatureGraph,
+  createRenderFeatureContributionStaging,
+} from '../features/graph-contribution';
+import type {
+  RenderFeatureGraphicsPassDescriptor,
+  RenderFeaturePreparedGraphicsState,
+  RenderFeaturePreparedRef,
+} from '../features/prepared-graphics';
+import { createRenderFeatureTarget } from '../features/targets';
+
+const target: ResourceDescriptor = { kind: 'texture', lifetime: 'transient' };
+
+const pass: RenderFeatureGraphicsPassDescriptor = {
+  attachments: {
+    colors: [{ resource: 'color', format: 'rgba8unorm', loadOp: 'load', storeOp: 'store' }],
+  },
+  draws: [
+    {
+      kind: 'draw',
+      pipeline: { kind: 'pipeline', generation: 2 } as RenderFeaturePreparedRef<'pipeline'>,
+      bindings: [{ kind: 'bindings', generation: 2 }],
+      vertexData: [{ slot: 0, resource: { kind: 'vertex-data', generation: 2 } }],
+      command: { vertexCount: 3, instanceCount: 1 },
+    },
+  ],
+};
+
+describe('render feature graphics staging', () => {
+  it('projects the latest resolved graphics snapshot after a topology-stable update', () => {
+    const graphicsState: RenderFeaturePreparedGraphicsState = {
+      capabilityAvailable: true,
+      generation: 1,
+      attachments: [],
+      pipeline: pass.draws[0]?.pipeline,
+      bindings: pass.draws[0]?.bindings ?? [],
+      vertexData: pass.draws[0]?.vertexData.map((vertex) => vertex.resource) ?? [],
+      indexData: [],
+    };
+    const contribution = (generation: number): RenderFeatureGraphContribution => ({
+      featureIdentity: 'synthetic.graphics',
+      order: 0,
+      resources: [],
+      passes: [
+        {
+          featureIdentity: 'synthetic.graphics',
+          order: 0,
+          name: 'synthetic.graphics::forward',
+          descriptor: { reads: [], writes: [] },
+          dependsOn: [],
+          graphics: pass,
+          graphicsState,
+          resolvedGraphics: {
+            generation,
+            resolve: () => undefined,
+          },
+        },
+      ],
+      topologySignature: 'synthetic.graphics::forward',
+    });
+    const observed: number[] = [];
+    const graph = new RenderGraph();
+    const composed = composeRenderFeatureGraph(graph, [contribution(1)], (ctx, current) => {
+      void ctx;
+      observed.push(current.resolvedGraphics?.generation ?? -1);
+    });
+    expect(composed.ok).toBe(true);
+    if (!composed.ok) return;
+    expect(graph.compile({ backendKind: 'null', caps: {} as never }).ok).toBe(true);
+    graph.execute(undefined);
+    expect(composed.value.update([contribution(2)]).topologyChanged).toBe(false);
+    graph.execute(undefined);
+    expect(observed).toEqual([1, 2]);
+  });
+
+  it('projects an accepted graphics pass into the active graph contribution', () => {
+    const staging = createRenderFeatureContributionStaging('synthetic.graphics', 0);
+    expect(staging.addResource('color', target).ok).toBe(true);
+    expect(staging.addGraphicsPass('forward', pass).ok).toBe(true);
+
+    const contribution = staging.commit();
+    expect(contribution.ok).toBe(true);
+    if (!contribution.ok) return;
+    expect(contribution.value.passes).toHaveLength(1);
+    expect(contribution.value.passes[0]).toMatchObject({
+      name: 'synthetic.graphics::forward',
+      graphics: pass,
+    });
+
+    const graph = new RenderGraph();
+    const composed = composeRenderFeatureGraph(graph, [contribution.value]);
+    expect(composed.ok).toBe(true);
+    if (composed.ok) {
+      expect(composed.value.passNames).toEqual(['synthetic.graphics::forward']);
+      expect(composed.value.graph).toBe(graph);
+    }
+  });
+
+  it('keeps the reserved swapchain attachment unqualified', () => {
+    const staging = createRenderFeatureContributionStaging('synthetic.graphics', 0);
+    const swapchainPass: RenderFeatureGraphicsPassDescriptor = {
+      ...pass,
+      attachments: {
+        colors: [
+          { resource: 'swapchain', format: 'rgba8unorm-srgb', loadOp: 'load', storeOp: 'store' },
+        ],
+      },
+    };
+    expect(staging.addGraphicsPass('overlay', swapchainPass).ok).toBe(true);
+    const contribution = staging.commit();
+    expect(contribution.ok).toBe(true);
+    if (!contribution.ok) return;
+    expect(contribution.value.passes[0]?.descriptor.writes).toEqual(['swapchain']);
+  });
+
+  it('projects render-pipeline target handles to semantic graph dependencies', () => {
+    const colorTarget = createRenderFeatureTarget({
+      kind: 'scene-color',
+      format: 'rgba16float',
+      sampleCount: 1,
+    });
+    const depthTarget = createRenderFeatureTarget({
+      kind: 'scene-depth',
+      format: 'depth24plus-stencil8',
+      sampleCount: 1,
+    });
+    const targetPass: RenderFeatureGraphicsPassDescriptor = {
+      ...pass,
+      attachments: {
+        colors: [
+          { resource: colorTarget, format: colorTarget.format, loadOp: 'load', storeOp: 'store' },
+        ],
+        depthStencil: {
+          resource: depthTarget,
+          format: depthTarget.format,
+          depthLoadOp: 'load',
+          depthStoreOp: 'store',
+        },
+      },
+    };
+    const staging = createRenderFeatureContributionStaging('synthetic.scene', 0);
+    expect(staging.addGraphicsPass('particles', targetPass).ok).toBe(true);
+    const contribution = staging.commit();
+    expect(contribution.ok).toBe(true);
+    if (!contribution.ok) return;
+
+    expect(contribution.value.passes[0]?.descriptor).toMatchObject({
+      reads: ['scene-depth'],
+      writes: ['scene-color'],
+    });
+  });
+
+  it('keeps ordinary addPass graph-only and contributes no work for an empty draw list', () => {
+    const staging = createRenderFeatureContributionStaging('synthetic.empty', 0);
+    const empty: RenderFeatureGraphicsPassDescriptor = { ...pass, draws: [] };
+    expect(staging.addGraphicsPass('empty', empty).ok).toBe(true);
+    const contribution = staging.commit();
+    expect(contribution.ok).toBe(true);
+    if (contribution.ok) {
+      expect(contribution.value.passes).toHaveLength(0);
+      expect(contribution.value.resources).toHaveLength(0);
+    }
+  });
+
+  it('treats asynchronous pipeline warm-up as an empty retryable frame', () => {
+    const staging = createRenderFeatureContributionStaging('synthetic.warmup', 0, undefined, () =>
+      err(
+        new RenderFeaturePreparationFailedError(
+          'synthetic.warmup',
+          0,
+          'resolve',
+          'pipeline',
+          'custom-material',
+          'pipeline-pending',
+          'next-frame',
+        ),
+      ),
+    );
+
+    expect(staging.addGraphicsPass('warmup', pass).ok).toBe(true);
+    const contribution = staging.commit();
+    expect(contribution.ok).toBe(true);
+    if (contribution.ok) expect(contribution.value.passes).toHaveLength(0);
+  });
+
+  it('aborts graphics staging without creating a feature-private graph', () => {
+    const staging = createRenderFeatureContributionStaging('synthetic.failed', 0);
+    expect(staging.addResource('color', target).ok).toBe(true);
+    expect(staging.addGraphicsPass('forward', pass).ok).toBe(true);
+    staging.abort();
+    expect(staging.resources).toEqual([]);
+    expect(staging.passes).toEqual([]);
+    expect(staging.commit().ok).toBe(false);
+  });
+});

package/src/__tests__/render-feature-order.unit.test.ts

@@ -0,0 +1,66 @@
+import type { ResourceDescriptor } from '@forgeax/engine-render-graph';
+import { describe, expect, it } from 'vitest';
+import {
+  createRenderFeatureContributionStaging,
+  mergeRenderFeatureContributions,
+} from '../features/graph-contribution';
+
+const resource: ResourceDescriptor = {
+  kind: 'texture',
+  lifetime: 'transient',
+};
+
+function pass(reads: readonly string[] = []) {
+  return { reads, writes: [], execute: () => undefined };
+}
+
+describe('render feature contribution order', () => {
+  it('sorts contributions by registration order before preserving declaration order', () => {
+    const late = createRenderFeatureContributionStaging('synthetic.late', 2);
+    const early = createRenderFeatureContributionStaging('synthetic.early', 0);
+    late.addResource('target', resource);
+    early.addResource('target', resource);
+    late.addPass('late-pass', pass(['target']));
+    early.addPass('first-pass', pass(['target']));
+
+    const merged = mergeRenderFeatureContributions([
+      late.commit().unwrap(),
+      early.commit().unwrap(),
+    ]);
+
+    expect(merged.ok).toBe(true);
+    if (!merged.ok) return;
+    expect(merged.value.passes.map((entry) => entry.name)).toEqual([
+      'synthetic.early::first-pass',
+      'synthetic.late::late-pass',
+    ]);
+  });
+
+  it('keeps a same-feature dependency in declared order', () => {
+    const feature = createRenderFeatureContributionStaging('synthetic.feature', 0);
+    feature.addResource('target', resource);
+    feature.addPass('first', pass(['target']));
+    feature.addPass('second', pass(['target']), {
+      dependsOn: [{ featureIdentity: 'synthetic.feature', passIdentity: 'first' }],
+    });
+
+    const merged = mergeRenderFeatureContributions([feature.commit().unwrap()]);
+
+    expect(merged.ok).toBe(true);
+  });
+
+  it('reports a same-feature dependency on a later declaration', () => {
+    const feature = createRenderFeatureContributionStaging('synthetic.feature', 0);
+    feature.addResource('target', resource);
+    feature.addPass('first', pass(['target']), {
+      dependsOn: [{ featureIdentity: 'synthetic.feature', passIdentity: 'second' }],
+    });
+    feature.addPass('second', pass(['target']));
+
+    const merged = mergeRenderFeatureContributions([feature.commit().unwrap()]);
+
+    expect(merged.ok).toBe(false);
+    if (merged.ok) return;
+    expect(merged.error.code).toBe('render-feature-pass-order-conflict');
+  });
+});

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

@@ -0,0 +1,101 @@
+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 = (compute: boolean): Readonly<RhiCaps> =>
+  ({ backendKind: 'null', compute }) as unknown as RhiCaps;
+
+function feature(
+  mode: 'healthy' | 'failed',
+  recoverCalls: number[],
+): RenderFeature<{ readonly ready: true }> {
+  return {
+    identity: `synthetic.diagnostics.${mode}`,
+    requiredCapabilities: ['compute'],
+    extract: () => ok({ ready: true }),
+    prepare: () =>
+      mode === 'failed'
+        ? err(
+            new RenderFeatureStageFailedError(
+              `synthetic.diagnostics.${mode}`,
+              0,
+              'prepare',
+              'next-frame',
+            ),
+          )
+        : ok(undefined),
+    contribute: () => ok(undefined),
+    recover: () => {
+      recoverCalls.push(1);
+      return ok(undefined);
+    },
+  };
+}
+
+describe('render feature prepared diagnostics', () => {
+  it('projects disabled and failed states with code-directed recovery data', () => {
+    const recoverCalls: number[] = [];
+    const disabledHost = createRenderFeatureHost([feature('healthy', recoverCalls)]).unwrap();
+    runRenderFeatureFrame(disabledHost, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      caps: caps(false),
+    });
+    const disabled = disabledHost.diagnostics()[0];
+    expect(disabled).toMatchObject({
+      status: 'disabled',
+      latestError: {
+        code: 'render-feature-capability-missing',
+        detail: { capability: 'compute' },
+      },
+    });
+    expect(disabled?.latestError?.expected).toContain('compute');
+    expect(disabled?.latestError?.hint).toContain('disable');
+
+    const failedHost = createRenderFeatureHost([feature('failed', recoverCalls)]).unwrap();
+    runRenderFeatureFrame(failedHost, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      caps: caps(true),
+    });
+    const failed = failedHost.diagnostics()[0];
+    expect(failed).toMatchObject({
+      status: 'failed',
+      latestError: {
+        code: 'render-feature-stage-failed',
+        detail: { stage: 'prepare', recovery: 'next-frame' },
+      },
+    });
+    expect(failed?.latestError?.hint).toContain('next frame');
+  });
+
+  it('makes disposed diagnostics terminal and keeps repeated lifecycle calls side-effect free', () => {
+    const recoverCalls: number[] = [];
+    const host = createRenderFeatureHost([feature('healthy', recoverCalls)]).unwrap();
+    expect(host.recover({ frameNumber: 2, caps: caps(true) })).toEqual(ok(undefined));
+    expect(host.recover({ frameNumber: 2, caps: caps(true) })).toEqual(ok(undefined));
+    expect(recoverCalls).toHaveLength(1);
+
+    expect(host.dispose()).toEqual(ok(undefined));
+    expect(host.dispose()).toEqual(ok(undefined));
+    const diagnostics = host.diagnostics()[0];
+    expect(diagnostics).toMatchObject({
+      identity: 'synthetic.diagnostics.healthy',
+      status: 'disposed',
+    });
+    const recoverAfterDispose = host.recover({ frameNumber: 3, caps: caps(true) });
+    expect(recoverAfterDispose.ok).toBe(false);
+    if (!recoverAfterDispose.ok) {
+      expect(recoverAfterDispose.error).toMatchObject({
+        code: 'render-feature-stage-failed',
+        detail: { stage: 'recover', recovery: 'registration' },
+      });
+      expect(recoverAfterDispose.error.hint).toContain('registration');
+    }
+  });
+});

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

@@ -0,0 +1,82 @@
+import type {
+  PreparedKind,
+  RenderFeatureErrorCode,
+  RenderFeatureErrorDescriptor,
+  RenderFeatureRecovery,
+} from '../index';
+
+function describeGraphicsError(error: RenderFeatureErrorDescriptor): string {
+  switch (error.code) {
+    case 'render-feature-preparation-failed':
+      return `${error.detail.operation}:${error.detail.resourceKind}:${error.detail.resourceName}`;
+    case 'render-feature-prepared-state-mismatch':
+      switch (error.detail.reason) {
+        case 'missing-prepared-state':
+          return error.detail.missingResource;
+        case 'foreign-feature':
+          return error.detail.actualFeatureIdentity;
+        case 'foreign-kind':
+          return `${error.detail.expectedKind}:${error.detail.actualKind}`;
+        case 'generation-mismatch':
+          return `${error.detail.expectedGeneration}:${error.detail.actualGeneration}`;
+        case 'layout-mismatch':
+          return `${error.detail.expectedLayout}:${error.detail.actualLayout}`;
+        case 'format-mismatch':
+          return `${error.detail.expectedFormat}:${error.detail.actualFormat}`;
+      }
+      return 'prepared-state-mismatch';
+    case 'render-feature-draw-recording-failed':
+      return `${error.detail.operation}:${error.detail.backendReason}`;
+    case 'render-feature-registration-conflict':
+      return error.detail.featureIdentity;
+    case 'render-feature-stage-failed':
+      return error.detail.featureIdentity;
+    case 'render-feature-capability-missing':
+      return error.detail.featureIdentity;
+    case 'render-feature-pass-order-conflict':
+      return error.detail.featureIdentity;
+  }
+}
+
+function renderGraphicsCodeLabel(code: RenderFeatureErrorCode): string {
+  switch (code) {
+    case 'render-feature-registration-conflict':
+      return code;
+    case 'render-feature-stage-failed':
+      return code;
+    case 'render-feature-capability-missing':
+      return code;
+    case 'render-feature-pass-order-conflict':
+      return code;
+    case 'render-feature-preparation-failed':
+      return code;
+    case 'render-feature-prepared-state-mismatch':
+      return code;
+    case 'render-feature-draw-recording-failed':
+      return code;
+  }
+}
+
+function describeRecovery(recovery: RenderFeatureRecovery): string {
+  switch (recovery) {
+    case 'next-frame':
+      return recovery;
+    case 'renderer-recover':
+      return recovery;
+    case 'registration':
+      return recovery;
+  }
+}
+
+const preparedKinds: readonly PreparedKind[] = [
+  'pipeline',
+  'bindings',
+  'vertex-data',
+  'index-data',
+  'attachment',
+];
+
+void describeGraphicsError;
+void renderGraphicsCodeLabel;
+void describeRecovery;
+void preparedKinds;

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

@@ -0,0 +1,141 @@
+import type {
+  RenderError,
+  RenderFeature,
+  RenderFeatureErrorDescriptor,
+  RenderFeaturePreparedRef,
+} from '@forgeax/engine-render';
+import { ok, type Result } from '@forgeax/engine-types';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+type PreparedFrame = {
+  readonly items: readonly unknown[];
+};
+
+interface PreparedGraphicsRefs {
+  readonly pipeline: RenderFeaturePreparedRef<'pipeline'>;
+  readonly bindings: RenderFeaturePreparedRef<'bindings'>;
+  readonly vertexData: RenderFeaturePreparedRef<'vertex-data'>;
+}
+
+function describeRenderFeatureError(error: RenderFeatureErrorDescriptor): string {
+  switch (error.code) {
+    case 'render-feature-registration-conflict':
+      return `${error.detail.featureIdentity}:${error.detail.conflictingOrder}`;
+    case 'render-feature-stage-failed':
+      return `${error.detail.featureIdentity}:${error.detail.stage}:${error.detail.recovery}`;
+    case 'render-feature-capability-missing':
+      return `${error.detail.featureIdentity}:${error.detail.capability}`;
+    case 'render-feature-pass-order-conflict':
+      return `${error.detail.passIdentity}:${error.detail.dependencyIdentity}`;
+    case 'render-feature-preparation-failed':
+      return `${error.detail.resourceKind}:${error.detail.resourceName}`;
+    case 'render-feature-prepared-state-mismatch':
+      switch (error.detail.reason) {
+        case 'missing-prepared-state':
+          return `${error.detail.resourceKind}:${error.detail.missingResource}`;
+        case 'foreign-feature':
+          return `${error.detail.expectedFeatureIdentity}:${error.detail.actualFeatureIdentity}`;
+        case 'foreign-kind':
+          return `${error.detail.expectedKind}:${error.detail.actualKind}`;
+        case 'generation-mismatch':
+          return `${error.detail.expectedGeneration}:${error.detail.actualGeneration}`;
+        case 'layout-mismatch':
+          return `${error.detail.expectedLayout}:${error.detail.actualLayout}`;
+        case 'format-mismatch':
+          return `${error.detail.expectedFormat}:${error.detail.actualFormat}`;
+      }
+      break;
+    case 'render-feature-draw-recording-failed':
+      return `${error.detail.resourceKind}:${error.detail.backendReason}`;
+  }
+}
+
+function publicPreparedRecipe(frame: PreparedFrame): RenderFeature<PreparedFrame> {
+  let prepared: PreparedGraphicsRefs | undefined;
+  const feature: RenderFeature<PreparedFrame> = {
+    identity: 'docs.prepared-graphics',
+    extract: () => ok(frame),
+    prepare: (data, context): Result<void, RenderError> => {
+      const pipeline = context.graphics.preparePipeline('docs.pipeline', {
+        shader: 'docs.shader',
+        vertexLayout: 'particle-billboard',
+        colorFormats: ['rgba8unorm-srgb'],
+      });
+      if (!pipeline.ok) return pipeline;
+      const bindings = context.graphics.prepareBindings('docs.bindings', {
+        pipeline: pipeline.value,
+        values: { itemCount: data.items.length },
+      });
+      if (!bindings.ok) return bindings;
+      const vertexData = context.graphics.prepareVertexData('docs.vertices', {
+        layout: 'particle-billboard',
+        data: new Float32Array(),
+      });
+      if (!vertexData.ok) return vertexData;
+      prepared = {
+        pipeline: pipeline.value,
+        bindings: bindings.value,
+        vertexData: vertexData.value,
+      };
+      return ok(undefined);
+    },
+    contribute: (data, context): Result<void, RenderError> => {
+      if (prepared === undefined) {
+        return ok(undefined);
+      }
+      return context.staging.addGraphicsPass('docs.prepared-pass', {
+        attachments: {
+          colors: [
+            {
+              resource: 'swap-chain',
+              format: 'rgba8unorm-srgb',
+              loadOp: 'load',
+              storeOp: 'store',
+            },
+          ],
+        },
+        draws: [
+          {
+            kind: 'draw',
+            pipeline: prepared.pipeline,
+            bindings: [prepared.bindings],
+            vertexData: [{ slot: 0, resource: prepared.vertexData }],
+            command: {
+              vertexCount: data.items.length * 0,
+              instanceCount: 1,
+            },
+          },
+        ],
+      });
+    },
+  };
+  return feature;
+}
+
+describe('public prepared graphics recipe', () => {
+  it('keeps the public imports and callback inference type-safe', () => {
+    const frame: PreparedFrame = { items: [] };
+    expectTypeOf(publicPreparedRecipe).parameter(0).toMatchTypeOf<PreparedFrame>();
+    expectTypeOf(publicPreparedRecipe).returns.toMatchTypeOf<RenderFeature<PreparedFrame>>();
+    expect(typeof publicPreparedRecipe).toBe('function');
+    expect(frame.items).toHaveLength(0);
+  });
+
+  it('keeps structured error fields available without message parsing', () => {
+    const error: RenderFeatureErrorDescriptor = {
+      code: 'render-feature-stage-failed',
+      expected: "feature 'docs.prepared-graphics' completes its prepare stage without an error",
+      hint: "correct 'docs.prepared-graphics' prepare data and retry on the next frame",
+      detail: {
+        featureIdentity: 'docs.prepared-graphics',
+        order: 0,
+        stage: 'prepare',
+        recovery: 'next-frame',
+      },
+    };
+    expect(describeRenderFeatureError(error)).toBe('docs.prepared-graphics:prepare:next-frame');
+    expect(error.expected).toContain('prepare');
+    expect(error.hint).toContain('next frame');
+    expect(error.detail.recovery).toBe('next-frame');
+  });
+});