@forgeax/engine-render 0.1.2

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

@@ -0,0 +1,180 @@
+import { rhi } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import type {
+  RenderFeatureGraphicsPassDescriptor,
+  RenderFeaturePreparedGraphicsState,
+  RenderFeaturePreparedRef,
+} from '../features/prepared-graphics';
+import type { PreparedGraphicsResolvedResource } from '../prepare/prepared-graphics-resolver';
+import {
+  type RenderFeatureGraphicsRecordingLedger,
+  recordResolvedRenderFeatureGraphicsPass,
+} from '../record/frame-targets';
+
+function ref<Kind extends RenderFeaturePreparedRef['kind']>(
+  kind: Kind,
+  generation = 3,
+): RenderFeaturePreparedRef<Kind> {
+  return Object.freeze({ kind, generation });
+}
+
+const pipeline = ref('pipeline');
+const bindings = ref('bindings');
+const vertices = ref('vertex-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: [],
+};
+
+function ledger(calls: unknown[]): RenderFeatureGraphicsRecordingLedger {
+  return {
+    pipeline: 0,
+    binding: 0,
+    vertex: 0,
+    index: 0,
+    draw: 0,
+    setPipeline: (handle) => calls.push(handle),
+    setBindGroup: (handle) => calls.push(handle),
+    setVertexBuffer: (_slot, handle) => calls.push(handle),
+    recordDraw: () => undefined,
+  };
+}
+
+describe('resolved prepared graphics recording', () => {
+  it('records current-device handles from the private resolved lookup', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const buffer = device.createBuffer({ size: 4, usage: 40 }).unwrap();
+    const shader = (
+      await rhi.createShaderModule(device, { code: 'synthetic' })
+    ).unwrap() as unknown as GPUShaderModule;
+    const pipelineHandle = device
+      .createRenderPipeline({
+        layout: 'auto',
+        vertex: { module: shader, entryPoint: 'main', buffers: [] },
+        fragment: { module: shader, entryPoint: 'main', targets: [] },
+      })
+      .unwrap();
+    const layout = device.createBindGroupLayout({ entries: [] }).unwrap();
+    const bindingsHandle = device.createBindGroup({ layout, entries: [] }).unwrap();
+    const resources = new Map<object, PreparedGraphicsResolvedResource>([
+      [pipeline, { kind: 'pipeline', reference: pipeline, handle: pipelineHandle }],
+      [bindings, { kind: 'bindings', reference: bindings, handle: bindingsHandle }],
+      [
+        vertices,
+        {
+          kind: 'vertex-data',
+          reference: vertices,
+          handle: buffer,
+          size: 4,
+          physicalUsage: 40,
+        },
+      ],
+    ]);
+    const calls: unknown[] = [];
+    const resolved = {
+      generation: 3,
+      resolve: (reference: RenderFeaturePreparedRef) => resources.get(reference),
+    };
+    const result = recordResolvedRenderFeatureGraphicsPass(
+      'synthetic.resolved',
+      pass,
+      state,
+      resolved,
+      ledger(calls),
+    );
+    expect(result).toMatchObject({ ok: true, value: { acceptedDrawCount: 1 } });
+    expect(calls).toEqual([pipelineHandle, bindingsHandle, buffer]);
+    expect(calls).not.toContain(pipeline);
+    expect(calls).not.toContain(bindings);
+    expect(calls).not.toContain(vertices);
+  });
+
+  it('rejects unresolved work before the first recording mutation', () => {
+    const calls: unknown[] = [];
+    const result = recordResolvedRenderFeatureGraphicsPass(
+      'synthetic.invalid',
+      pass,
+      state,
+      { generation: 3, resolve: () => undefined },
+      ledger(calls),
+    );
+    expect(result.ok).toBe(false);
+    expect(calls).toEqual([]);
+  });
+
+  it('forwards prepared binding dynamic offsets to the render pass', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const buffer = device.createBuffer({ size: 4, usage: 40 }).unwrap();
+    const shader = (
+      await rhi.createShaderModule(device, { code: 'synthetic' })
+    ).unwrap() as unknown as GPUShaderModule;
+    const pipelineHandle = device
+      .createRenderPipeline({
+        layout: 'auto',
+        vertex: { module: shader, entryPoint: 'main', buffers: [] },
+        fragment: { module: shader, entryPoint: 'main', targets: [] },
+      })
+      .unwrap();
+    const layout = device.createBindGroupLayout({ entries: [] }).unwrap();
+    const bindingsHandle = device.createBindGroup({ layout, entries: [] }).unwrap();
+    const resources = new Map<object, PreparedGraphicsResolvedResource>([
+      [pipeline, { kind: 'pipeline', reference: pipeline, handle: pipelineHandle }],
+      [
+        bindings,
+        {
+          kind: 'bindings',
+          reference: bindings,
+          handle: bindingsHandle,
+          dynamicOffsets: [256],
+        },
+      ],
+      [
+        vertices,
+        {
+          kind: 'vertex-data',
+          reference: vertices,
+          handle: buffer,
+          size: 4,
+          physicalUsage: 40,
+        },
+      ],
+    ]);
+    const calls: unknown[] = [];
+    const result = recordResolvedRenderFeatureGraphicsPass(
+      'synthetic.dynamic-offset',
+      pass,
+      state,
+      { generation: 3, resolve: (reference) => resources.get(reference) },
+      {
+        ...ledger(calls),
+        setBindGroupAt: (index, handle, offsets) => calls.push([index, handle, offsets]),
+      },
+    );
+
+    expect(result).toMatchObject({ ok: true });
+    expect(calls).toContainEqual([0, bindingsHandle, [256]]);
+  });
+});

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

@@ -0,0 +1,287 @@
+import { type BindGroup, type RenderPipeline, RhiError } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import type { RenderFeatureGpuBufferRef } from '../features/prepared-gpu-work';
+import {
+  createPreparedGraphicsStore,
+  type PreparedGraphicsItem,
+} from '../features/prepared-graphics-store';
+import { createRenderFeatureTarget } from '../features/targets';
+import {
+  createPreparedGraphicsResolver,
+  type PreparedGraphicsResolverInput,
+} from '../prepare/prepared-graphics-resolver';
+
+async function device() {
+  const adapter = (await rhi.requestAdapter()).unwrap();
+  return (await adapter.requestDevice()).unwrap();
+}
+
+function resultMap(items: readonly PreparedGraphicsItem[]): Map<object, PreparedGraphicsItem> {
+  return new Map(items.map((item) => [item.reference, item]));
+}
+
+function failure<T>(result: Result<T, unknown>): {
+  readonly code: string;
+  readonly detail?: { readonly reason: string };
+} {
+  if (result.ok) throw new Error('expected a resolver failure');
+  return result.error as {
+    readonly code: string;
+    readonly detail?: { readonly reason: string };
+  };
+}
+
+describe('prepared graphics resolver', () => {
+  it('lets the render owner decide whether a scene target is a deferred binding', async () => {
+    const currentDevice = await device();
+    const store = createPreparedGraphicsStore();
+    const transaction = store.beginFrame('resolver.scene-target', 1);
+    const pipeline = transaction.prepare('pipeline', 'forward', {
+      shader: 'synthetic::view-only',
+      vertexLayout: 'position',
+      colorFormats: ['rgba8unorm'],
+    });
+    const bindings = transaction.prepare('bindings', 'view', {
+      pipeline: pipeline.unwrap(),
+      values: {
+        sceneDepth: createRenderFeatureTarget({
+          kind: 'scene-depth',
+          format: 'depth24plus-stencil8',
+          sampleCount: 1,
+        }),
+      },
+    });
+    transaction.commit().unwrap();
+    const lookup = resultMap(store.snapshot('resolver.scene-target').items);
+    const resolvedView = {} as BindGroup;
+    const resolveBindings = vi.fn(() => ok(resolvedView));
+    const resolver = createPreparedGraphicsResolver({
+      device: currentDevice,
+      generation: 1,
+      capabilityAvailable: true,
+      lookup: (reference) => lookup.get(reference),
+      resolvePipeline: () => ok({} as RenderPipeline),
+      resolveBindings,
+    });
+
+    const result = resolver.resolve(bindings.unwrap());
+
+    expect(result.ok && result.value.handle).toBe(resolvedView);
+    expect(resolveBindings).toHaveBeenCalledOnce();
+  });
+
+  it('releases producer binding resources exactly once', async () => {
+    const currentDevice = await device();
+    const store = createPreparedGraphicsStore();
+    const transaction = store.beginFrame('resolver.binding-lifetime', 1);
+    const pipeline = transaction.prepare('pipeline', 'forward', {
+      shader: 'synthetic::forward',
+      vertexLayout: 'position',
+      colorFormats: ['rgba8unorm'],
+    });
+    const bindings = transaction.prepare('bindings', 'material', {
+      pipeline: pipeline.unwrap(),
+      values: { group: 1 },
+    });
+    transaction.commit().unwrap();
+    const lookup = resultMap(store.snapshot('resolver.binding-lifetime').items);
+    const release = vi.fn(() => ok(undefined));
+    const resolver = createPreparedGraphicsResolver({
+      device: currentDevice,
+      generation: 1,
+      capabilityAvailable: true,
+      lookup: (reference) => lookup.get(reference),
+      resolvePipeline: () => ok({} as RenderPipeline),
+      resolveBindings: () => ok({ handle: {} as BindGroup, release }),
+    });
+
+    expect(resolver.resolve(bindings.unwrap()).ok).toBe(true);
+    expect(resolver.release().ok).toBe(true);
+    expect(resolver.release().ok).toBe(true);
+    expect(release).toHaveBeenCalledTimes(1);
+  });
+
+  it('maps normalized operations to current-device handles without using refs as handles', async () => {
+    const currentDevice = await device();
+    const store = createPreparedGraphicsStore();
+    const transaction = store.beginFrame('resolver.feature', 7);
+    const pipeline = transaction.prepare('pipeline', 'forward', {
+      shader: 'synthetic::forward',
+      vertexLayout: 'position',
+      colorFormats: ['rgba8unorm'],
+    });
+    const bindings = transaction.prepare('bindings', 'forward', {
+      pipeline: pipeline.unwrap(),
+      values: { tint: [1, 0, 0, 1] },
+    });
+    const vertex = transaction.prepare('vertex-data', 'triangle', {
+      layout: 'position',
+      data: new Float32Array([0, 1, 2]),
+    });
+    const index = transaction.prepare('index-data', 'triangle', {
+      format: 'uint16',
+      data: new Uint16Array([0, 1, 2]),
+    });
+    const externalBuffer = currentDevice.createBuffer({ size: 16, usage: 56 }).unwrap();
+    const externalRef = Object.freeze({
+      name: 'external-geometry',
+      generation: 7,
+    }) as RenderFeatureGpuBufferRef;
+    const externalVertex = transaction.prepare('vertex-data', 'external-vertices', {
+      layout: 'position',
+      buffer: externalRef,
+    });
+    const externalIndex = transaction.prepare('index-data', 'external-indices', {
+      format: 'uint16',
+      buffer: externalRef,
+    });
+    expect(transaction.commit().ok).toBe(true);
+
+    const items = store.snapshot('resolver.feature').items;
+    const lookup = resultMap(items);
+    const shader = (
+      await rhi.createShaderModule(currentDevice, { code: 'synthetic' })
+    ).unwrap() as unknown as GPUShaderModule;
+    const input: PreparedGraphicsResolverInput = {
+      device: currentDevice,
+      generation: 7,
+      capabilityAvailable: true,
+      lookup: (ref) => lookup.get(ref),
+      resolvePipeline: () =>
+        currentDevice.createRenderPipeline({
+          layout: 'auto',
+          vertex: { module: shader, entryPoint: 'main', buffers: [] },
+          fragment: { module: shader, entryPoint: 'main', targets: [] },
+        }) as Result<RenderPipeline, never>,
+      resolveBindings: () => {
+        const layout = currentDevice.createBindGroupLayout({ entries: [] }).unwrap();
+        return currentDevice.createBindGroup({ layout, entries: [] }) as Result<BindGroup, never>;
+      },
+      resolveGpuBuffer: (reference) =>
+        reference === externalRef
+          ? { buffer: externalBuffer, size: 64, physicalUsage: 0x0020 }
+          : undefined,
+    };
+    const resolver = createPreparedGraphicsResolver(input);
+    const pipelineRef = pipeline.unwrap();
+    const bindingsRef = bindings.unwrap();
+    const vertexRef = vertex.unwrap();
+    const indexRef = index.unwrap();
+    const resolvedPipeline = resolver.resolve(pipelineRef);
+    const resolvedBindings = resolver.resolve(bindingsRef);
+    const resolvedVertex = resolver.resolve(vertexRef);
+    const resolvedIndex = resolver.resolve(indexRef);
+    const resolvedExternalVertex = resolver.resolve(externalVertex.unwrap());
+    const resolvedExternalIndex = resolver.resolve(externalIndex.unwrap());
+
+    expect(resolvedPipeline.ok).toBe(true);
+    expect(resolvedBindings.ok).toBe(true);
+    expect(resolvedVertex.ok).toBe(true);
+    expect(resolvedIndex.ok).toBe(true);
+    expect(resolvedExternalVertex.ok && resolvedExternalVertex.value.handle).toBe(externalBuffer);
+    expect(resolvedExternalIndex.ok && resolvedExternalIndex.value.handle).toBe(externalBuffer);
+    expect(resolvedPipeline.ok && resolvedPipeline.value.handle).not.toBe(pipelineRef);
+    expect(resolvedBindings.ok && resolvedBindings.value.handle).not.toBe(bindingsRef);
+    expect(resolvedVertex.ok && resolvedVertex.value.handle).not.toBe(vertexRef);
+    expect(resolvedIndex.ok && resolvedIndex.value.handle).not.toBe(indexRef);
+  });
+
+  it('rejects capability, resolution, stale, and forged refs before record mutation', async () => {
+    const currentDevice = await device();
+    const store = createPreparedGraphicsStore();
+    const transaction = store.beginFrame('resolver.failure', 3);
+    const pipeline = transaction.prepare('pipeline', 'forward', {
+      shader: 'synthetic::forward',
+      vertexLayout: 'position',
+      colorFormats: ['rgba8unorm'],
+    });
+    expect(transaction.commit().ok).toBe(true);
+    const lookup = resultMap(store.snapshot('resolver.failure').items);
+    let resolveCalls = 0;
+    const base: PreparedGraphicsResolverInput = {
+      device: currentDevice,
+      generation: 3,
+      capabilityAvailable: true,
+      lookup: (ref) => lookup.get(ref),
+      resolvePipeline: () => {
+        resolveCalls += 1;
+        return ok({} as RenderPipeline);
+      },
+      resolveBindings: () => ok({} as BindGroup),
+    };
+
+    const pipelineRef = pipeline.unwrap();
+    const unavailable = createPreparedGraphicsResolver({
+      ...base,
+      capabilityAvailable: false,
+    }).resolve(pipelineRef);
+    expect(unavailable.ok).toBe(false);
+    expect(failure(unavailable).code).toBe('render-feature-preparation-failed');
+    expect(resolveCalls).toBe(0);
+
+    const stale = createPreparedGraphicsResolver({ ...base, generation: 4 }).resolve(pipelineRef);
+    expect(stale.ok).toBe(false);
+    const staleError = failure(stale);
+    expect(staleError.code).toBe('render-feature-prepared-state-mismatch');
+    expect(staleError.detail?.reason).toBe('generation-mismatch');
+    expect(resolveCalls).toBe(0);
+
+    const forged = createPreparedGraphicsResolver(base).resolve({
+      kind: 'pipeline',
+      generation: 3,
+    });
+    expect(forged.ok).toBe(false);
+    const forgedError = failure(forged);
+    expect(forgedError.code).toBe('render-feature-prepared-state-mismatch');
+    expect(forgedError.detail?.reason).toBe('missing-prepared-state');
+    expect(resolveCalls).toBe(0);
+
+    const failed = createPreparedGraphicsResolver({
+      ...base,
+      resolvePipeline: () => {
+        resolveCalls += 1;
+        return ok(undefined as never);
+      },
+    }).resolve(pipelineRef);
+    expect(failed.ok).toBe(false);
+    expect(failure(failed).code).toBe('render-feature-preparation-failed');
+    expect(resolveCalls).toBe(1);
+  });
+
+  it('preserves asynchronous pipeline warm-up as the graph-level pending reason', async () => {
+    const currentDevice = await device();
+    const store = createPreparedGraphicsStore();
+    const transaction = store.beginFrame('resolver.warmup', 5);
+    const pipeline = transaction.prepare('pipeline', 'forward', {
+      shader: 'synthetic::forward',
+      vertexLayout: 'position',
+      colorFormats: ['rgba8unorm'],
+    });
+    expect(transaction.commit().ok).toBe(true);
+    const lookup = resultMap(store.snapshot('resolver.warmup').items);
+
+    const pending = createPreparedGraphicsResolver({
+      device: currentDevice,
+      generation: 5,
+      capabilityAvailable: true,
+      lookup: (ref) => lookup.get(ref),
+      resolvePipeline: () =>
+        err(
+          new RhiError({
+            code: 'rhi-not-available',
+            expected: 'asynchronous shader module warm-up to finish',
+            hint: 'retry on the next frame',
+          }),
+        ),
+      resolveBindings: () => ok({} as BindGroup),
+    }).resolve(pipeline.unwrap());
+
+    expect(pending.ok).toBe(false);
+    expect(failure(pending)).toMatchObject({
+      code: 'render-feature-preparation-failed',
+      detail: { reason: 'pipeline-pending' },
+    });
+  });
+});

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

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest';
+import { createPreparedGraphicsStore } from '../features/prepared-graphics-store';
+
+describe('prepared graphics operation snapshots', () => {
+  it('retains normalized descriptors and upload bytes after producer mutation', () => {
+    const store = createPreparedGraphicsStore();
+    const transaction = store.beginFrame('snapshot.feature', 3);
+    const pipeline: {
+      shader: string;
+      vertexLayout: string;
+      colorFormats: string[];
+      depthFormat: string;
+      topology: 'triangle-strip';
+      indexFormat: 'uint32';
+      renderState: {
+        depthWriteEnabled: boolean;
+        blend: GPUBlendState;
+      };
+    } = {
+      shader: 'synthetic::forward',
+      vertexLayout: 'position',
+      colorFormats: ['rgba8unorm'],
+      depthFormat: 'depth24plus-stencil8',
+      topology: 'triangle-strip',
+      indexFormat: 'uint32',
+      renderState: {
+        depthWriteEnabled: false,
+        blend: {
+          color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha' },
+          alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha' },
+        },
+      },
+    };
+    const vertexData = new Float32Array([0, 1, 2, 3, 4, 5]);
+    const indexData = new Uint16Array([0, 1, 2]);
+
+    const pipelineRef = transaction.prepare('pipeline', 'forward', pipeline);
+    const bindingsRef = transaction.prepare('bindings', 'forward', {
+      pipeline: pipelineRef.unwrap(),
+      values: { tint: [1, 0, 0, 1] },
+    });
+    const vertexRef = transaction.prepare('vertex-data', 'triangle', {
+      layout: 'position',
+      data: vertexData,
+    });
+    const indexRef = transaction.prepare('index-data', 'triangle', {
+      format: 'uint16',
+      data: indexData,
+    });
+
+    expect(pipelineRef.ok).toBe(true);
+    expect(bindingsRef.ok).toBe(true);
+    expect(vertexRef.ok).toBe(true);
+    expect(indexRef.ok).toBe(true);
+    if (!pipelineRef.ok || !bindingsRef.ok || !vertexRef.ok || !indexRef.ok) return;
+
+    pipeline.colorFormats[0] = 'bgra8unorm';
+    pipeline.renderState.depthWriteEnabled = true;
+    pipeline.renderState.blend.color.dstFactor = 'zero';
+    vertexData[0] = 99;
+    indexData[0] = 99;
+
+    expect(transaction.commit().ok).toBe(true);
+    const snapshot = store.snapshot('snapshot.feature');
+    const pipelineItem = snapshot.items.find((item) => item.kind === 'pipeline');
+    const bindingsItem = snapshot.items.find((item) => item.kind === 'bindings');
+    const vertexItem = snapshot.items.find((item) => item.kind === 'vertex-data');
+    const indexItem = snapshot.items.find((item) => item.kind === 'index-data');
+
+    expect(pipelineItem?.descriptor).toMatchObject({
+      shader: 'synthetic::forward',
+      vertexLayout: 'position',
+      colorFormats: ['rgba8unorm'],
+      depthFormat: 'depth24plus-stencil8',
+      topology: 'triangle-strip',
+      indexFormat: 'uint32',
+      renderState: {
+        depthWriteEnabled: false,
+        blend: {
+          color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha' },
+          alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha' },
+        },
+      },
+    });
+    expect(bindingsItem?.descriptor).toMatchObject({
+      pipeline: pipelineRef.value,
+      values: { tint: [1, 0, 0, 1] },
+    });
+    expect(vertexItem?.descriptor).toMatchObject({
+      layout: 'position',
+      data: [0, 1, 2, 3, 4, 5],
+    });
+    expect(indexItem?.descriptor).toMatchObject({ format: 'uint16', data: [0, 1, 2] });
+    expect(vertexItem?.uploadBytes).toEqual(
+      Array.from(new Uint8Array(new Float32Array([0, 1, 2, 3, 4, 5]).buffer)),
+    );
+    expect(indexItem?.uploadBytes).toEqual(
+      Array.from(new Uint8Array(new Uint16Array([0, 1, 2]).buffer)),
+    );
+
+    for (const item of snapshot.items) {
+      expect(Object.keys(item.reference).sort()).toEqual(['generation', 'kind']);
+    }
+  });
+});