@forgeax/engine-render 0.0.0-dev.8d955ade1c79

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

@@ -0,0 +1,271 @@
+import { frustum, mat4 } from '@forgeax/engine-math';
+import { type CompiledRenderGraph, RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import type { RhiCommandEncoder } from '@forgeax/engine-rhi';
+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 type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
+import { RenderScene } from '../scene/render-scene';
+
+const GPU_MAP_MODE_READ = 0x0001;
+
+function snapshot(entityKey: number, x: number): RenderableSnapshot {
+  const world = mat4.identity(mat4.create());
+  world[12] = x;
+  const material = {
+    baseColor: new Float32Array([0.25, 0.5, 0.75]),
+    metallic: 0.1,
+    roughness: 0.9,
+  } as MaterialSnapshot;
+  return {
+    assetHandle: 3,
+    transform: { world: new Float32Array(world) },
+    localAabb: new Float32Array([-0.25, -0.25, -0.25, 0.25, 0.25, 0.25]),
+    material,
+    materials: [material],
+    materialBindingSources: ['engine-default'],
+    worldId: 0,
+    entityKey,
+    gpuDrivenDraws: [
+      {
+        kind: 'indexed',
+        first: 3,
+        count: 36,
+        baseVertex: -2,
+        materialSlot: 0,
+        topology: 'triangle-list',
+        pipelineClass: 'opaque-pbr',
+        materialResourceClass: 'plain',
+      },
+    ],
+  };
+}
+
+export interface GpuDrivenViewGpuEvidence {
+  readonly visibleInstance: number;
+  readonly indexCount: number;
+  readonly instanceCount: number;
+  readonly firstIndex: number;
+  readonly baseVertex: number;
+  readonly firstInstance: number;
+  readonly overflow: number;
+  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();
+  const shader = (
+    await rhi.createShaderModule(device, {
+      code: GPU_DRIVEN_VIEW_WGSL,
+      label: 'gpu-driven-view-evidence',
+    })
+  ).unwrap();
+  const projection = new RenderScene();
+  const visibleInstance = mat4.identity(mat4.create());
+  const culledInstance = mat4.identity(mat4.create());
+  culledInstance[12] = 10;
+  const instanced = snapshot(1, 0);
+  const delta = projection.apply([
+    {
+      kind: 'create',
+      snapshot: {
+        ...instanced,
+        instances: {
+          transforms: new Float32Array([...visibleInstance, ...culledInstance]),
+          instanceCount: 2,
+          cacheKey: 1,
+          archVersion: 1,
+        },
+      },
+    },
+    { kind: 'create', snapshot: snapshot(2, 10) },
+  ]);
+  const sceneAvailability = GpuScene.create(device, 2).unwrap();
+  if (sceneAvailability.status !== 'available') throw new Error('GPU Scene unavailable');
+  sceneAvailability.scene.sync(delta).unwrap();
+  const topology = new BatchTopology();
+  topology.rebuild(projection.slotsSnapshot());
+  const view = GpuDrivenView.create({
+    device,
+    shaderModuleFactory: { createShaderModule: () => ok(shader) },
+  }).unwrap();
+  view
+    .update(
+      topology.plan(),
+      sceneAvailability.scene,
+      frustum.fromViewProjection(frustum.create(), mat4.identity(mat4.create())),
+    )
+    .unwrap();
+  const visible = view.visibleBuffer;
+  const indirect = view.indirectBuffer;
+  const overflow = view.overflowBuffer;
+  if (visible === undefined || indirect === undefined || overflow === undefined) {
+    throw new Error('GPU-driven output buffers unavailable');
+  }
+  const visibleReadback = device
+    .createBuffer({
+      label: 'gpu-driven-visible-readback',
+      size: 4,
+      usage: GPU_BUFFER_USAGE_MAP_READ | GPU_BUFFER_USAGE_COPY_DST,
+    })
+    .unwrap();
+  const indirectReadback = device
+    .createBuffer({
+      label: 'gpu-driven-indirect-readback',
+      size: 20,
+      usage: GPU_BUFFER_USAGE_MAP_READ | GPU_BUFFER_USAGE_COPY_DST,
+    })
+    .unwrap();
+  const overflowReadback = device
+    .createBuffer({
+      label: 'gpu-driven-overflow-readback',
+      size: 4,
+      usage: GPU_BUFFER_USAGE_MAP_READ | GPU_BUFFER_USAGE_COPY_DST,
+    })
+    .unwrap();
+  const persistentTransformReadback = device
+    .createBuffer({
+      label: 'gpu-driven-persistent-transform-readback',
+      size: 64,
+      usage: GPU_BUFFER_USAGE_MAP_READ | GPU_BUFFER_USAGE_COPY_DST,
+    })
+    .unwrap();
+  const graph = new RenderGraphBuilder<{ readonly encoder: RhiCommandEncoder }>();
+  view.addPasses(graph).unwrap();
+  const compiled = graph.compile({ device, surfaceSize: { width: 1, height: 1 } }).unwrap();
+  const encoder = device.createCommandEncoder({ label: 'gpu-driven-evidence' }).unwrap();
+  compiled.execute({ encoder }).unwrap();
+  encoder.copyBufferToBuffer(visible, 0, visibleReadback, 0, 4);
+  encoder.copyBufferToBuffer(indirect, 0, indirectReadback, 0, 20);
+  encoder.copyBufferToBuffer(overflow, view.overflowByteOffset, overflowReadback, 0, 4);
+  encoder.copyBufferToBuffer(
+    sceneAvailability.scene.transformBuffer,
+    0,
+    persistentTransformReadback,
+    0,
+    64,
+  );
+  device.queue.submit([encoder.finish().unwrap()]).unwrap();
+  await device.queue.onSubmittedWorkDone();
+
+  const visibleMap = (await visibleReadback.mapAsync(GPU_MAP_MODE_READ)).unwrap();
+  const visibleValue = new DataView(visibleMap.getMappedRange().unwrap()).getUint32(0, true);
+  visibleMap.unmap();
+  const indirectMap = (await indirectReadback.mapAsync(GPU_MAP_MODE_READ)).unwrap();
+  const indirectValue = new DataView(indirectMap.getMappedRange().unwrap().slice(0));
+  indirectMap.unmap();
+  const overflowMap = (await overflowReadback.mapAsync(GPU_MAP_MODE_READ)).unwrap();
+  const overflowValue = new DataView(overflowMap.getMappedRange().unwrap()).getUint32(0, true);
+  overflowMap.unmap();
+  const persistentTransformMap = (
+    await persistentTransformReadback.mapAsync(GPU_MAP_MODE_READ)
+  ).unwrap();
+  const persistentTranslationX = new DataView(
+    persistentTransformMap.getMappedRange().unwrap(),
+  ).getFloat32(12 * 4, true);
+  persistentTransformMap.unmap();
+
+  const evidence = {
+    visibleInstance: visibleValue,
+    indexCount: indirectValue.getUint32(0, true),
+    instanceCount: indirectValue.getUint32(4, true),
+    firstIndex: indirectValue.getUint32(8, true),
+    baseVertex: indirectValue.getInt32(12, true),
+    firstInstance: indirectValue.getUint32(16, true),
+    overflow: overflowValue,
+    persistentTranslationX,
+  };
+  view.dispose();
+  sceneAvailability.scene.dispose();
+  device.destroyBuffer(visibleReadback);
+  device.destroyBuffer(indirectReadback);
+  device.destroyBuffer(overflowReadback);
+  device.destroyBuffer(persistentTransformReadback);
+  return evidence;
+}

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

@@ -0,0 +1,290 @@
+import { frustum, mat4 } from '@forgeax/engine-math';
+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, 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 { 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]),
+  metallic: 0,
+  roughness: 1,
+} as MaterialSnapshot;
+
+function snapshot(entityKey: number): RenderableSnapshot {
+  return {
+    assetHandle: 3,
+    transform: { world: new Float32Array(mat4.identity(mat4.create())) },
+    localAabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
+    material,
+    materials: [material],
+    materialBindingSources: ['engine-default'],
+    worldId: 0,
+    entityKey,
+    gpuDrivenDraws: [
+      {
+        kind: 'indexed',
+        first: 0,
+        count: 36,
+        baseVertex: 0,
+        materialSlot: 0,
+        topology: 'triangle-list',
+        pipelineClass: 'opaque',
+        materialResourceClass: 'plain',
+      },
+    ],
+  };
+}
+
+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 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(delta).unwrap();
+    const topology = new BatchTopology();
+    topology.rebuild(projection.slotsSnapshot());
+    const view = GpuDrivenView.create({
+      device,
+      shaderModuleFactory: { createShaderModule: () => ok(shader) },
+    }).unwrap();
+    view
+      .update(
+        topology.plan(),
+        sceneAvailability.scene,
+        frustum.fromViewProjection(frustum.create(), mat4.identity(mat4.create())),
+      )
+      .unwrap();
+    expect(view.inspect()).toMatchObject({
+      topologyRevision: 1,
+      candidateCount: 1,
+      batchCount: 1,
+      visibleCapacity: 1,
+      updateCount: 1,
+      bufferRebuilds: 1,
+      candidateUploadBytes: 28,
+      batchUploadBytes: 28,
+      viewConstantsUploadBytes: 112,
+      bindGroupCreates: 1,
+    });
+
+    view
+      .update(
+        topology.plan(),
+        sceneAvailability.scene,
+        frustum.fromViewProjection(frustum.create(), mat4.identity(mat4.create())),
+      )
+      .unwrap();
+    expect(view.inspect()).toMatchObject({
+      updateCount: 2,
+      bufferRebuilds: 1,
+      candidateUploadBytes: 0,
+      batchUploadBytes: 0,
+      viewConstantsUploadBytes: 112,
+      bindGroupCreates: 0,
+    });
+
+    const graph = new RenderGraphBuilder<{ readonly encoder: RhiCommandEncoder }>();
+    expect(view.addPasses(graph).ok).toBe(true);
+    const compiled = graph.compile({ device, surfaceSize: { width: 1, height: 1 } }).unwrap();
+    expect(compiled.inspect().passes).toMatchObject([
+      { name: 'gpu-driven.view-reset', kind: 'compute', dependencies: [] },
+      {
+        name: 'gpu-driven.frustum-compact',
+        kind: 'compute',
+        dependencies: ['gpu-driven.view-reset'],
+      },
+      {
+        name: 'gpu-driven.finalize-indirect',
+        kind: 'compute',
+        dependencies: ['gpu-driven.frustum-compact'],
+      },
+    ]);
+    const encoder = device.createCommandEncoder({ label: 'gpu-driven-view' }).unwrap();
+    compiled.execute({ encoder }).unwrap();
+    encoder.finish().unwrap();
+    expect((device as RhiNullDevice).framePassNames).toEqual([
+      'gpu-driven.view-reset',
+      'gpu-driven.frustum-compact',
+      'gpu-driven.finalize-indirect',
+    ]);
+
+    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/__tests__/gpu-driven-view-reference.ts

@@ -0,0 +1,111 @@
+/** Test-owned CPU oracle for the GPU-driven visibility protocol. */
+import { box3, frustum, mat4 } from '@forgeax/engine-math';
+import type { SubmissionPlan } from '../gpu-driven/batch-topology';
+import type { RenderSceneSlot } from '../scene/render-scene';
+
+export const INDEXED_INDIRECT_STRIDE = 20;
+
+export interface GpuDrivenViewReferenceResult {
+  readonly visibleInstanceIndices: Uint32Array;
+  readonly batchCounters: Uint32Array;
+  readonly indirectArgs: ArrayBuffer;
+  readonly candidateCount: number;
+  readonly rejectedCount: number;
+  readonly visibleCount: number;
+  readonly overflowedBatches: readonly number[];
+}
+
+/** CPU oracle for the storage-buffer compute protocol and WebGL2 fallback semantics. */
+export function classifyGpuDrivenView(
+  plan: SubmissionPlan,
+  slots: readonly RenderSceneSlot[],
+  planes: Float32Array,
+  capacityByBatch?: ReadonlyMap<number, number>,
+): GpuDrivenViewReferenceResult {
+  const bySlot = new Map(slots.map((slot) => [slot.slot, slot]));
+  const visibleInstanceIndices = new Uint32Array(plan.visibleCapacity);
+  const batchCounters = new Uint32Array(plan.batches.length);
+  const indirectArgs = new ArrayBuffer(
+    (plan.batches.reduce((maximum, batch) => Math.max(maximum, batch.batchId), -1) + 1) *
+      INDEXED_INDIRECT_STRIDE,
+  );
+  const args = new DataView(indirectArgs);
+  const overflowedBatches: number[] = [];
+  const instanceStartByPrimitive = new Map<number, number>();
+  let nextInstance = 0;
+  for (const slot of [...slots].sort((left, right) => left.slot - right.slot)) {
+    instanceStartByPrimitive.set(slot.slot, nextInstance);
+    nextInstance += slot.snapshot.instances?.instanceCount ?? 1;
+  }
+  let candidateCount = 0;
+  let rejectedCount = 0;
+  let visibleCount = 0;
+
+  for (let batchIndex = 0; batchIndex < plan.batches.length; batchIndex += 1) {
+    const batch = plan.batches[batchIndex];
+    if (batch === undefined) continue;
+    const capacity = capacityByBatch?.get(batch.batchId) ?? batch.visibleCapacity;
+    let count = 0;
+    for (const candidate of batch.candidates) {
+      candidateCount += 1;
+      const slot = bySlot.get(candidate.primitiveIndex);
+      if (slot === undefined || slot.generation !== candidate.generation) {
+        rejectedCount += 1;
+        continue;
+      }
+      const bounds = slot.snapshot.localAabb;
+      if (bounds === undefined) {
+        rejectedCount += 1;
+        continue;
+      }
+      const worldBounds = box3.create();
+      const local = slot.snapshot.instances?.transforms.subarray(
+        candidate.instanceOrdinal * 16,
+        candidate.instanceOrdinal * 16 + 16,
+      );
+      const world =
+        local?.length === 16
+          ? mat4.multiply(
+              mat4.create(),
+              slot.snapshot.transform.world as unknown as mat4.Mat4Like,
+              local as unknown as mat4.Mat4Like,
+            )
+          : slot.snapshot.transform.world;
+      box3.transformBox3(
+        worldBounds,
+        bounds,
+        world as unknown as Parameters<typeof box3.transformBox3>[2],
+      );
+      if (!frustum.intersectsBox(planes as frustum.Frustum, worldBounds as box3.Box3Like)) {
+        rejectedCount += 1;
+        continue;
+      }
+      if (count >= capacity) {
+        if (!overflowedBatches.includes(batch.batchId)) overflowedBatches.push(batch.batchId);
+        continue;
+      }
+      visibleInstanceIndices[batch.visibleBase + count] =
+        (instanceStartByPrimitive.get(candidate.primitiveIndex) ?? 0) + candidate.instanceOrdinal;
+      count += 1;
+      visibleCount += 1;
+    }
+    batchCounters[batchIndex] = count;
+    const offset = batch.indirectOffset;
+    args.setUint32(offset, batch.key.count, true);
+    args.setUint32(offset + 4, count, true);
+    args.setUint32(offset + 8, batch.key.first, true);
+    if (batch.key.drawKind === 'indexed') args.setInt32(offset + 12, batch.key.baseVertex, true);
+    else args.setUint32(offset + 12, 0, true);
+    args.setUint32(offset + 16, 0, true);
+  }
+
+  return {
+    visibleInstanceIndices,
+    batchCounters,
+    indirectArgs,
+    candidateCount,
+    rejectedCount,
+    visibleCount,
+    overflowedBatches,
+  };
+}