@forgeax/engine-render 0.1.4 → 0.1.7

package/src/__tests__/gpu-driven-view-gpu-evidence.ts

@@ -1,14 +1,14 @@
 import { frustum, mat4 } from '@forgeax/engine-math';
-import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import { type CompiledRenderGraph, RenderGraphBuilder } from '@forgeax/engine-render-graph';
 import type { RhiCommandEncoder } from '@forgeax/engine-rhi';
-import { rhi } from '@forgeax/engine-rhi-webgpu';
+import { _internal_getRawDevice, rhi } from '@forgeax/engine-rhi-webgpu';
 import { ok } from '@forgeax/engine-types';
 import { BatchTopology } from '../gpu-driven/batch-topology';
 import { GPU_DRIVEN_VIEW_WGSL, GpuDrivenView } from '../gpu-driven/view-gpu';
 import { GpuScene } from '../gpu-scene';
 import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_MAP_READ } from '../gpu-usage';
-import { RenderSceneProjection } from '../render-scene-projection';
 import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
+import { RenderScene } from '../scene/render-scene';
 
 const GPU_MAP_MODE_READ = 0x0001;
 
@@ -31,9 +31,6 @@ function snapshot(entityKey: number, x: number): RenderableSnapshot {
     entityKey,
     gpuDrivenDraws: [
       {
-        submeshIndex: 0,
-        passIndex: 0,
-        queue: 2000,
         kind: 'indexed',
         first: 3,
         count: 36,
@@ -58,6 +55,88 @@ export interface GpuDrivenViewGpuEvidence {
   readonly persistentTranslationX: number;
 }
 
+export interface GpuDrivenViewLifecycleEvidence {
+  readonly frames: number;
+  readonly bufferRebuilds: number;
+  readonly candidateCapacity: number;
+}
+
+export async function runGpuDrivenViewLifecycleEvidence(): Promise<GpuDrivenViewLifecycleEvidence> {
+  const adapter = (await rhi.requestAdapter()).unwrap();
+  const device = (await adapter.requestDevice()).unwrap();
+  const rawDevice = _internal_getRawDevice(device);
+  if (rawDevice === undefined) throw new Error('GPU-driven lifecycle raw device unavailable');
+  rawDevice.pushErrorScope('validation');
+  const shader = (
+    await rhi.createShaderModule(device, {
+      code: GPU_DRIVEN_VIEW_WGSL,
+      label: 'gpu-driven-view-lifecycle',
+    })
+  ).unwrap();
+  const projection = new RenderScene();
+  const sceneAvailability = GpuScene.create(device, 8).unwrap();
+  if (sceneAvailability.status !== 'available') throw new Error('GPU Scene unavailable');
+  const topology = new BatchTopology();
+  const view = GpuDrivenView.create({
+    device,
+    shaderModuleFactory: { createShaderModule: () => ok(shader) },
+  }).unwrap();
+  const planes = frustum.fromViewProjection(frustum.create(), mat4.identity(mat4.create()));
+  const retirements: Array<Promise<unknown>> = [];
+  let activeCount = 0;
+  let previous: CompiledRenderGraph<{ readonly encoder: RhiCommandEncoder }> | undefined;
+  const frames = 300;
+
+  for (let frame = 0; frame < frames; frame += 1) {
+    const targetCount = frame < 4 ? 2 ** frame : frame % 2 === 0 ? 1 : 8;
+    const operations: Array<
+      | { readonly kind: 'create'; readonly snapshot: RenderableSnapshot }
+      | { readonly kind: 'remove'; readonly worldId: number; readonly entityKey: number }
+    > = [];
+    while (activeCount < targetCount) {
+      activeCount += 1;
+      operations.push({ kind: 'create', snapshot: snapshot(activeCount, activeCount * 0.05) });
+    }
+    while (activeCount > targetCount) {
+      operations.push({ kind: 'remove', worldId: 0, entityKey: activeCount });
+      activeCount -= 1;
+    }
+    const delta = projection.apply(operations);
+    sceneAvailability.scene.sync(delta).unwrap();
+    topology.apply(delta);
+    view.update(topology.plan(), sceneAvailability.scene, planes).unwrap();
+
+    const graph = new RenderGraphBuilder<{ readonly encoder: RhiCommandEncoder }>();
+    view.addPasses(graph).unwrap();
+    const compiled = graph.compile({ device, surfaceSize: { width: 1, height: 1 } }).unwrap();
+    if (previous !== undefined) retirements.push(previous.retire());
+    view._commitResourceReplacement();
+    const encoder = device
+      .createCommandEncoder({ label: `gpu-driven-lifecycle-${frame}` })
+      .unwrap();
+    compiled.execute({ encoder }).unwrap();
+    device.queue.submit([encoder.finish().unwrap()]).unwrap();
+    previous = compiled;
+  }
+
+  await device.queue.onSubmittedWorkDone();
+  if (previous !== undefined) retirements.push(previous.retire());
+  await Promise.all(retirements);
+  const validationError = await rawDevice.popErrorScope();
+  if (validationError !== null) {
+    throw new Error(`GPU-driven lifecycle validation failed: ${validationError.message}`);
+  }
+  const inspection = view.inspect();
+  view.dispose();
+  sceneAvailability.scene.dispose();
+  await device.queue.onSubmittedWorkDone();
+  return {
+    frames,
+    bufferRebuilds: inspection.bufferRebuilds,
+    candidateCapacity: inspection.candidateCapacity,
+  };
+}
+
 export async function runGpuDrivenViewGpuEvidence(): Promise<GpuDrivenViewGpuEvidence> {
   const adapter = (await rhi.requestAdapter()).unwrap();
   const device = (await adapter.requestDevice()).unwrap();
@@ -67,7 +146,7 @@ export async function runGpuDrivenViewGpuEvidence(): Promise<GpuDrivenViewGpuEvi
       label: 'gpu-driven-view-evidence',
     })
   ).unwrap();
-  const projection = new RenderSceneProjection();
+  const projection = new RenderScene();
   const visibleInstance = mat4.identity(mat4.create());
   const culledInstance = mat4.identity(mat4.create());
   culledInstance[12] = 10;
@@ -89,7 +168,7 @@ export async function runGpuDrivenViewGpuEvidence(): Promise<GpuDrivenViewGpuEvi
   ]);
   const sceneAvailability = GpuScene.create(device, 2).unwrap();
   if (sceneAvailability.status !== 'available') throw new Error('GPU Scene unavailable');
-  sceneAvailability.scene.sync(projection, delta).unwrap();
+  sceneAvailability.scene.sync(delta).unwrap();
   const topology = new BatchTopology();
   topology.rebuild(projection.slotsSnapshot());
   const view = GpuDrivenView.create({

package/src/__tests__/gpu-driven-view-graph.integration.test.ts

@@ -3,12 +3,23 @@ import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
 import type { RhiCommandEncoder } from '@forgeax/engine-rhi';
 import { type RhiNullDevice, rhi } from '@forgeax/engine-rhi-null';
 import { ok } from '@forgeax/engine-types';
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import { BatchTopology } from '../gpu-driven/batch-topology';
+import type { PreparedGpuDrivenFrame } from '../gpu-driven/production-raster';
 import { GpuDrivenView } from '../gpu-driven/view-gpu';
 import { GpuScene } from '../gpu-scene';
-import { RenderSceneProjection } from '../render-scene-projection';
-import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
+import { RhiErrorListenerRegistry } from '../lifecycle';
+import type { RenderFrameState } from '../record/frame-snapshot';
+import { makeZeroCameraFallbackSnapshot } from '../record/frame-snapshot';
+import type { PipelineState, RenderSystemInternals } from '../record/render-context';
+import { ensureCompiledFrameGraph } from '../record/typed-frame-graph';
+import type { RenderPipeline, RenderPipelineFrame } from '../render-pipeline';
+import type {
+  ExtractedLights,
+  MaterialSnapshot,
+  RenderableSnapshot,
+} from '../render-system-extract';
+import { RenderScene } from '../scene/render-scene';
 
 const material = {
   baseColor: new Float32Array([1, 1, 1]),
@@ -28,9 +39,6 @@ function snapshot(entityKey: number): RenderableSnapshot {
     entityKey,
     gpuDrivenDraws: [
       {
-        submeshIndex: 0,
-        passIndex: 0,
-        queue: 2000,
         kind: 'indexed',
         first: 0,
         count: 36,
@@ -44,17 +52,30 @@ function snapshot(entityKey: number): RenderableSnapshot {
   };
 }
 
+function preparedFrame(view: GpuDrivenView): PreparedGpuDrivenFrame {
+  return {
+    topologySignature: `view-generation:${view.inspect().resourceGeneration}`,
+    entityKeys: new Set(),
+    ownsAllRenderables: true,
+    _commitResourceReplacement: () => view._commitResourceReplacement(),
+    project: (graph) => {
+      const projected = view.addPasses(graph);
+      return projected.ok ? ok({ accesses: [], encode: () => undefined }) : projected;
+    },
+  };
+}
+
 describe('GpuDrivenView graph projection', () => {
   it('records reset, compact, and finalize in one typed graph', async () => {
     const adapter = (await rhi.requestAdapter()).unwrap();
     const device = (await adapter.requestDevice()).unwrap();
     const shader = (await rhi.createShaderModule(device, { code: 'synthetic' })).unwrap();
-    const projection = new RenderSceneProjection();
+    const projection = new RenderScene();
     const delta = projection.apply([{ kind: 'create', snapshot: snapshot(1) }]);
     const sceneAvailability = GpuScene.create(device, 1).unwrap();
     expect(sceneAvailability.status).toBe('available');
     if (sceneAvailability.status !== 'available') return;
-    sceneAvailability.scene.sync(projection, delta).unwrap();
+    sceneAvailability.scene.sync(delta).unwrap();
     const topology = new BatchTopology();
     topology.rebuild(projection.slotsSnapshot());
     const view = GpuDrivenView.create({
@@ -125,4 +146,145 @@ describe('GpuDrivenView graph projection', () => {
     view.dispose();
     sceneAvailability.scene.dispose();
   });
+
+  it('keeps last-known-good graph buffers alive until replacement promotion', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const shader = (await rhi.createShaderModule(device, { code: 'synthetic' })).unwrap();
+    const destroyBuffer = vi.spyOn(device, 'destroyBuffer');
+    const projection = new RenderScene();
+    const firstDelta = projection.apply([{ kind: 'create', snapshot: snapshot(1) }]);
+    const sceneAvailability = GpuScene.create(device, 2).unwrap();
+    expect(sceneAvailability.status).toBe('available');
+    if (sceneAvailability.status !== 'available') return;
+    sceneAvailability.scene.sync(firstDelta).unwrap();
+    const topology = new BatchTopology();
+    topology.rebuild(projection.slotsSnapshot());
+    const view = GpuDrivenView.create({
+      device,
+      shaderModuleFactory: { createShaderModule: () => ok(shader) },
+    }).unwrap();
+    const planes = frustum.fromViewProjection(frustum.create(), mat4.identity(mat4.create()));
+    view.update(topology.plan(), sceneAvailability.scene, planes).unwrap();
+    const previousVisible = view.visibleBuffer;
+    expect(previousVisible).toBeDefined();
+    if (previousVisible === undefined) return;
+
+    let forceCompileFailure = false;
+    const activePipeline: RenderPipeline = {
+      build: ({ graph, projectGpuDriven }) => {
+        const projected = projectGpuDriven({ format: 'rgba8unorm', sampleCount: 1 });
+        if (!projected.ok) return projected;
+        if (forceCompileFailure) {
+          const dangling = graph
+            .createBuffer('forced-candidate-compile-failure', { size: 4 })
+            .unwrap();
+          graph
+            .addComputePass('forced-candidate-compile-failure', {
+              accesses: [{ resource: dangling, usage: 'storage-read' }],
+              encode: () => undefined,
+            })
+            .unwrap();
+        }
+        return ok(undefined);
+      },
+    };
+    const frameState = {
+      compiledFrameGraph: null,
+      compiledFrameGraphTopologyKey: null,
+      retiredCompiledFrameGraphs: new Set(),
+      activePipeline,
+      installedPipelineConfig: undefined,
+    } as unknown as RenderFrameState;
+    const errors: unknown[] = [];
+    const errorRegistry = new RhiErrorListenerRegistry();
+    errorRegistry.add((error) => errors.push(error));
+    const internals = { device, errorRegistry } as unknown as RenderSystemInternals;
+    const pipelineState = {
+      format: 'rgba8unorm',
+      colorAttachmentFormat: 'rgba8unorm',
+    } as unknown as PipelineState;
+    const lights = {
+      cascadeCount: undefined,
+      pointShadow: [],
+      spot: [],
+    } as unknown as ExtractedLights;
+    const compile = (prepared: PreparedGpuDrivenFrame) =>
+      ensureCompiledFrameGraph(
+        internals,
+        frameState,
+        pipelineState,
+        makeZeroCameraFallbackSnapshot(),
+        lights,
+        1,
+        1,
+        undefined,
+        prepared,
+      );
+    const compiledPrevious = compile(preparedFrame(view));
+    expect(compiledPrevious).not.toBeNull();
+    if (compiledPrevious === null) return;
+
+    const secondDelta = projection.apply([{ kind: 'create', snapshot: snapshot(2) }]);
+    sceneAvailability.scene.sync(secondDelta).unwrap();
+    topology.rebuild(projection.slotsSnapshot());
+    view.update(topology.plan(), sceneAvailability.scene, planes).unwrap();
+
+    expect(view.inspect()).toMatchObject({ candidateCount: 2, candidateCapacity: 2 });
+    forceCompileFailure = true;
+    expect(compile(preparedFrame(view))).toBe(compiledPrevious);
+    expect(errors).toHaveLength(1);
+    expect(destroyBuffer.mock.calls.some(([buffer]) => buffer === previousVisible)).toBe(false);
+    const encoder = device.createCommandEncoder({ label: 'gpu-driven-view-lkg' }).unwrap();
+    expect(compiledPrevious.execute({ encoder } as RenderPipelineFrame).ok).toBe(true);
+
+    forceCompileFailure = false;
+    const retirePrevious = vi.spyOn(compiledPrevious, 'retire');
+    const acceptedGraph = compile(preparedFrame(view));
+    expect(acceptedGraph).not.toBe(compiledPrevious);
+    expect(retirePrevious).toHaveBeenCalledOnce();
+    await device.queue.onSubmittedWorkDone();
+    await Promise.resolve();
+    expect(destroyBuffer.mock.calls.some(([buffer]) => buffer === previousVisible)).toBe(true);
+
+    view.dispose();
+    sceneAvailability.scene.dispose();
+  });
+
+  it('releases a promoted generation once when the queue fence rejects', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const shader = (await rhi.createShaderModule(device, { code: 'synthetic' })).unwrap();
+    const destroyBuffer = vi.spyOn(device, 'destroyBuffer');
+    const projection = new RenderScene();
+    const firstDelta = projection.apply([{ kind: 'create', snapshot: snapshot(1) }]);
+    const sceneAvailability = GpuScene.create(device, 2).unwrap();
+    expect(sceneAvailability.status).toBe('available');
+    if (sceneAvailability.status !== 'available') return;
+    sceneAvailability.scene.sync(firstDelta).unwrap();
+    const topology = new BatchTopology();
+    topology.rebuild(projection.slotsSnapshot());
+    const view = GpuDrivenView.create({
+      device,
+      shaderModuleFactory: { createShaderModule: () => ok(shader) },
+    }).unwrap();
+    const planes = frustum.fromViewProjection(frustum.create(), mat4.identity(mat4.create()));
+    view.update(topology.plan(), sceneAvailability.scene, planes).unwrap();
+    const firstVisible = view.visibleBuffer;
+    expect(firstVisible).toBeDefined();
+    if (firstVisible === undefined) return;
+
+    const secondDelta = projection.apply([{ kind: 'create', snapshot: snapshot(2) }]);
+    sceneAvailability.scene.sync(secondDelta).unwrap();
+    topology.rebuild(projection.slotsSnapshot());
+    view.update(topology.plan(), sceneAvailability.scene, planes).unwrap();
+    vi.spyOn(device.queue, 'onSubmittedWorkDone').mockRejectedValueOnce(new Error('device lost'));
+    view._commitResourceReplacement();
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(destroyBuffer.mock.calls.filter(([buffer]) => buffer === firstVisible)).toHaveLength(1);
+
+    view.dispose();
+    sceneAvailability.scene.dispose();
+  });
 });

package/src/{gpu-driven/view-reference.ts → __tests__/gpu-driven-view-reference.ts}

@@ -1,6 +1,7 @@
+/** Test-owned CPU oracle for the GPU-driven visibility protocol. */
 import { box3, frustum, mat4 } from '@forgeax/engine-math';
-import type { RenderSceneProjectionSlot } from '../render-scene-projection';
-import type { SubmissionPlan } from './batch-topology';
+import type { SubmissionPlan } from '../gpu-driven/batch-topology';
+import type { RenderSceneSlot } from '../scene/render-scene';
 
 export const INDEXED_INDIRECT_STRIDE = 20;
 
@@ -17,7 +18,7 @@ export interface GpuDrivenViewReferenceResult {
 /** CPU oracle for the storage-buffer compute protocol and WebGL2 fallback semantics. */
 export function classifyGpuDrivenView(
   plan: SubmissionPlan,
-  slots: readonly RenderSceneProjectionSlot[],
+  slots: readonly RenderSceneSlot[],
   planes: Float32Array,
   capacityByBatch?: ReadonlyMap<number, number>,
 ): GpuDrivenViewReferenceResult {

package/src/__tests__/gpu-driven-view.browser.test.ts

@@ -1,5 +1,8 @@
 import { describe, expect, it } from 'vitest';
-import { runGpuDrivenViewGpuEvidence } from './gpu-driven-view-gpu-evidence';
+import {
+  runGpuDrivenViewGpuEvidence,
+  runGpuDrivenViewLifecycleEvidence,
+} from './gpu-driven-view-gpu-evidence';
 
 const browserReady = typeof navigator !== 'undefined' && navigator.gpu !== undefined;
 
@@ -16,4 +19,12 @@ describe.skipIf(!browserReady)('GPU-driven View Browser WebGPU', () => {
       persistentTranslationX: 0,
     });
   });
+
+  it('survives 300 frames of spawn/despawn capacity crossings without stale buffers', async () => {
+    await expect(runGpuDrivenViewLifecycleEvidence()).resolves.toEqual({
+      frames: 300,
+      bufferRebuilds: 4,
+      candidateCapacity: 8,
+    });
+  }, 30_000);
 });

package/src/__tests__/gpu-driven-view.dawn.test.ts

@@ -1,5 +1,8 @@
 import { describe, expect, it } from 'vitest';
-import { runGpuDrivenViewGpuEvidence } from './gpu-driven-view-gpu-evidence';
+import {
+  runGpuDrivenViewGpuEvidence,
+  runGpuDrivenViewLifecycleEvidence,
+} from './gpu-driven-view-gpu-evidence';
 
 describe('GPU-driven View Dawn', () => {
   it('produces compact visible IDs and portable indirect args on the real GPU API', async () => {
@@ -14,4 +17,12 @@ describe('GPU-driven View Dawn', () => {
       persistentTranslationX: 0,
     });
   });
+
+  it('survives 300 frames of spawn/despawn capacity crossings without stale buffers', async () => {
+    await expect(runGpuDrivenViewLifecycleEvidence()).resolves.toEqual({
+      frames: 300,
+      bufferRebuilds: 4,
+      candidateCapacity: 8,
+    });
+  }, 30_000);
 });