@forgeax/engine-render 0.1.2

package/src/__tests__/prepared-graphics-capability.unit.test.ts

@@ -0,0 +1,140 @@
+import type { RhiCaps } from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { createRenderFeatureHost, runRenderFeatureFrame } from '../features/host';
+import type {
+  RenderFeatureDrawRecord,
+  RenderFeaturePreparedRef,
+} from '../features/prepared-graphics';
+import type { RenderFeature } from '../features/types';
+import { describeIblCapability } from '../ibl/cubemap-projection';
+
+const supportedCaps: Readonly<RhiCaps> = {
+  backendKind: 'null',
+  compute: true,
+  timestampQuery: false,
+  timestampPeriodNanoseconds: null,
+  indirectDrawing: false,
+  textureCompressionBc: false,
+} as RhiCaps;
+
+const missingCaps: Readonly<RhiCaps> = { ...supportedCaps, compute: false };
+
+function preparedFeature(): RenderFeature<{ readonly draw: RenderFeatureDrawRecord }> {
+  let pipeline: RenderFeaturePreparedRef<'pipeline'> | undefined;
+  let bindings: RenderFeaturePreparedRef<'bindings'> | undefined;
+  let vertices: RenderFeaturePreparedRef<'vertex-data'> | undefined;
+
+  return {
+    identity: 'synthetic.capability',
+    requiredCapabilities: ['compute'],
+    extract: () =>
+      ok({
+        draw: {
+          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 },
+        },
+      }),
+    prepare: (_data, context) => {
+      const preparedPipeline = context.graphics.preparePipeline('pipeline', {
+        shader: 'synthetic.shader',
+        vertexLayout: 'position',
+        colorFormats: ['rgba8unorm'],
+      });
+      if (!preparedPipeline.ok) return preparedPipeline;
+      const preparedBindings = context.graphics.prepareBindings('bindings', {
+        pipeline: preparedPipeline.value,
+        values: { opacity: 1 },
+      });
+      if (!preparedBindings.ok) return preparedBindings;
+      const preparedVertices = context.graphics.prepareVertexData('vertices', {
+        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 (pipeline === undefined || bindings === undefined || vertices === undefined) {
+        return ok(undefined);
+      }
+      context.staging.addResource('color', { kind: 'texture', lifetime: 'transient' });
+      return context.staging.addGraphicsPass('prepared', {
+        attachments: {
+          colors: [{ resource: 'color', format: 'rgba8unorm', loadOp: 'load', storeOp: 'store' }],
+        },
+        draws: [
+          {
+            ...data.draw,
+            pipeline,
+            bindings: [bindings],
+            vertexData: [{ slot: 0, resource: vertices }],
+          },
+        ],
+      });
+    },
+  };
+}
+
+describe('prepared graphics capability projection', () => {
+  it('projects supported capability into an accepted machine-readable operation', () => {
+    const host = createRenderFeatureHost([preparedFeature()]).unwrap();
+    const result = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      caps: supportedCaps,
+    });
+
+    expect(result.errors).toEqual([]);
+    expect(result.contributions).toHaveLength(1);
+    expect(result.contributions[0]?.passes[0]?.graphicsState).toMatchObject({
+      capabilityAvailable: true,
+      generation: 0,
+    });
+    expect(host.diagnostics()[0]?.status).toBe('active');
+  });
+
+  it('returns a structured capability failure without a silent operation', () => {
+    const host = createRenderFeatureHost([preparedFeature()]).unwrap();
+    const result = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      caps: missingCaps,
+    });
+
+    expect(result.contributions).toEqual([]);
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0]).toMatchObject({
+      code: 'render-feature-capability-missing',
+      expected: expect.stringContaining('compute'),
+      hint: expect.stringContaining('disable'),
+      detail: {
+        featureIdentity: 'synthetic.capability',
+        capability: 'compute',
+      },
+    });
+    expect(host.diagnostics()[0]?.status).toBe('disabled');
+  });
+
+  it('marks missing rgba16float renderability as degraded with a white-cube artifact', () => {
+    const report = describeIblCapability({ rgba16floatRenderable: false });
+
+    expect(report).toMatchObject({
+      capabilityStatus: 'degraded',
+      executionStatus: 'notExecuted',
+      verdict: 'failed',
+      fallbackArtifact: 'white-cube',
+      rgba16floatRenderable: false,
+    });
+    expect(report.expectedImpact).toContain('HDR');
+    expect(report.hint).toContain('rgba16floatRenderable');
+  });
+});

package/src/__tests__/prepared-graphics-generation.unit.test.ts

@@ -0,0 +1,175 @@
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { createRenderFeatureHost, runRenderFeatureFrame } from '../features/host';
+import type {
+  RenderFeatureDrawRecord,
+  RenderFeatureGraphicsPassDescriptor,
+  RenderFeaturePreparedGraphicsState,
+  RenderFeaturePreparedRef,
+} from '../features/prepared-graphics';
+import { validateRenderFeatureGraphicsPass } from '../features/prepared-graphics';
+import { createPreparedGraphicsStore } from '../features/prepared-graphics-store';
+import { createRenderFeatureTarget } from '../features/targets';
+import type { RenderFeature } from '../features/types';
+
+function feature(): RenderFeature<{ readonly ready: true }> {
+  let pipeline: { readonly kind: 'pipeline'; readonly generation: number } | undefined;
+  return {
+    identity: 'synthetic.generation',
+    extract: () => ok({ ready: true }),
+    prepare: (_data, context) => {
+      const result = context.graphics.preparePipeline('pipeline', {
+        shader: 'synthetic.shader',
+        vertexLayout: 'position',
+        colorFormats: ['rgba8unorm'],
+      });
+      if (!result.ok) return result;
+      pipeline = result.value;
+      return ok(undefined);
+    },
+    contribute: () => {
+      expect(pipeline?.kind).toBe('pipeline');
+      return ok(undefined);
+    },
+  };
+}
+
+function ref<Kind extends 'pipeline' | 'bindings'>(
+  kind: Kind,
+  generation = 5,
+): RenderFeaturePreparedRef<Kind> {
+  return { kind, generation };
+}
+
+const noVertexPipeline = ref('pipeline');
+const noVertexBindings = ref('bindings');
+const noVertexColor = createRenderFeatureTarget({
+  kind: 'scene-color',
+  format: 'rgba8unorm',
+  sampleCount: 1,
+});
+const noVertexDepth = createRenderFeatureTarget({
+  kind: 'scene-depth',
+  format: 'depth24plus',
+  sampleCount: 1,
+});
+
+const noVertexDraw: RenderFeatureDrawRecord = {
+  kind: 'draw',
+  pipeline: noVertexPipeline,
+  bindings: [noVertexBindings],
+  vertexData: [],
+  vertexLayout: 'none',
+  command: { vertexCount: 3, instanceCount: 1 },
+};
+
+const noVertexPass: RenderFeatureGraphicsPassDescriptor = {
+  attachments: {
+    colors: [
+      { resource: noVertexColor, format: noVertexColor.format, loadOp: 'load', storeOp: 'store' },
+    ],
+    depthStencil: {
+      resource: noVertexDepth,
+      format: noVertexDepth.format,
+      depthLoadOp: 'load',
+      depthStoreOp: 'store',
+    },
+  },
+  draws: [noVertexDraw],
+};
+
+const noVertexState: RenderFeaturePreparedGraphicsState = {
+  capabilityAvailable: true,
+  generation: 5,
+  attachments: [
+    { resource: noVertexColor, format: noVertexColor.format },
+    { resource: noVertexDepth, format: noVertexDepth.format },
+  ],
+  pipeline: noVertexPipeline,
+  bindings: [noVertexBindings],
+  vertexData: [],
+  indexData: [],
+};
+
+describe('prepared graphics generation ownership', () => {
+  it('accepts only the explicit no-vertex draw shape and fences its generation', () => {
+    const accepted = validateRenderFeatureGraphicsPass(
+      'synthetic.no-vertex',
+      noVertexPass,
+      noVertexState,
+    );
+    expect(accepted.ok).toBe(true);
+    if (accepted.ok) expect(accepted.value.acceptedDrawCount).toBe(1);
+
+    const { vertexLayout: _marker, ...drawWithoutMarker } = noVertexDraw;
+    void _marker;
+    const missingMarker = validateRenderFeatureGraphicsPass(
+      'synthetic.no-vertex',
+      { ...noVertexPass, draws: [drawWithoutMarker] },
+      noVertexState,
+    );
+    expect(missingMarker.ok).toBe(false);
+
+    const stalePipeline = validateRenderFeatureGraphicsPass('synthetic.no-vertex', noVertexPass, {
+      ...noVertexState,
+      pipeline: ref('pipeline', 6),
+      generation: 5,
+    });
+    expect(stalePipeline.ok).toBe(false);
+
+    const missingBindings = validateRenderFeatureGraphicsPass('synthetic.no-vertex', noVertexPass, {
+      ...noVertexState,
+      bindings: [],
+    });
+    expect(missingBindings.ok).toBe(false);
+  });
+
+  it('rejects stale generation and foreign owner or kind references', () => {
+    const store = createPreparedGraphicsStore();
+    const owner = store.beginFrame('synthetic.owner', 4);
+    const foreign = store.beginFrame('synthetic.foreign', 4);
+    const old = owner.prepare('pipeline', 'pipeline', { signature: 'pipeline:v1' });
+    const foreignRef = foreign.prepare('pipeline', 'pipeline', { signature: 'pipeline:v1' });
+    expect(old.ok).toBe(true);
+    expect(foreignRef.ok).toBe(true);
+    owner.commit();
+    foreign.commit();
+
+    const next = store.beginFrame('synthetic.owner', 5);
+    const nextRef = next.prepare('pipeline', 'pipeline', { signature: 'pipeline:v2' });
+    expect(nextRef.ok).toBe(true);
+    if (old.ok && foreignRef.ok && nextRef.ok) {
+      expect(next.owns(old.value)).toBe(false);
+      expect(next.owns(foreignRef.value)).toBe(false);
+      expect(nextRef.value).not.toBe(old.value);
+      expect(nextRef.value.generation).toBe(5);
+    }
+    expect(next.graphicsState(true, []).generation).toBe(5);
+  });
+
+  it('keeps registration while replacing prepared state after a pipeline generation switch', () => {
+    const host = createRenderFeatureHost([feature()]).unwrap();
+    const before = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      generation: 1,
+      caps: { backendKind: 'null' } as never,
+    });
+    const after = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 2,
+      generation: 2,
+      caps: { backendKind: 'null' } as never,
+    });
+
+    expect(before.errors).toEqual([]);
+    expect(after.errors).toEqual([]);
+    expect(before.contributions).toEqual([]);
+    expect(after.contributions).toEqual([]);
+    expect(host.features).toHaveLength(1);
+    expect(host.features[0]?.identity).toBe('synthetic.generation');
+    expect(host.diagnostics()[0]?.status).toBe('active');
+  });
+});

package/src/__tests__/prepared-graphics-lifecycle.unit.test.ts

@@ -0,0 +1,206 @@
+import type { RhiCaps } from '@forgeax/engine-rhi';
+import { err, ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import {
+  createRenderFeatureHost,
+  runRenderFeatureFrame,
+  settlePreparedGraphicsCompletion,
+} from '../features/host';
+import { createPreparedGraphicsStore } from '../features/prepared-graphics-store';
+import type { RenderFeature } from '../features/types';
+
+const caps = { backendKind: 'null' } as unknown as Readonly<RhiCaps>;
+
+function preparedFeature(recoverCalls: number[]): RenderFeature<{ readonly ready: true }> {
+  let pipeline: { readonly kind: 'pipeline'; readonly generation: number } | undefined;
+  let bindings: { readonly kind: 'bindings'; readonly generation: number } | undefined;
+  let vertices: { readonly kind: 'vertex-data'; readonly generation: number } | undefined;
+  return {
+    identity: 'synthetic.lifecycle',
+    extract: () => ok({ ready: true }),
+    prepare: (_data, context) => {
+      const result = context.graphics.preparePipeline('pipeline', {
+        shader: 'synthetic.shader',
+        vertexLayout: 'position',
+        colorFormats: ['rgba8unorm'],
+      });
+      if (!result.ok) return result;
+      pipeline = result.value;
+      const bindingsResult = context.graphics.prepareBindings('bindings', {
+        pipeline: result.value,
+        values: {},
+      });
+      if (!bindingsResult.ok) return bindingsResult;
+      bindings = bindingsResult.value;
+      const verticesResult = context.graphics.prepareVertexData('vertices', {
+        layout: 'position',
+        data: [0, 0, 0],
+      });
+      if (!verticesResult.ok) return verticesResult;
+      vertices = verticesResult.value;
+      return ok(undefined);
+    },
+    contribute: (_data, context) => {
+      if (pipeline === undefined || bindings === undefined || vertices === undefined) {
+        return err(new Error('prepared state missing') as never);
+      }
+      context.staging.addResource('color', { kind: 'texture', lifetime: 'transient' });
+      return context.staging.addGraphicsPass('prepared', {
+        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 },
+          },
+        ],
+      });
+    },
+    recover: () => {
+      recoverCalls.push(1);
+      return ok(undefined);
+    },
+  };
+}
+
+describe('prepared graphics lifecycle ownership', () => {
+  it('aborts partial preparation without changing committed state', () => {
+    const store = createPreparedGraphicsStore();
+    const initial = store.beginFrame('synthetic.lifecycle', 1);
+    initial.prepare('pipeline', 'pipeline', { signature: 'v1' });
+    initial.commit();
+
+    const failed = store.beginFrame('synthetic.lifecycle', 2);
+    failed.prepare('bindings', 'bindings', { signature: 'v2' });
+    failed.abort();
+
+    expect(store.snapshot('synthetic.lifecycle')).toMatchObject({
+      generation: 1,
+      items: [{ kind: 'pipeline', name: 'pipeline' }],
+    });
+    expect(failed.overlayItems()).toEqual([]);
+  });
+
+  it('re-prepares after recovery and makes repeated recovery idempotent', () => {
+    const recoverCalls: number[] = [];
+    const host = createRenderFeatureHost([preparedFeature(recoverCalls)]).unwrap();
+    const first = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      generation: 1,
+      caps,
+    });
+    expect(first.errors).toEqual([]);
+
+    expect(host.recover({ frameNumber: 2, caps })).toEqual(ok(undefined));
+    expect(host.recover({ frameNumber: 2, caps })).toEqual(ok(undefined));
+    const recovered = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 3,
+      generation: 2,
+      caps,
+    });
+
+    expect(recoverCalls).toHaveLength(1);
+    expect(recovered.errors).toEqual([]);
+    expect(host.features[0]?.identity).toBe('synthetic.lifecycle');
+    expect(host.diagnostics()[0]?.status).toBe('active');
+  });
+
+  it('releases registered resources once and keeps dispose terminal', () => {
+    const host = createRenderFeatureHost([preparedFeature([])]).unwrap();
+    let releases = 0;
+    host.registerResource('synthetic.lifecycle', {
+      handle: {} as never,
+      release: () => {
+        releases += 1;
+        return ok(undefined);
+      },
+    });
+
+    expect(host.dispose()).toEqual(ok(undefined));
+    expect(host.dispose()).toEqual(ok(undefined));
+    expect(releases).toBe(1);
+    expect(host.recover({ frameNumber: 4, caps }).ok).toBe(false);
+    expect(host.diagnostics()[0]?.status).toBe('disposed');
+  });
+
+  it('releases a prepared batch that never reached queue submission during recovery', () => {
+    const host = createRenderFeatureHost([preparedFeature([])]).unwrap();
+    let releases = 0;
+    const lease = {
+      release: () => {
+        releases += 1;
+        return ok(undefined);
+      },
+    };
+    const batch = host.retainPreparedGraphics('synthetic.lifecycle', [lease]).unwrap();
+
+    expect(host.recover({ frameNumber: 5, caps })).toEqual(ok(undefined));
+    expect(releases).toBe(1);
+    expect(host.retirePreparedGraphics([batch])).toEqual(ok(undefined));
+    expect(releases).toBe(1);
+  });
+
+  it('keeps submitted batches alive through recovery and dispose until late completion', () => {
+    const host = createRenderFeatureHost([preparedFeature([])]).unwrap();
+    let releases = 0;
+    const lease = {
+      release: () => {
+        releases += 1;
+        return ok(undefined);
+      },
+    };
+    const batch = host.retainPreparedGraphics('synthetic.lifecycle', [lease]).unwrap();
+
+    host.markPreparedGraphicsSubmitted([batch]);
+    expect(host.recover({ frameNumber: 6, caps })).toEqual(ok(undefined));
+    expect(releases).toBe(0);
+    expect(host.dispose()).toEqual(ok(undefined));
+    expect(releases).toBe(0);
+
+    expect(host.retirePreparedGraphics([batch])).toEqual(ok(undefined));
+    expect(host.retirePreparedGraphics([batch])).toEqual(ok(undefined));
+    expect(releases).toBe(1);
+  });
+
+  it('recovers submitted batches when queue completion rejects and reports release errors', async () => {
+    const host = createRenderFeatureHost([preparedFeature([])]).unwrap();
+    let releases = 0;
+    const releaseError = new Error('prepared release failed');
+    const firstLease = {
+      release: () => {
+        releases += 1;
+        return ok(undefined);
+      },
+    };
+    const secondLease = {
+      release: () => {
+        releases += 1;
+        return err(releaseError as never);
+      },
+    };
+    const first = host.retainPreparedGraphics('synthetic.lifecycle', [firstLease]).unwrap();
+    const second = host.retainPreparedGraphics('synthetic.lifecycle', [secondLease]).unwrap();
+    host.markPreparedGraphicsSubmitted([first, second]);
+
+    const errors: unknown[] = [];
+    const completion = Promise.reject(new Error('queue completion unavailable'));
+    settlePreparedGraphicsCompletion(host, [first, second], completion, (error) => {
+      errors.push(error);
+    });
+    await completion.catch(() => undefined);
+    await Promise.resolve();
+
+    expect(releases).toBe(2);
+    expect(errors).toEqual([releaseError]);
+    expect(host.retirePreparedGraphics([first, second])).toEqual(ok(undefined));
+    expect(releases).toBe(2);
+  });
+});

package/src/__tests__/prepared-graphics-pipeline-warmup.unit.test.ts

@@ -0,0 +1,29 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const ownerSource = readFileSync(new URL('../render-system.ts', import.meta.url), 'utf8');
+
+describe('prepared graphics material pipeline warmup', () => {
+  it('does not substitute an unrelated unlit pipeline while the authored shader warms', () => {
+    const start = ownerSource.indexOf('const preparedPipeline =');
+    const end = ownerSource.indexOf('resolveBindings:', start);
+    const owner = ownerSource.slice(start, end);
+
+    expect(owner).toContain('const pipeline = preparedPipeline ?? null');
+    expect(owner).not.toContain('unlitPipeline');
+    expect(owner).toContain('err(makePreparedPipelinePendingError())');
+  });
+
+  it('keeps view-only material bindings on the canonical view group with depth', () => {
+    const declaration = ownerSource.indexOf('const preparedViewOnlyPipelines');
+    const classification = ownerSource.indexOf('preparedViewOnlyPipelines.add', declaration);
+    const bindingResolution = ownerSource.indexOf(
+      'preparedViewOnlyPipelines.has(pipeline as object)',
+      classification,
+    );
+
+    expect(declaration).toBeGreaterThan(-1);
+    expect(classification).toBeGreaterThan(declaration);
+    expect(bindingResolution).toBeGreaterThan(classification);
+  });
+});