@forgeax/engine-render 0.1.20 → 0.1.23

package/src/record/__tests__/gpu-timing.unit.test.ts

@@ -0,0 +1,177 @@
+import type { Buffer, QuerySet, RhiCommandEncoder, RhiDevice } from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import { GPU_BUFFER_USAGE_MAP_READ } from '../../gpu-usage';
+import { GpuTimingCapture } from '../gpu-timing';
+
+function timestampDevice(readbackBytes: ArrayBuffer): {
+  readonly device: RhiDevice;
+  readonly encoder: RhiCommandEncoder;
+  readonly resolveQuerySet: ReturnType<typeof vi.fn>;
+  readonly readbackBuffer: Buffer;
+  readonly getMappedRange: ReturnType<typeof vi.fn>;
+  readonly destroyBuffer: ReturnType<typeof vi.fn>;
+  readonly destroyQuerySet: ReturnType<typeof vi.fn>;
+} {
+  const querySet = {} as QuerySet;
+  const resolveBuffer = {} as Buffer;
+  const getMappedRange = vi.fn(() => ok(readbackBytes));
+  const unmap = vi.fn();
+  const readbackBuffer = {
+    mapAsync: vi.fn(async (mode: number) => {
+      expect(mode).toBe(GPU_BUFFER_USAGE_MAP_READ);
+      return ok({
+        getMappedRange,
+        unmap,
+      } as never);
+    }),
+  } as unknown as Buffer;
+  let bufferIndex = 0;
+  const resolveQuerySet = vi.fn(() => ok(undefined));
+  const destroyBuffer = vi.fn(() => ok(undefined));
+  const destroyQuerySet = vi.fn(() => ok(undefined));
+  const encoder = {
+    resolveQuerySet,
+    copyBufferToBuffer: vi.fn(),
+  } as unknown as RhiCommandEncoder;
+  const device = {
+    caps: {
+      backendKind: 'webgpu',
+      compute: true,
+      storageBuffer: true,
+      storageTexture: true,
+      timestampQuery: true,
+      timestampPeriodNanoseconds: 1,
+      indirectDrawing: true,
+      textureCompressionBc: false,
+      textureCompressionEtc2: false,
+      textureCompressionAstc: false,
+      multiDrawIndirect: false,
+      pushConstants: false,
+      textureBindingArray: false,
+      samplerAliasing: true,
+      firstInstanceIndirect: true,
+      rgba16floatRenderable: true,
+      rg11b10ufloatRenderable: true,
+      float32Filterable: true,
+      maxColorAttachments: 8,
+    },
+    createQuerySet: vi.fn(() => ok(querySet)),
+    createBuffer: vi.fn(() => {
+      bufferIndex += 1;
+      return ok(bufferIndex === 1 ? resolveBuffer : readbackBuffer);
+    }),
+    destroyQuerySet,
+    destroyBuffer,
+    queue: { onSubmittedWorkDone: vi.fn(async () => undefined) },
+  } as unknown as RhiDevice;
+  return {
+    device,
+    encoder,
+    resolveQuerySet,
+    readbackBuffer,
+    getMappedRange,
+    destroyBuffer,
+    destroyQuerySet,
+  };
+}
+
+function writeTimestampPair(bytes: ArrayBuffer, index: number, begin: bigint, end: bigint): void {
+  const view = new DataView(bytes);
+  view.setBigUint64(index * 16, begin, true);
+  view.setBigUint64(index * 16 + 8, end, true);
+}
+
+describe('GpuTimingCapture pass descriptor contract', () => {
+  it('resolves real pass pairs without calling command-encoder writeTimestamp', async () => {
+    const bytes = new ArrayBuffer(64 * 8);
+    writeTimestampPair(bytes, 0, 100n, 200n);
+    writeTimestampPair(bytes, 1, 210n, 450n);
+    const { device, encoder, resolveQuerySet } = timestampDevice(bytes);
+    const created = GpuTimingCapture.create(device);
+    expect(created.ok).toBe(true);
+    if (!created.ok || created.value === undefined) return;
+
+    const first = created.value.beginPass('volume-inject', 'compute', 3);
+    const second = created.value.beginPass('volume-integrate', 'raster', 9);
+    expect(first).toMatchObject({ beginningOfPassWriteIndex: 0, endOfPassWriteIndex: 1 });
+    expect(second).toMatchObject({ beginningOfPassWriteIndex: 2, endOfPassWriteIndex: 3 });
+    expect((encoder as unknown as { writeTimestamp?: unknown }).writeTimestamp).toBeUndefined();
+
+    expect(created.value.resolve(encoder).ok).toBe(true);
+    expect(resolveQuerySet).toHaveBeenCalledWith(expect.anything(), 0, 4, expect.anything(), 0);
+    created.value.markSubmitted();
+    await expect(created.value.observation()).resolves.toEqual({
+      status: 'ready',
+      unit: 'ms',
+      frameMs: 0.00035,
+      totalMs: 0.00035,
+      passes: [
+        { name: 'volume-inject', milliseconds: 0.0001 },
+        { name: 'volume-integrate', milliseconds: 0.00024 },
+      ],
+    });
+  });
+
+  it('fails closed when a producer already owns the pass timestamp pair', async () => {
+    const { device, encoder } = timestampDevice(new ArrayBuffer(64 * 8));
+    const created = GpuTimingCapture.create(device);
+    expect(created.ok).toBe(true);
+    if (!created.ok || created.value === undefined) return;
+    expect(created.value.beginPass('volume-inject', 'compute', 0)).toBeDefined();
+    created.value.markOwnerConflict('volume-inject');
+    expect(created.value.resolve(encoder).ok).toBe(true);
+    created.value.markSubmitted();
+    await expect(created.value.observation()).resolves.toEqual({
+      status: 'unavailable',
+      reason: "timestamp pass 'volume-inject' already has producer-owned timestampWrites",
+    });
+  });
+
+  it('disposes query and buffer resources when readback mapping fails', async () => {
+    const { device, encoder, readbackBuffer, destroyBuffer, destroyQuerySet } = timestampDevice(
+      new ArrayBuffer(64 * 8),
+    );
+    const mapAsync = readbackBuffer.mapAsync as unknown as ReturnType<typeof vi.fn>;
+    mapAsync.mockResolvedValue({
+      ok: false,
+      error: { code: 'webgpu-runtime-error' },
+    });
+    const created = GpuTimingCapture.create(device);
+    expect(created.ok).toBe(true);
+    if (!created.ok || created.value === undefined) return;
+
+    expect(created.value.beginPass('volume-inject', 'compute', 0)).toBeDefined();
+    expect(created.value.resolve(encoder).ok).toBe(true);
+    created.value.markSubmitted();
+    await expect(created.value.observation()).resolves.toEqual({
+      status: 'unavailable',
+      reason: 'timestamp readback failed: webgpu-runtime-error',
+    });
+    expect(destroyBuffer).toHaveBeenCalledTimes(2);
+    expect(destroyQuerySet).toHaveBeenCalledTimes(1);
+  });
+
+  it('disposes query and buffer resources when mapped range access fails', async () => {
+    const { device, encoder, getMappedRange, destroyBuffer, destroyQuerySet } = timestampDevice(
+      new ArrayBuffer(64 * 8),
+    );
+    getMappedRange.mockReturnValue({
+      ok: false,
+      error: { code: 'webgpu-runtime-error' },
+    });
+    const created = GpuTimingCapture.create(device);
+    expect(created.ok).toBe(true);
+    if (!created.ok || created.value === undefined) return;
+
+    expect(created.value.beginPass('volume-inject', 'compute', 0)).toBeDefined();
+    expect(created.value.resolve(encoder).ok).toBe(true);
+    created.value.markSubmitted();
+    await expect(created.value.observation()).resolves.toEqual({
+      status: 'unavailable',
+      reason: 'timestamp mapping failed: webgpu-runtime-error',
+    });
+    expect(destroyBuffer).toHaveBeenCalledTimes(2);
+    expect(destroyQuerySet).toHaveBeenCalledTimes(1);
+  });
+});

package/src/record/__tests__/temporal-payload.unit.test.ts

@@ -2,7 +2,7 @@ import { vec3 } from '@forgeax/engine-math';
 import type { Buffer, RhiQueue } from '@forgeax/engine-rhi';
 import { describe, expect, it } from 'vitest';
 import type { CameraSnapshot } from '../../render-contract';
-import type { RenderableSnapshot } from '../../render-system-extract';
+import type { RenderableSnapshot, SpotLightSnapshot } from '../../render-system-extract';
 import type { TemporalView } from '../../temporal/temporal-view';
 import type { ValidatedRenderable } from '../frame-snapshot';
 import { uploadMeshSsboBatch } from '../mesh-ssbo';
@@ -98,6 +98,46 @@ function temporalView(): TemporalView {
 }
 
 describe('temporal GPU payloads', () => {
+  it('publishes a projector-only SpotLight matrix into the explicit lane-0 contract', () => {
+    const { queue, uploads } = recordingQueue();
+    const projectorMatrix = translatedMatrix(9);
+    const projector: SpotLightSnapshot = {
+      kind: 'spot',
+      entity: 4,
+      position: vec3.create(0, 2, 0),
+      direction: vec3.create(0, -1, 0),
+      color: vec3.create(1, 1, 1),
+      intensity: 1,
+      invRangeSquared: 0.04,
+      cosInner: 0.95,
+      cosOuter: 0.8,
+      castShadow: false,
+      lightViewProj: projectorMatrix,
+      mapSize: 512,
+      nearPlane: 0.1,
+      farPlane: 25,
+      shadowAtlasTile: -1,
+      projectorAsset: { kind: 'texture' } as never,
+    };
+    writeViewUbo(
+      queue,
+      {} as Buffer,
+      camera(),
+      {
+        kind: 'directional',
+        direction: vec3.create(0, -1, 0),
+        color: vec3.create(1, 1, 1),
+        intensity: 1,
+      },
+      { point: [], spot: [projector] } as never,
+      [projector],
+      undefined,
+      0,
+    );
+    const payload = new Float32Array(uploads[0]?.buffer ?? new ArrayBuffer(0));
+    expect(payload[132 + 12]).toBe(9);
+  });
+
   it('writes temporal current/previous projection after the spot-light lanes', () => {
     const { queue, uploads } = recordingQueue();
     writeViewUbo(
@@ -124,6 +164,29 @@ describe('temporal GPU payloads', () => {
     expect(payload[230]).toBe(0);
   });
 
+  it('keeps the accepted previous camera in the temporal ABI', () => {
+    const { queue, uploads } = recordingQueue();
+    const acceptedCamera = [7, 8, 9] as const;
+    const temporal = { ...temporalView(), previousCameraPosition: acceptedCamera };
+    writeViewUbo(
+      queue,
+      {} as Buffer,
+      camera(),
+      {
+        kind: 'directional',
+        direction: vec3.create(0, -1, 0),
+        color: vec3.create(1, 1, 1),
+        intensity: 1,
+      },
+      { point: [], spot: [] } as never,
+      [],
+      temporal as never,
+    );
+
+    const payload = new Float32Array(uploads[0]?.buffer ?? new ArrayBuffer(0));
+    expect(Array.from(payload.slice(232, 236))).toEqual([...acceptedCamera, 1]);
+  });
+
   it('seeds previousWorld on the first frame and uses the submitted snapshot later', () => {
     const first = translatedMatrix(4);
     const previous = translatedMatrix(2);

package/src/record/__tests__/transparent-group2-selection.unit.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest';
+import { selectPipelineLayoutForVariant } from '../../assembly/factory';
+import { resolvePipelineGroup2Contract } from '../../pbr-pipeline';
+import { projectDeviceOwnedBindGroup } from '../frame-lighting';
+import { selectMaterialGroup2 } from '../main-pass-material';
+
+const meshGroup = { label: 'pbr-mesh-bg' } as never;
+const clusterGroup = { label: 'hdrp-unified-bg-group2' } as never;
+
+describe('transparent material group 2 selection', () => {
+  it('uses the shared cluster layout only for standard materials', () => {
+    expect(selectMaterialGroup2(clusterGroup, meshGroup, 'cluster')).toBe(clusterGroup);
+    expect(selectMaterialGroup2(clusterGroup, meshGroup, 'mesh')).toBe(meshGroup);
+  });
+
+  it('returns null when a non-standard material lacks its ordinary mesh group', () => {
+    expect(selectMaterialGroup2(clusterGroup, null, 'mesh')).toBeNull();
+  });
+
+  it('resolves mesh, skin, and clustered skin from the composed shader artifact', () => {
+    expect(
+      resolvePipelineGroup2Contract('@group(2) @binding(0) var<storage> mesh: array<u32>;'),
+    ).toBe('mesh');
+    expect(
+      resolvePipelineGroup2Contract(
+        '@group(2) @binding(0) var<storage> mesh: array<u32>; @group(2) @binding(1) var<uniform> palette: mat4x4<f32>;',
+      ),
+    ).toBe('skin');
+    expect(
+      resolvePipelineGroup2Contract(
+        '@group(2) @binding(0) var<storage> mesh: array<u32>; @group(2) @binding(1) var<storage> palette: array<u32>; @group(2) @binding(4) var<storage> lights: array<u32>;',
+      ),
+    ).toBe('skin-cluster');
+  });
+
+  it('lets the resolved clustered contract select the unified group', () => {
+    expect(selectMaterialGroup2(clusterGroup, meshGroup, 'cluster')).toBe(clusterGroup);
+    expect(selectMaterialGroup2(clusterGroup, meshGroup, 'skin')).toBeNull();
+    // A skin-cluster PSO cannot consume the ordinary HDRP group. The caller
+    // must provide the dedicated skin bind group through the skin path; when
+    // it is absent, fail-stop instead of submitting a layout-invalid draw.
+    expect(selectMaterialGroup2(clusterGroup, meshGroup, 'skin-cluster')).toBeNull();
+  });
+
+  it('keeps a mesh contract on the mesh pipeline despite the HDRP variant key', () => {
+    const pbrPipelineLayout = { label: 'pbr-pl' } as never;
+    const hdrpPipelineLayout = { label: 'hdrp-pbr-pl' } as never;
+    expect(
+      selectPipelineLayoutForVariant(
+        {
+          pbrPipelineLayout,
+          hdrpPbrPipelineLayout: hdrpPipelineLayout,
+          pbrSkinPipelineLayout: null,
+          hdrpSkinPipelineLayout: null,
+        },
+        '',
+        'pbr',
+      ),
+    ).toBe(pbrPipelineLayout);
+  });
+
+  it('rejects membership bindings from a retired device or layout', () => {
+    const deviceA = {} as never;
+    const deviceB = {} as never;
+    const layoutA = {} as never;
+    const layoutB = {} as never;
+    const bindGroup = {} as never;
+    const state = { device: deviceA, layout: layoutA, bindGroup };
+    expect(projectDeviceOwnedBindGroup(state, deviceA, layoutA)).toBe(bindGroup);
+    expect(projectDeviceOwnedBindGroup(state, deviceB, layoutA)).toBeNull();
+    expect(projectDeviceOwnedBindGroup(state, deviceA, layoutB)).toBeNull();
+  });
+});

package/src/record/__tests__/typed-frame-graph-plan.unit.test.ts

@@ -19,6 +19,7 @@ const captureDescriptor = {
 
 type CaptureOverrides = {
   readonly target?: boolean;
+  readonly onSubmitted?: () => void;
   readonly descriptor?: {
     readonly format?: 'rgba16float' | 'rgba8unorm';
     readonly size?: { readonly width: number; readonly height: number };
@@ -74,7 +75,14 @@ function executeCapture(overrides: CaptureOverrides = {}) {
     errorRegistry: { fire: (error: unknown) => errors.push(error) },
     device: { queue: { submit: () => ok(undefined) } },
   } as never;
-  const submitted = executeCompiledFrameGraph(internals, frameState, {} as never, encoder);
+  const submitted = executeCompiledFrameGraph(
+    internals,
+    frameState,
+    {} as never,
+    encoder,
+    undefined,
+    overrides.onSubmitted === undefined ? undefined : { onSubmitted: overrides.onSubmitted },
+  );
   return { submitted, errors, copies };
 }
 
@@ -142,6 +150,17 @@ describe('typed frame graph feature plan authority', () => {
     expect(result.copies).toHaveLength(1);
   });
 
+  it('keeps the submit hook on the successful commit path', () => {
+    let calls = 0;
+    const result = executeCapture({
+      onSubmitted: () => {
+        calls += 1;
+      },
+    });
+    expect(result.submitted).toBe(true);
+    expect(calls).toBe(1);
+  });
+
   it.each([
     [
       'missing same-submit copy / untouched sentinel',

package/src/record/__tests__/view-ubo-layout.unit.test.ts

@@ -0,0 +1,40 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const viewUboSrc = readFileSync(fileURLToPath(new URL('../view-ubo.ts', import.meta.url)), 'utf8');
+const commonWgslSrc = readFileSync(
+  fileURLToPath(new URL('../../../..//shader/src/common.wgsl', import.meta.url)),
+  'utf8',
+);
+
+describe('View UBO directional shadow ABI', () => {
+  it('keeps the 960 B payload inside the existing 1024 B slot', () => {
+    expect(viewUboSrc).toMatch(/VIEW_UNIFORM_BYTES\s*=\s*960/);
+    expect(viewUboSrc).toMatch(/VIEW_UNIFORM_SLOT_STRIDE\s*=\s*1024/);
+    expect(viewUboSrc).toMatch(/VIEW_PAYLOAD_FLOATS\s*=\s*240/);
+  });
+
+  it('packs all four cascade metrics into the existing vec4 lanes', () => {
+    expect(viewUboSrc).toMatch(/viewPayload\[108 \+ s \* 4 \+ lane\]/);
+    expect(viewUboSrc).not.toMatch(/viewPayload\[108 \+ s \* 4\]\s*=\s*lights\.splitPlanes/);
+  });
+
+  it('keeps bias at [126]/[127], directional filter at [128..131], and Spot at 132', () => {
+    expect(viewUboSrc).toMatch(/viewPayload\[126\]\s*=\s*lights\.depthBias/);
+    expect(viewUboSrc).toMatch(/viewPayload\[127\]\s*=\s*lights\.normalBias/);
+    expect(viewUboSrc).toMatch(/viewPayload\[128\]/);
+    expect(viewUboSrc).toMatch(/viewPayload\[129\]/);
+    expect(viewUboSrc).toMatch(/viewPayload\[130\]/);
+    expect(viewUboSrc).toMatch(/viewPayload\[131\]/);
+    expect(viewUboSrc).toMatch(/SPOT_LVP_BASE_FLOAT\s*=\s*132/);
+    expect(viewUboSrc).not.toMatch(/lights\.pcfKernelSize/);
+  });
+
+  it('declares one shared View binding with a vec4 directional filter carrier', () => {
+    const viewStruct = commonWgslSrc.match(/struct View \{[\s\S]*?\n\};/)?.[0] ?? '';
+    expect(viewStruct).toMatch(/directionalShadowFilter\s*:\s*vec4<f32>/);
+    expect(viewStruct).not.toMatch(/pcfKernelSize/);
+    expect(commonWgslSrc.match(/@group\(0\) @binding\(0\) var<uniform> view/g)).toHaveLength(1);
+  });
+});