@forgeax/engine-render 0.1.20 → 0.1.23

package/src/__tests__/gpu-lod-readiness.integration.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+import { buildGpuLodRows, selectGpuLod } from '../scene/visibility/gpu-lod';
+
+describe('GPU LOD readiness projection', () => {
+  it('keeps the root ready fallback when a selected lower level is not resident', () => {
+    const rows = buildGpuLodRows({
+      generation: 11,
+      hysteresis: 0,
+      ranges: [
+        { firstIndex: 0, indexCount: 36, baseVertex: 0 },
+        { firstIndex: 36, indexCount: 18, baseVertex: 0 },
+        { firstIndex: 54, indexCount: 6, baseVertex: 0 },
+      ],
+      coverages: [1, 0.5, 0.2],
+      ready: [true, false, false],
+    });
+
+    expect(
+      selectGpuLod(rows, { projectedHeight: 0.1, previousLevel: 0, historyValid: false }),
+    ).toEqual({
+      level: 0,
+      confidence: 1,
+    });
+    expect(
+      selectGpuLod(rows, { projectedHeight: 0.6, previousLevel: 0, historyValid: false }),
+    ).toEqual({
+      level: 0,
+      confidence: 1,
+    });
+  });
+
+  it('uses absolute coverage with hysteresis, not cross-level distances', () => {
+    const rows = buildGpuLodRows({
+      generation: 12,
+      hysteresis: 0.1,
+      ranges: [
+        { firstIndex: 0, indexCount: 36, baseVertex: 0 },
+        { firstIndex: 36, indexCount: 18, baseVertex: 0 },
+        { firstIndex: 54, indexCount: 6, baseVertex: 0 },
+      ],
+      coverages: [1, 0.5, 0.2],
+      ready: [true, true, true],
+    });
+
+    expect(
+      selectGpuLod(rows, { projectedHeight: 0.49, previousLevel: 1, historyValid: true }).level,
+    ).toBe(1);
+    expect(
+      selectGpuLod(rows, { projectedHeight: 0.1, previousLevel: 1, historyValid: true }).level,
+    ).toBe(2);
+  });
+});

package/src/__tests__/gpu-lod-schema.unit.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest';
+import {
+  buildGpuLodRows,
+  encodeGpuLodRows,
+  GPU_LOD_ROW_LAYOUT,
+  GPU_LOD_ROW_SCHEMA,
+} from '../scene/visibility/gpu-lod';
+
+describe('GPU LOD row schema', () => {
+  it('projects absolute coverage and stable draw-template ranges into rows', () => {
+    const rows = buildGpuLodRows({
+      generation: 7,
+      hysteresis: 0.1,
+      ranges: [
+        { firstIndex: 0, indexCount: 120, baseVertex: 0 },
+        { firstIndex: 120, indexCount: 60, baseVertex: 0 },
+        { firstIndex: 180, indexCount: 24, baseVertex: 0 },
+      ],
+      coverages: [1, 0.5, 0.2],
+      ready: [true, true, false],
+    });
+
+    expect(rows).toHaveLength(3);
+    expect(rows[1]).toMatchObject({
+      generation: 7,
+      level: 1,
+      screenCoverage: 0.5,
+      firstIndex: 120,
+      indexCount: 60,
+      ready: true,
+    });
+    expect(rows[2]?.ready).toBe(false);
+    expect(GPU_LOD_ROW_SCHEMA.fields.map((field) => field.name)).toEqual([
+      'generation',
+      'level',
+      'firstIndex',
+      'indexCount',
+      'baseVertex',
+      'screenCoverage',
+      'hysteresis',
+      'ready',
+    ]);
+    expect(GPU_LOD_ROW_LAYOUT.stride).toBe(32);
+  });
+
+  it('encodes the same bytes for CPU and GPU consumers', () => {
+    const rows = buildGpuLodRows({
+      generation: 3,
+      hysteresis: 0.05,
+      ranges: [
+        { firstIndex: 0, indexCount: 36, baseVertex: -2 },
+        { firstIndex: 36, indexCount: 12, baseVertex: -2 },
+      ],
+      coverages: [1, 0.25],
+      ready: [true, true],
+    });
+    const bytes = encodeGpuLodRows(rows);
+    expect(bytes.byteLength).toBe(GPU_LOD_ROW_LAYOUT.stride * rows.length);
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    expect(view.getUint32(0, true)).toBe(3);
+    expect(view.getUint32(4, true)).toBe(0);
+    expect(view.getInt32(16, true)).toBe(-2);
+    expect(view.getFloat32(20, true)).toBe(1);
+    expect(view.getUint32(GPU_LOD_ROW_LAYOUT.stride + 28, true)).toBe(1);
+  });
+});

package/src/__tests__/gpu-lod-selector.unit.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+import { GPU_DRIVEN_VIEW_WGSL, selectGpuLodLane } from '../gpu-driven/view-gpu';
+
+describe('GPU LOD selector lane', () => {
+  it('contains the same absolute threshold and readiness inputs as the CPU reference', () => {
+    expect(GPU_DRIVEN_VIEW_WGSL).toContain('screenCoverage');
+    expect(GPU_DRIVEN_VIEW_WGSL).toContain('hysteresis');
+    expect(GPU_DRIVEN_VIEW_WGSL).toContain('ready');
+    expect(GPU_DRIVEN_VIEW_WGSL).toContain('selectLodLevel');
+  });
+
+  it('keeps GPU-driven candidates without authored bounds conservatively visible', () => {
+    expect(GPU_DRIVEN_VIEW_WGSL).toContain('if ((primitive.flags & 5u) != 5u) { return false; }');
+    expect(GPU_DRIVEN_VIEW_WGSL).toContain('if ((primitive.flags & 2u) == 0u) { return true; }');
+  });
+
+  it('selects the GPU lane only when all required storage capabilities exist', () => {
+    expect(selectGpuLodLane({ compute: true, storageBuffer: true, indirectDrawing: true })).toBe(
+      'gpu',
+    );
+    expect(selectGpuLodLane({ compute: false, storageBuffer: true, indirectDrawing: true })).toBe(
+      'cpu',
+    );
+    expect(selectGpuLodLane({ compute: true, storageBuffer: false, indirectDrawing: true })).toBe(
+      'cpu',
+    );
+  });
+});

package/src/__tests__/gpu-lod-silhouette.browser.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest';
+import { runGpuLodSilhouetteEvidence } from './gpu-lod-evidence';
+
+const browserReady = typeof navigator !== 'undefined' && navigator.gpu !== undefined;
+
+describe.skipIf(!browserReady)('GPU LOD Browser silhouette evidence', () => {
+  it('publishes distinct composite silhouettes with matching identity', () => {
+    const evidence = runGpuLodSilhouetteEvidence();
+    expect(evidence.status).toBe('available');
+    expect(new Set(evidence.levelSignatures).size).toBe(3);
+    expect(evidence.identity.view).toContain('lod-evidence-view');
+  });
+});

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();
+  });
+});