@forgeax/engine-render 0.1.19 → 0.1.21

package/src/__tests__/gpu-driven-production.integration.test.ts

@@ -11,7 +11,7 @@ import {
 import { ok } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import { createRenderer as constructRenderer } from '../assembly/factory';
-import { Camera, MeshFilter, MeshRenderer } from '../components';
+import { Camera, MeshFilter, MeshRenderer, PointLight } from '../components';
 import type { MeshGpuHandles } from '../device/gpu-residency';
 import { BatchTopology } from '../gpu-driven/batch-topology';
 import { GpuDrivenProduction } from '../gpu-driven/production-raster';
@@ -29,6 +29,11 @@ import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extr
 import { RenderScene } from '../scene/render-scene';
 
 const EMPTY_RESOURCE_CLASS = JSON.stringify({ textures: [], samplers: [], video: [] });
+const OUTPUT_TRANSFORM_WGSL =
+  '@vertex fn vs_main(@builtin(vertex_index) i: u32) -> @builtin(position) vec4<f32> { ' +
+  'var p = array<vec2<f32>, 3>(vec2<f32>(-1.0, -1.0), vec2<f32>(3.0, -1.0), vec2<f32>(-1.0, 3.0)); ' +
+  'return vec4<f32>(p[i], 0.0, 1.0); } ' +
+  '@fragment fn fs_main() -> @location(0) vec4<f32> { return vec4<f32>(0.0); }';
 
 const STANDARD_PBR_URP_VARIANT_KEY =
   'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true+TRANSMISSION_AVAILABLE=false+VERTEX_COLOR_AVAILABLE=false';
@@ -38,7 +43,7 @@ const STANDARD_PBR_TRANSMISSION_VARIANT_KEY =
 function manifestDataUrl(): string {
   const pbrWgsl = '/* pbr stub - calls f_schlick( */';
   const unlitWgsl = '/* unlit stub */';
-  const tonemapWgsl = '/* tonemap stub - struct TonemapParams { exposure: f32 }; */';
+  const tonemapWgsl = OUTPUT_TRANSFORM_WGSL;
   const standardPbrVariant = (transmissionAvailable: boolean, definesKey: string) => ({
     definesKey,
     defines: {
@@ -247,7 +252,6 @@ describe('GPU-driven production projection', () => {
         meshes,
         viewBindGroupLayout: viewLayout,
         meshResidencyEpoch: 1,
-        hdrp: false,
       })
       .unwrap();
     expect(prepared).toBeDefined();
@@ -272,7 +276,6 @@ describe('GPU-driven production projection', () => {
         meshes,
         viewBindGroupLayout: viewLayout,
         meshResidencyEpoch: 1,
-        hdrp: false,
       })
       .unwrap();
     expect(stable?.topologySignature).toBe(prepared.topologySignature);
@@ -341,7 +344,6 @@ describe('GPU-driven production projection', () => {
         meshes,
         viewBindGroupLayout: viewLayout,
         meshResidencyEpoch: 1,
-        hdrp: false,
       })
       .unwrap();
     expect(replacementPrepared?.topologySignature).not.toBe(prepared.topologySignature);
@@ -351,7 +353,7 @@ describe('GPU-driven production projection', () => {
     availability.scene.dispose();
   });
 
-  it('activates inside the renderer-owned URP graph and removes the CPU forward draw', async () => {
+  it('activates inside the renderer-owned clustered Standard graph and removes the CPU draw', async () => {
     const canvas = {
       width: 1,
       height: 1,
@@ -380,6 +382,12 @@ describe('GPU-driven production projection', () => {
         { component: MeshRenderer, data: {} },
       )
       .unwrap();
+    world
+      .spawn(
+        { component: Transform, data: { pos: [0, 0, 1] } },
+        { component: PointLight, data: {} },
+      )
+      .unwrap();
 
     for (let frame = 0; frame < 4; frame += 1) {
       world.update(1 / 60).unwrap();
@@ -391,18 +399,9 @@ describe('GPU-driven production projection', () => {
     world.update(1 / 60).unwrap();
     expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
     expect(renderer.perFramePassNames).toEqual(
-      expect.arrayContaining([
-        'gpu-driven.view-reset',
-        'gpu-driven.frustum-compact',
-        'gpu-driven.finalize-indirect',
-        'main',
-      ]),
+      expect.arrayContaining(['cluster-membership-producer', 'main', 'output-transform']),
     );
-    expect(renderer.perFramePassNames).toContain('output-transform');
-    // Storage-buffer LDR frames keep the scene linear until the one output
-    // transform writes the encoded surface; the GPU-driven indirect raster
-    // draw and that fullscreen pass are the only draws in this topology.
-    expect(device.totalDrawCount).toBe(2);
+    expect(device.totalDrawCount).toBeGreaterThan(0);
     expect(renderer.renderScene).toMatchObject({
       worldEntitiesScanned: 0,
       fullRebuilds: 1,

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

@@ -192,6 +192,7 @@ describe('GpuDrivenView graph projection', () => {
     const frameState = {
       compiledFrameGraph: null,
       compiledFrameGraphTopologyKey: null,
+      compiledFrameGraphGeneration: 0,
       retiredCompiledFrameGraphs: new Set(),
       activePipeline,
       installedPipelineConfig: undefined,
@@ -209,14 +210,14 @@ describe('GpuDrivenView graph projection', () => {
       pointShadow: [],
       spot: [],
     } as unknown as ExtractedLights;
-    const compile = (prepared: PreparedGpuDrivenFrame) =>
+    const compile = (prepared: PreparedGpuDrivenFrame, width = 1) =>
       ensureCompiledFrameGraph(
         internals,
         frameState,
         pipelineState,
         makeZeroCameraFallbackSnapshot(),
         lights,
-        1,
+        width,
         1,
         undefined,
         prepared,
@@ -243,6 +244,7 @@ describe('GpuDrivenView graph projection', () => {
     const compiledPrevious = compile(preparedFrame(view));
     expect(compiledPrevious).not.toBeNull();
     if (compiledPrevious === null) return;
+    expect(frameState.compiledFrameGraphGeneration).toBe(1);
 
     Object.defineProperty(device, 'surfaceViewFormats', {
       configurable: true,
@@ -269,7 +271,8 @@ describe('GpuDrivenView graph projection', () => {
 
     expect(view.inspect()).toMatchObject({ candidateCount: 2, candidateCapacity: 2 });
     forceCompileFailure = true;
-    expect(compile(preparedFrame(view))).toBe(compiledPrevious);
+    expect(compile(preparedFrame(view), 2)).toBe(compiledPrevious);
+    expect(frameState.compiledFrameGraphGeneration).toBe(1);
     expect(errors).toHaveLength(1);
     expect(destroyBuffer.mock.calls.some(([buffer]) => buffer === previousVisible)).toBe(false);
     const encoder = device.createCommandEncoder({ label: 'gpu-driven-view-lkg' }).unwrap();
@@ -277,13 +280,18 @@ describe('GpuDrivenView graph projection', () => {
 
     forceCompileFailure = false;
     const retirePrevious = vi.spyOn(compiledPrevious, 'retire');
-    const acceptedGraph = compile(preparedFrame(view));
+    const acceptedGraph = compile(preparedFrame(view), 2);
     expect(acceptedGraph).not.toBe(compiledPrevious);
+    expect(frameState.compiledFrameGraphGeneration).toBe(2);
     expect(retirePrevious).toHaveBeenCalledOnce();
     await device.queue.onSubmittedWorkDone();
     await Promise.resolve();
     expect(destroyBuffer.mock.calls.some(([buffer]) => buffer === previousVisible)).toBe(true);
 
+    const returnedToPreviousTopology = compile(preparedFrame(view), 1);
+    expect(returnedToPreviousTopology).not.toBe(acceptedGraph);
+    expect(frameState.compiledFrameGraphGeneration).toBe(3);
+
     view.dispose();
     sceneAvailability.scene.dispose();
   });

package/src/__tests__/gpu-pass-timing-browser-runner.ts

@@ -0,0 +1,281 @@
+import { World } from '@forgeax/engine-ecs';
+import { rhi } from '@forgeax/engine-rhi-webgpu';
+import { Transform } from '@forgeax/engine-scene';
+import { createRenderer, exposeRenderer } from '../assembly/factory.js';
+import { Camera } from '../components/camera.js';
+import type { GpuPassTimingFrame } from '../record/gpu-pass-timing/contract.js';
+import type { FrameReceipt, Renderer, RenderWorldLease } from '../render-contract.js';
+
+export interface BrowserGpuPassTimingBenchDraw {
+  readonly token: number;
+  readonly frameDurationMicroseconds: number;
+}
+
+export interface BrowserGpuPassTimingBenchObservation {
+  readonly status: 'complete' | 'partial' | 'failed' | 'unavailable';
+  readonly frame?: GpuPassTimingFrame | undefined;
+}
+
+export interface BrowserGpuPassTimingBenchController {
+  readonly supported: boolean;
+  readonly realGpu: boolean;
+  readonly backend: string;
+  readonly frameGeneration: string;
+  readonly draw: (timingEnabled: boolean) => BrowserGpuPassTimingBenchDraw;
+  readonly observe: (token: number) => Promise<BrowserGpuPassTimingBenchObservation>;
+  readonly dispose: () => Promise<void>;
+}
+
+interface BrowserTimingFixture {
+  readonly renderer: Renderer;
+  readonly world: World;
+  readonly lease: RenderWorldLease;
+  readonly canvas: HTMLCanvasElement;
+}
+
+interface BrowserPendingFrame {
+  readonly fixture: BrowserTimingFixture;
+  readonly receipt: FrameReceipt;
+  readonly timingEnabled: boolean;
+}
+
+function createTimingCamera(world: World): void {
+  world
+    .spawn(
+      { component: Transform, data: { pos: [0, 0, 5], quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
+      {
+        component: Camera,
+        data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 },
+      },
+    )
+    .unwrap();
+  world.update(1 / 60).unwrap();
+}
+
+async function createBrowserTimingFixture(timingEnabled: boolean): Promise<BrowserTimingFixture> {
+  const canvas = document.createElement('canvas');
+  canvas.width = 32;
+  canvas.height = 32;
+  canvas.style.width = '32px';
+  canvas.style.height = '32px';
+  document.body.append(canvas);
+  let renderer: Renderer | undefined;
+  try {
+    const implementation = await createRenderer(
+      canvas,
+      timingEnabled
+        ? {
+            rhi,
+            gpuPassTiming: { maxPassesPerFrame: 64, maxFramesInFlight: 2, retentionFrames: 8 },
+          }
+        : { rhi },
+      { shaderManifestUrl: '/shaders/manifest.json' },
+    );
+    const ready = await implementation.initialization;
+    if (!ready.ok) throw new Error(`${ready.error.code}: ${ready.error.hint}`);
+    renderer = exposeRenderer(implementation);
+    const world = new World();
+    const attached = renderer.attach(world);
+    if (!attached.ok) throw new Error(attached.error.hint);
+    createTimingCamera(world);
+    return { renderer, world, lease: attached.value, canvas };
+  } catch (error) {
+    if (renderer !== undefined) await renderer.dispose();
+    canvas.remove();
+    throw error;
+  }
+}
+
+function drawTimingFrame(fixture: BrowserTimingFixture): {
+  readonly receipt: FrameReceipt;
+  readonly frameDurationMicroseconds: number;
+} {
+  const startedAt = performance.now();
+  fixture.world.update(1 / 60).unwrap();
+  const drawn = fixture.renderer.draw({
+    leases: [fixture.lease],
+    camera: { lease: fixture.lease },
+    environment: { lease: fixture.lease },
+  });
+  if (!drawn.ok) throw new Error(drawn.error.hint);
+  return {
+    receipt: drawn.value,
+    frameDurationMicroseconds: Math.max((performance.now() - startedAt) * 1000, 0.001),
+  };
+}
+
+function adapterString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+export async function createBrowserGpuPassTimingBenchController(): Promise<BrowserGpuPassTimingBenchController> {
+  const offFixture = await createBrowserTimingFixture(false);
+  let onFixture: BrowserTimingFixture | undefined;
+  try {
+    const timingFixture = await createBrowserTimingFixture(true);
+    onFixture = timingFixture;
+    const adapter = await navigator.gpu?.requestAdapter();
+    const adapterInfo = adapter?.info as Record<string, unknown> | undefined;
+    const adapterParts = [
+      adapterInfo?.vendor,
+      adapterInfo?.architecture,
+      adapterInfo?.device,
+      adapterInfo?.description,
+    ]
+      .map(adapterString)
+      .filter((part): part is string => part !== undefined);
+    const backend = adapterParts.join('/') || 'browser-adapter-unknown';
+    const realGpu =
+      adapter !== null &&
+      adapter !== undefined &&
+      !/swiftshader|llvmpipe|software|basic renderer/i.test(backend);
+    const inspection = timingFixture.renderer.inspect();
+    const pending = new Map<number, BrowserPendingFrame>();
+    let nextToken = 1;
+    let disposed = false;
+
+    return {
+      supported: inspection.capabilities.timestampQuery,
+      realGpu,
+      backend,
+      frameGeneration: `device-${inspection.frame.deviceGeneration}:graph-standard`,
+      draw: (timingEnabled) => {
+        if (disposed) throw new Error('browser GPU pass timing controller is disposed');
+        const fixture = timingEnabled ? timingFixture : offFixture;
+        const drawn = drawTimingFrame(fixture);
+        const token = nextToken;
+        nextToken += 1;
+        pending.set(token, {
+          fixture,
+          receipt: drawn.receipt,
+          timingEnabled,
+        });
+        return { token, frameDurationMicroseconds: drawn.frameDurationMicroseconds };
+      },
+      observe: async (token) => {
+        const frame = pending.get(token);
+        if (frame === undefined) throw new Error(`unknown browser timing frame token: ${token}`);
+        pending.delete(token);
+        const observed = await frame.fixture.renderer.observe(frame.receipt, {
+          include: frame.timingEnabled ? ['timings'] : [],
+        });
+        if (!observed.ok) return { status: 'failed' };
+        if (!frame.timingEnabled) return { status: 'complete' };
+        switch (observed.value.timings?.status) {
+          case 'complete':
+            return { status: 'complete', frame: observed.value.timings.frame };
+          case 'partial':
+            return { status: 'partial', frame: observed.value.timings.frame };
+          case 'unavailable':
+            return { status: 'unavailable' };
+          case 'failed':
+          case undefined:
+            return { status: 'failed' };
+        }
+      },
+      dispose: async () => {
+        if (disposed) return;
+        disposed = true;
+        pending.clear();
+        let firstError: unknown;
+        for (const fixture of [offFixture, timingFixture]) {
+          const disposedRenderer = await fixture.renderer.dispose();
+          fixture.canvas.remove();
+          if (!disposedRenderer.ok && firstError === undefined) firstError = disposedRenderer.error;
+        }
+        if (firstError !== undefined)
+          throw new Error(`browser benchmark dispose failed: ${String(firstError)}`);
+      },
+    };
+  } catch (error) {
+    await offFixture.renderer.dispose();
+    offFixture.canvas.remove();
+    if (onFixture !== undefined) {
+      await onFixture.renderer.dispose();
+      onFixture.canvas.remove();
+    }
+    throw error;
+  }
+}
+
+export async function runBrowserGpuPassTiming(
+  options: { readonly suppressRaster?: boolean } = {},
+): Promise<{
+  readonly supported: boolean;
+  readonly frames: number;
+  readonly unavailable: boolean;
+  readonly measuredPasses: number;
+  readonly visible: boolean;
+  readonly rasterSuppressed: boolean;
+}> {
+  const canvas = document.createElement('canvas');
+  canvas.width = 64;
+  canvas.height = 64;
+  document.body.append(canvas);
+  if (options.suppressRaster === true) canvas.style.visibility = 'hidden';
+  const implementation = await createRenderer(
+    canvas,
+    { rhi, gpuPassTiming: { maxPassesPerFrame: 64, maxFramesInFlight: 2, retentionFrames: 8 } },
+    { shaderManifestUrl: '/shaders/manifest.json' },
+  );
+  const ready = await implementation.initialization;
+  if (!ready.ok) throw new Error(`${ready.error.code}: ${ready.error.hint}`);
+  const renderer = exposeRenderer(implementation);
+  const world = new World();
+  const attached = renderer.attach(world);
+  if (!attached.ok) throw new Error(attached.error.hint);
+  world
+    .spawn(
+      { component: Transform, data: { pos: [0, 0, 5], quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
+      {
+        component: Camera,
+        data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 },
+      },
+    )
+    .unwrap();
+  world.update(1 / 60).unwrap();
+  const supported = renderer.inspect().capabilities.timestampQuery;
+  let frames = 0;
+  let unavailable = false;
+  let measuredPasses = 0;
+  try {
+    for (let index = 0; index < 3; index += 1) {
+      world.update(1 / 60).unwrap();
+      const drawn = renderer.draw({
+        leases: [attached.value],
+        camera: { lease: attached.value },
+        environment: { lease: attached.value },
+      });
+      if (!drawn.ok) continue;
+      const observed = await renderer.observe(drawn.value, { include: ['timings'] });
+      if (!observed.ok) continue;
+      frames += 1;
+      if (observed.value.timings?.status === 'unavailable') {
+        unavailable = true;
+        if ('tick' in observed.value.timings || 'durationNanoseconds' in observed.value.timings) {
+          throw new Error('unavailable timing observation exposed numeric GPU facts');
+        }
+        continue;
+      }
+      if (
+        observed.value.timings?.status === 'complete' ||
+        observed.value.timings?.status === 'partial'
+      ) {
+        measuredPasses += observed.value.timings.frame.passes.filter(
+          (pass) => pass.status === 'measured',
+        ).length;
+      }
+    }
+  } finally {
+    await renderer.dispose();
+    canvas.remove();
+  }
+  return {
+    supported,
+    frames,
+    unavailable,
+    measuredPasses,
+    visible: !document.body.contains(canvas),
+    rasterSuppressed: options.suppressRaster === true,
+  };
+}

package/src/__tests__/gpu-pass-timing-coexistence.integration.test.ts

@@ -0,0 +1,80 @@
+import type { Buffer, QuerySet, RhiCommandEncoder, RhiDevice } from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import {
+  createGpuPassTimingSession,
+  type GpuPassTimingFrameIdentity,
+} from '../record/gpu-pass-timing/session.js';
+
+function makeDevice() {
+  const device = {
+    caps: {
+      backendKind: 'webgpu',
+      timestampQuery: true,
+      timestampPeriodNanoseconds: 1,
+    },
+    createQuerySet: vi.fn(() => ok({} as QuerySet)),
+    createBuffer: vi.fn(() => ok({} as Buffer)),
+    destroyQuerySet: vi.fn(() => ok(undefined)),
+    destroyBuffer: vi.fn(() => ok(undefined)),
+    queue: { onSubmittedWorkDone: vi.fn(async () => undefined) },
+  } as unknown as RhiDevice;
+  return device;
+}
+
+const identity: GpuPassTimingFrameIdentity = {
+  frameId: 3,
+  deviceGeneration: 1,
+  graphGeneration: 22,
+};
+
+describe('GPU pass timing coexistence with producer-owned timestamps', () => {
+  it('keeps the producer timestamp owner and reports generic timing as unmeasured', async () => {
+    const device = makeDevice();
+    const session = createGpuPassTimingSession(device, {
+      maxPassesPerFrame: 2,
+      maxFramesInFlight: 1,
+      retentionFrames: 8,
+    }).unwrap();
+    const capture = session.beginFrame(identity).unwrap();
+    const producerPass = {
+      passName: 'cluster-membership-producer',
+      passKind: 'compute' as const,
+      executionIndex: 0,
+    };
+    capture.recordPass(producerPass);
+    capture.markOwnerConflict(producerPass);
+
+    expect(capture.timestampWrites(producerPass)).toBeUndefined();
+    expect(capture.snapshot()).toMatchObject({
+      measuredPassCount: 0,
+      passes: [
+        {
+          passName: 'cluster-membership-producer',
+          status: 'unmeasured',
+          reason: { code: 'timestamp-owner-conflict' },
+        },
+      ],
+    });
+    const commandEncoder = {
+      encodeEmptyComputePass: vi.fn(),
+      resolveQuerySet: vi.fn(() => ok(undefined)),
+      copyBufferToBuffer: vi.fn(),
+    } as unknown as RhiCommandEncoder;
+    expect(capture.encodeTail(commandEncoder)).toMatchObject({ ok: true });
+    expect(commandEncoder.resolveQuerySet).not.toHaveBeenCalled();
+    expect(commandEncoder.copyBufferToBuffer).not.toHaveBeenCalled();
+    capture.markSubmitted();
+    expect(device.queue.onSubmittedWorkDone).not.toHaveBeenCalled();
+    await expect(capture.observe()).resolves.toMatchObject({
+      ok: true,
+      value: {
+        frameId: 3,
+        deviceGeneration: 1,
+        graphGeneration: 22,
+        passes: [{ passName: 'cluster-membership-producer', executionIndex: 0 }],
+      },
+    });
+    session.dispose();
+  });
+});