@forgeax/engine-render 0.1.27 → 0.1.29

package/src/__tests__/reflection-fallback-async-publication.unit.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from 'vitest';
+import type { RenderSystemInternals } from '../record/render-context';
+import { ReflectionProbeRecordOwner } from '../reflection/record-owner';
+import type { SkylightSnapshot } from '../render-system-extract';
+
+function fixture() {
+  const internals = {
+    device: { caps: { rgba16floatRenderable: true } },
+    deviceScope: { owner: 'test', generation: 0 },
+  } as unknown as RenderSystemInternals;
+  const owner = new ReflectionProbeRecordOwner(internals);
+  const stage = (frame: number, source = 1) =>
+    // biome-ignore lint/complexity/useLiteralKeys: Exercise the private owner seam without exposing a test-only public API.
+    owner['stageFallbackProjections'](
+      [],
+      new Map([['receiver', { kind: 'skylight' as const }]]),
+      new Map(),
+      frame,
+      {
+        entityHandle: source,
+        equirectHandle: 0,
+        color: [1, 1, 1],
+        intensity: 1,
+        rotation: [0, 0, 0, 1],
+      } satisfies SkylightSnapshot,
+    );
+  const complete = (tickets: ReturnType<typeof stage>, frameId: number) =>
+    // biome-ignore lint/complexity/useLiteralKeys: Invoke the real asynchronous completion boundary.
+    owner['completeSubmission'](true, tickets, Promise.resolve(), {
+      frameId,
+      format: 'rgba16float',
+      size: { width: 1, height: 1 },
+      graphGeneration: 1,
+      textureIdentity: 1,
+      readback: Promise.resolve({
+        linearHdr: [1, 1, 1, 1],
+        hash: 'test',
+        graphGeneration: 1,
+        textureIdentity: 1,
+      }),
+    });
+  return { owner, stage, complete, internals };
+}
+
+describe('fallback asynchronous publication', () => {
+  it('publishes a completed source-compatible frame while newer frames are being prepared', async () => {
+    const { owner, stage, complete } = fixture();
+    const first = stage(1);
+    stage(2);
+    stage(3);
+    await complete(first, 1);
+    expect(owner.inspect().reflectionFallback).toMatchObject({ state: 'active', frameId: 1 });
+  });
+
+  it('does not roll back an already completed newer frame', async () => {
+    const { owner, stage, complete } = fixture();
+    const first = stage(1);
+    const second = stage(2);
+    await complete(second, 2);
+    await complete(first, 1);
+    expect(owner.inspect().reflectionFallback).toMatchObject({ state: 'active', frameId: 2 });
+  });
+
+  it('rejects source changes including an uncommitted A-B-A transition', async () => {
+    const { owner, stage, complete } = fixture();
+    const first = stage(1, 1);
+    stage(2, 2);
+    stage(3, 1);
+    await complete(first, 1);
+    expect(owner.inspect().reflectionFallback.state).not.toBe('active');
+  });
+
+  it('rejects completion from a retired device', async () => {
+    const { owner, stage, complete, internals } = fixture();
+    const first = stage(1);
+    Object.assign(internals.deviceScope, { generation: 1 });
+    await complete(first, 1);
+    expect(owner.inspect().reflectionFallback.state).not.toBe('active');
+  });
+
+  it('does not revive a disappeared receiver when the same source returns', async () => {
+    const { owner, stage, complete } = fixture();
+    const first = stage(1);
+    // biome-ignore lint/complexity/useLiteralKeys: Retire through the same private staging seam.
+    owner['stageFallbackProjections']([], new Map(), new Map(), 2, undefined);
+    stage(3);
+    await complete(first, 1);
+    expect(owner.inspect().reflectionFallback.state).not.toBe('active');
+  });
+
+  it('keeps source and projection generations stable for compatible completions', async () => {
+    const { owner, stage, complete } = fixture();
+    await complete(stage(1), 1);
+    const second = stage(2);
+    stage(3);
+    await complete(second, 2);
+    expect(owner.inspect().reflectionFallback).toMatchObject({
+      state: 'active',
+      frameId: 2,
+      sourceGeneration: 1,
+      projectionGeneration: 1,
+    });
+  });
+});

package/src/__tests__/reflection-probe-record-owner.characterization.unit.test.ts

@@ -105,7 +105,8 @@ describe('ReflectionProbeRecordOwner characterization', () => {
     expect(ownerSource).not.toContain("readbackStatus: 'scheduled'");
     expect(ownerSource).toContain('readbackHash: readback.hash');
     expect(ownerSource).not.toContain('linearHdr: readback.linearHdr');
-    expect(ownerSource).toContain('const staged = this.pendingFallback.get(pending.ticket);');
+    expect(ownerSource).toContain('reflectionFallbackProjectionSignature(latest.projection)');
+    expect(ownerSource).toContain('pending.frameId <= committedFrame');
     expect(ownerSource).toContain('latestFallbackTickets');
   });
 

package/src/__tests__/render-error-code-owner.test-d.ts

@@ -15,6 +15,10 @@ import type {
 } from '../index';
 
 const expectedCodes = [
+  'auto-exposure-invalid-parameter',
+  'auto-exposure-capability-unavailable',
+  'auto-exposure-stale-generation',
+  'auto-exposure-stage-failed',
   'lifecycle-construction-failed',
   'world-lease-invalid',
   'frame-input-invalid',

package/src/__tests__/render-error-detail-ssot.test-d.ts

@@ -1,5 +1,10 @@
 import { describe, expectTypeOf, it } from 'vitest';
 import type { RenderError } from '../errors/render';
+import type {
+  AutoExposureError,
+  AutoExposureErrorCode,
+  AutoExposureErrorDetail,
+} from '../pipeline/standard-output/auto-exposure/inspection';
 import type {
   FullscreenInputNotFoundDetail,
   PostProcessErrorCode,
@@ -15,6 +20,16 @@ import type {
 } from '../post-process-errors';
 import { PostProcessError } from '../post-process-errors';
 
+type ExpectedAutoExposureCodes =
+  | 'auto-exposure-invalid-parameter'
+  | 'auto-exposure-capability-unavailable'
+  | 'auto-exposure-stale-generation'
+  | 'auto-exposure-stage-failed';
+type AutoExposureDetailFor<C extends AutoExposureErrorCode> = Extract<
+  AutoExposureError,
+  { readonly code: C }
+>['detail'];
+
 type ExpectedPostProcessDetails = {
   readonly 'post-process-already-registered': PostProcessPreviouslyRegisteredDetail;
   readonly 'post-process-not-found': PostProcessNotFoundDetail;
@@ -32,6 +47,13 @@ type DetailFor<C extends PostProcessErrorCode> = Extract<
 >['detail'];
 
 describe('render error detail aliases derive from their code resolvers', () => {
+  it('keeps auto-exposure error codes and code/detail correlation closed', () => {
+    expectTypeOf<AutoExposureErrorCode>().toEqualTypeOf<ExpectedAutoExposureCodes>();
+    expectTypeOf<AutoExposureErrorCode>().toEqualTypeOf<AutoExposureError['code']>();
+    expectTypeOf<AutoExposureErrorDetail>().toEqualTypeOf<
+      AutoExposureDetailFor<AutoExposureErrorCode>
+    >();
+  });
   it('preserves the complete post-process detail union', () => {
     expectTypeOf<PostProcessErrorDetail>().toEqualTypeOf<
       PostProcessErrorDetailFor<PostProcessErrorCode>

package/src/__tests__/render-error-exhaustive.test-d.ts

@@ -11,6 +11,20 @@ import type {
   VertexColorVariantConflictError,
 } from '../errors/render';
 import type { RenderFeatureErrorCode } from '../features/types';
+import type { AutoExposureErrorCode } from '../pipeline/standard-output/auto-exposure/inspection';
+
+function autoExposureCodeLabel(code: AutoExposureErrorCode): string {
+  switch (code) {
+    case 'auto-exposure-invalid-parameter':
+      return code;
+    case 'auto-exposure-capability-unavailable':
+      return code;
+    case 'auto-exposure-stale-generation':
+      return code;
+    case 'auto-exposure-stage-failed':
+      return code;
+  }
+}
 
 function renderFeatureCodeLabel(code: RenderFeatureErrorCode): string {
   switch (code) {
@@ -111,3 +125,4 @@ const taaErrorCode: RenderErrorCode = 'taa-unavailable';
 void taaErrorCode;
 void renderCodeLabel;
 void renderFeatureErrorLabel;
+void autoExposureCodeLabel;

package/src/__tests__/render-feature-gpu-work.integration.test.ts

@@ -10,14 +10,109 @@ import {
 import { rhi } from '@forgeax/engine-rhi-null';
 import { err, ok } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
+import type { RenderFeatureGpuProgramDescriptor } from '../features/prepared-gpu-work';
 import { createRenderFeatureGpuWorkOwner } from '../features/prepared-gpu-work';
 import { RenderFeatureComputeGraphProjection } from '../features/render-graph-compute';
 import { RenderFeatureRasterGraphProjection } from '../features/render-graph-raster';
 import { createRenderFeatureGraphBufferState } from '../features/render-graph-resources';
+import { createRenderFeatureTarget } from '../features/targets';
 import type { PreparedGraphicsResolvedResource } from '../prepare/prepared-graphics-resolver';
 
 describe('RenderFeature persistent GPU work', () => {
-  it('projects compute output and indirect raster consumption into one typed graph', async () => {
+  it('binds graph-owned sampled textures at execution instead of the preparation fallback', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const shader = (await rhi.createShaderModule(device, { code: 'synthetic' })).unwrap();
+    const owner = createRenderFeatureGpuWorkOwner({
+      getDevice: () => device,
+      getShaderModuleFactory: () => ({ createShaderModule: () => ok(shader) }),
+    });
+    const session = owner.beginFeature('sampled-compute', 0);
+    const program = session
+      .prepareProgram('sample', {
+        wgsl: 'synthetic',
+        entryPoints: ['sample'],
+        bindings: [{ entries: [{ binding: 0, visibility: 4, texture: { sampleType: 'depth' } }] }],
+      })
+      .unwrap();
+    const texture = device
+      .createTexture({
+        size: { width: 1, height: 1 },
+        format: 'depth32float',
+        usage: 0x04 | 0x10,
+        textureBindingViewDimension: undefined,
+      })
+      .unwrap();
+    const fallback = device.createTextureView(texture, {}).unwrap();
+    const reference = session
+      .prepareTextureView(
+        'depth',
+        fallback,
+        createRenderFeatureTarget({ kind: 'scene-depth', format: 'depth32float', sampleCount: 1 }),
+      )
+      .unwrap();
+    const bindings = session
+      .prepareBindings('bindings', {
+        program,
+        entries: [{ binding: 0, resource: { kind: 'texture-view', reference } }],
+      })
+      .unwrap();
+    const work = session
+      .resolveComputePass('sampled-compute', {
+        program,
+        bindings,
+        dispatches: [{ entryPoint: 'sample', workgroups: [1] }],
+      })
+      .unwrap();
+    expect(work.sampledTargets).toMatchObject([
+      { kind: 'scene-depth', format: 'depth32float', sampleCount: 1 },
+    ]);
+    const graph = new RenderGraphBuilder<{ readonly encoder: RhiCommandEncoder }>();
+    const depth = graph
+      .createTexture('real-depth', {
+        format: 'depth32float',
+        size: { width: 1, height: 1 },
+      })
+      .unwrap();
+    const view = graph.view(depth).unwrap();
+    graph
+      .addRasterPass('depth-producer', {
+        colorAttachments: [],
+        depthStencilAttachment: {
+          view,
+          depthLoadOp: 'clear',
+          depthStoreOp: 'store',
+          depthClearValue: 0.25,
+        },
+        accesses: [{ resource: view, usage: 'depth-stencil-write' }],
+        encode: () => {},
+      })
+      .unwrap();
+    const seen: unknown[] = [];
+    const createBindGroup = device.createBindGroup.bind(device);
+    device.createBindGroup = (descriptor) => {
+      seen.push([...descriptor.entries][0]?.resource);
+      return createBindGroup(descriptor);
+    };
+    const projection = new RenderFeatureComputeGraphProjection(graph, undefined, undefined, () => ({
+      texture: depth,
+      view,
+    }));
+    projection.addPass('sample', 'sampled-compute', 0, work).unwrap();
+    const compiled = graph.compile({ device, surfaceSize: { width: 1, height: 1 } }).unwrap();
+    expect(compiled.inspect().passes[1]?.dependencies).toEqual(['depth-producer']);
+    compiled.execute({ encoder: device.createCommandEncoder().unwrap() }).unwrap();
+    expect(seen).toHaveLength(1);
+    expect(seen[0]).not.toEqual({ kind: 'textureView', value: fallback });
+    await compiled.retire();
+    owner.dispose().unwrap();
+  });
+  it.each([
+    [1, false],
+    [4, false],
+    [1, true],
+    [4, true],
+  ] as const)('projects compute and indirect raster consumption with %i samples, Standard lighting %s', async (sampleCount, standardLighting) => {
     const adapter = (await rhi.requestAdapter()).unwrap();
     const device = (await adapter.requestDevice()).unwrap();
     const indirectBuffer = device
@@ -28,6 +123,18 @@ describe('RenderFeature persistent GPU work', () => {
       .createTexture('output', { format: 'rgba8unorm', size: { width: 1, height: 1 } })
       .unwrap();
     const outputView = graph.view(output, { label: 'output.view' }).unwrap();
+    const multisample =
+      sampleCount === 1
+        ? undefined
+        : graph
+            .createTexture('multisample', {
+              format: 'rgba8unorm',
+              size: { width: 1, height: 1 },
+              sampleCount,
+            })
+            .unwrap();
+    const multisampleView =
+      multisample === undefined ? undefined : graph.view(multisample).unwrap();
     const buffers = createRenderFeatureGraphBufferState();
     const compute = new RenderFeatureComputeGraphProjection(graph, buffers);
     expect(
@@ -62,6 +169,7 @@ describe('RenderFeature persistent GPU work', () => {
           kind: 'pipeline',
           reference: pipeline as never,
           handle: {} as RenderPipeline,
+          standardLighting,
         },
       ],
       [
@@ -83,11 +191,18 @@ describe('RenderFeature persistent GPU work', () => {
         },
       ],
     ]);
+    const lightingGroup = {} as BindGroup;
     const raster = new RenderFeatureRasterGraphProjection(
       graph,
-      () => ({ texture: output, view: outputView }),
+      () => ({
+        texture: multisample ?? output,
+        view: multisampleView ?? outputView,
+        ...(multisampleView === undefined ? {} : { resolveTarget: outputView }),
+      }),
       undefined,
       buffers,
+      undefined,
+      () => lightingGroup,
     );
     expect(
       raster.addPass(
@@ -143,7 +258,21 @@ describe('RenderFeature persistent GPU work', () => {
       { name: 'vfx.draw', kind: 'raster', dependencies: ['vfx.simulate-and-project'] },
     ]);
     const encoder = device.createCommandEncoder({ label: 'vfx-mixed-frame' }).unwrap();
+    const bound: Array<{ index: number; group: BindGroup }> = [];
+    const begin = encoder.beginRenderPass.bind(encoder);
+    encoder.beginRenderPass = (descriptor) => {
+      const pass = begin(descriptor);
+      const set = pass.setBindGroup.bind(pass);
+      pass.setBindGroup = (index, group, offsets) => {
+        bound.push({ index, group });
+        return set(index, group, offsets === undefined ? undefined : Array.from(offsets));
+      };
+      return pass;
+    };
     expect(compiled.execute({ encoder }).ok).toBe(true);
+    expect(bound.filter((entry) => entry.index === 2)).toEqual(
+      standardLighting ? [{ index: 2, group: lightingGroup }] : [],
+    );
     expect(encoder.finish().ok).toBe(true);
   });
 
@@ -227,6 +356,65 @@ describe('RenderFeature persistent GPU work', () => {
     expect(owner.dispose().ok).toBe(true);
   });
 
+  it('reuses equivalent prepared programs but rejects nested descriptor mutation', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const shader = (await rhi.createShaderModule(device, { code: 'synthetic' })).unwrap();
+    const owner = createRenderFeatureGpuWorkOwner({
+      getDevice: () => device,
+      getShaderModuleFactory: () => ({ createShaderModule: () => ok(shader) }),
+    });
+    const resolver = owner.beginFeature('synthetic.program', 0);
+    const descriptor = {
+      wgsl: 'synthetic',
+      entryPoints: ['simulate'],
+      bindings: [
+        {
+          entries: [
+            {
+              binding: 0,
+              visibility: 0x4,
+              buffer: { type: 'storage', hasDynamicOffset: false, minBindingSize: 0 },
+            },
+          ],
+        },
+      ],
+    } satisfies RenderFeatureGpuProgramDescriptor;
+    const first = resolver.prepareProgram('program', descriptor).unwrap();
+    const equivalent = resolver.prepareProgram('program', {
+      wgsl: 'synthetic',
+      entryPoints: ['simulate'],
+      bindings: [
+        {
+          entries: [
+            {
+              binding: 0,
+              visibility: 0x4,
+              buffer: { type: 'storage', hasDynamicOffset: false, minBindingSize: 0 },
+            },
+          ],
+        },
+      ],
+    });
+    expect(equivalent).toMatchObject({ ok: true, value: first });
+
+    const firstBinding = descriptor.bindings[0];
+    if (firstBinding === undefined) throw new Error('fixture missing binding');
+    const firstEntry = firstBinding.entries[0];
+    if (firstEntry === undefined) throw new Error('fixture missing binding entry');
+    const mutableEntry = firstEntry as { visibility: number };
+    mutableEntry.visibility = 0x1;
+    const changed = resolver.prepareProgram('program', descriptor);
+    expect(changed).toMatchObject({
+      ok: false,
+      error: {
+        code: 'render-feature-preparation-failed',
+        detail: { reason: 'signature-mismatch' },
+      },
+    });
+    expect(owner.dispose().ok).toBe(true);
+  });
+
   it('records compute against persistent storage and releases it once', async () => {
     const adapter = (await rhi.requestAdapter()).unwrap();
     const device = (await adapter.requestDevice()).unwrap();
@@ -352,9 +540,104 @@ describe('RenderFeature persistent GPU work', () => {
     const retired = resolver.retireUntouched();
     expect(retired).toHaveLength(1);
     expect(resolver.resolveBuffer(storage)).toBeUndefined();
+    // A non-VFX feature retires all three resource kinds together.  The
+    // binding/program indexes must be invalidated at the same boundary as the
+    // buffer; otherwise a stale compute descriptor can revive work that now
+    // references a destroyed buffer.
+    expect(resolver.retainBindings([bindings]).ok).toBe(false);
+    expect(resolver.resolveComputePass('synthetic.gpu', computeDescriptor).ok).toBe(false);
     expect(retired[0]?.release().ok).toBe(true);
     expect(retired[0]?.release().ok).toBe(true);
+    expect(resolver.retainBindings([bindings]).ok).toBe(false);
+    expect(resolver.resolveComputePass('synthetic.gpu', computeDescriptor).ok).toBe(false);
+
+    const replacementProgram = resolver
+      .prepareProgram('program', {
+        wgsl: 'synthetic',
+        entryPoints: ['simulate', 'compact'],
+        bindings: [
+          {
+            entries: [
+              {
+                binding: 0,
+                visibility: 0x4,
+                buffer: { type: 'storage', hasDynamicOffset: false, minBindingSize: 0 },
+              },
+              {
+                binding: 1,
+                visibility: 0x4,
+                buffer: { type: 'storage', hasDynamicOffset: false, minBindingSize: 0 },
+              },
+            ],
+          },
+        ],
+      })
+      .unwrap();
+    const replacementStorage = resolver
+      .prepareBuffer('particles', {
+        size: 4096,
+        usage: ['storage', 'vertex'],
+        data: new Uint32Array([5, 6, 7, 8]),
+      })
+      .unwrap();
+    const replacementIndirect = resolver
+      .prepareBuffer('indirect', {
+        size: 20,
+        usage: ['storage', 'indirect'],
+        data: new Uint32Array([6, 0, 0, 0, 0]),
+      })
+      .unwrap();
+    const replacementBindings = resolver
+      .prepareBindings('bindings', {
+        program: replacementProgram,
+        entries: [
+          { binding: 0, buffer: replacementStorage },
+          { binding: 1, buffer: replacementIndirect },
+        ],
+      })
+      .unwrap();
+    expect(replacementProgram).not.toBe(program);
+    expect(replacementBindings).not.toBe(bindings);
+    expect(resolver.retainBindings([bindings]).ok).toBe(false);
     expect(resolver.dispose().ok).toBe(true);
     expect(resolver.dispose().ok).toBe(true);
   });
+
+  it('parks short-lived VFX queue slots and revives the same allocation', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const owner = createRenderFeatureGpuWorkOwner({
+      getDevice: () => device,
+      getShaderModuleFactory: () => ({ createShaderModule: () => ok({} as never) }),
+    });
+    const session = owner.beginFeature('forgeax.vfx-render.gpu-particles', 0);
+    const first = session
+      .prepareBuffer('queued-slot', { size: 16, usage: ['storage'], data: new Uint32Array([1]) })
+      .unwrap();
+    expect(session.retireUntouched()).toEqual([]);
+
+    // One missing fixed tick parks the slot instead of retiring its physical
+    // buffer. Re-publishing the same named slot must revive the exact ref.
+    session.beginFrame();
+    expect(session.retireUntouched()).toEqual([]);
+    session.beginFrame();
+    const revived = session
+      .prepareBuffer('queued-slot', { size: 16, usage: ['storage'], data: new Uint32Array([2]) })
+      .unwrap();
+    expect(revived).toBe(first);
+    expect(session.resolveBuffer(first)).toBeDefined();
+    expect(session.retireUntouched()).toEqual([]);
+
+    // Parking is bounded. After the window, the old allocation is retired via
+    // the normal lease path and cannot be resolved by a stale reference.
+    let retired = [] as ReturnType<typeof session.retireUntouched>;
+    for (let index = 0; index < 9; index += 1) {
+      session.beginFrame();
+      retired = session.retireUntouched();
+    }
+    expect(retired).toHaveLength(1);
+    expect(session.resolveBuffer(first)).toBeUndefined();
+    expect(retired[0]?.release().ok).toBe(true);
+    expect(owner.dispose().ok).toBe(true);
+  });
 });