@forgeax/engine-render 0.1.31 → 0.1.33

package/src/__tests__/gpu-driven-baseline.characterization.test.ts

@@ -6,6 +6,7 @@ const read = (path: string): string => readFileSync(new URL(path, import.meta.ur
 const count = (source: string, pattern: RegExp): number => source.match(pattern)?.length ?? 0;
 
 const productionRaster = read('../gpu-driven/production-raster.ts');
+const mainPass = read('../record/main-pass.ts');
 const shadowPass = read('../record/shadow-pass.ts');
 const paletteAllocator = read('../systems/skin-palette-allocator.ts');
 const extractRoot = read('../render-system-extract.ts');
@@ -46,6 +47,17 @@ describe('GPU-driven baseline characterization', () => {
     expect(productionRaster).toContain('vertexLayout.arrayStride');
   });
 
+  it('keeps CPU-only video slots out of the global GPU receipt gate', () => {
+    expect(mainPass).toContain('videoTextureFields?.size');
+    expect(mainPass).toContain('if (gpuDrivenStandardPbrFrameResources === undefined)');
+    expect(mainPass).not.toContain(
+      'gpuDrivenStandardPbrFrameResources.materialBindGroups.some((group) => group === undefined)',
+    );
+    expect(productionRaster).toMatch(
+      /material bind group for global slot \$\{globalMaterialSlot\}/,
+    );
+  });
+
   it('freezes CPU shadow caster enumeration as the pre-GPU baseline', () => {
     expect(shadowPass).toContain('validatedOrdered');
     expect(shadowPass).toMatch(/for \(let i = 0; i < validatedOrdered\.length; i\+\+\)/);

package/src/__tests__/gpu-driven-indirect-raster-evidence.ts

@@ -110,7 +110,8 @@ function camera(): CameraSnapshot {
     bloom: 'off',
     bloomThreshold: 1,
     bloomIntensity: 1,
-    bloomBlurRadius: 4,
+    bloomSoftKnee: 0.5,
+    bloomScatter: 0.7,
     clearColor: [0, 0, 0, 0],
   };
 }

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

@@ -824,6 +824,7 @@ describe('GPU-driven production projection', () => {
         device.createBindGroup({ layout: materialBindGroup, entries: [] }).unwrap(),
       ],
     };
+    let activeFrameResources = frameResources;
     const color = graph
       .createTexture('gpu-driven-production-color', {
         format: 'rgba8unorm',
@@ -842,7 +843,8 @@ describe('GPU-driven production projection', () => {
             clearValue: { r: 0, g: 0, b: 0, a: 1 },
           },
         ],
-        encode: ({ pass, resources }) => gpu.encode(viewBindGroup, pass, resources, frameResources),
+        encode: ({ pass, resources }) =>
+          gpu.encode(viewBindGroup, pass, resources, activeFrameResources),
       })
       .unwrap();
     const compiled = graph.compile({ device, surfaceSize: { width: 1, height: 1 } }).unwrap();
@@ -872,6 +874,30 @@ describe('GPU-driven production projection', () => {
       production.inspect().batchCount,
     );
 
+    const missingMaterialFrameResources = {
+      ...frameResources,
+      materialBindGroups: [undefined] as unknown as typeof frameResources.materialBindGroups,
+    };
+    activeFrameResources = missingMaterialFrameResources;
+    const missingMaterialEncoder = device
+      .createCommandEncoder({ label: 'gpu-driven-production-missing-material' })
+      .unwrap();
+    const missingMaterialResult = compiled.execute({
+      viewBindGroup,
+      encoder: missingMaterialEncoder,
+      gpuDrivenStandardPbrFrameResources: missingMaterialFrameResources,
+    } as unknown as RenderPipelineFrame);
+    expect(missingMaterialResult.ok).toBe(false);
+    if (!missingMaterialResult.ok) {
+      expect(missingMaterialResult.error.code).toBe('pass-encode-failed');
+      const detail = missingMaterialResult.error.detail;
+      expect(detail).toBeDefined();
+      expect(detail !== undefined && 'cause' in detail).toBe(true);
+      if (detail === undefined || !('cause' in detail)) return;
+      expect(detail.cause).toBeInstanceOf(RhiError);
+      expect((detail.cause as RhiError).code).toBe('rhi-not-available');
+    }
+
     // The facet projection is the same admission set consumed by the GPU
     // candidate upload. A suppressed entity must disappear from the indirect
     // plan without making the remaining entity fall back to CPU validation.

package/src/__tests__/gpu-driven-shadow-views.dawn.test.ts

@@ -68,7 +68,7 @@ function topology(): RenderPipelineTopology {
       storageFormat: 'rgba8unorm',
       viewFormat: 'rgba8unorm',
     },
-    camera: { tonemap: 'aces-filmic', antialias: 'fxaa', bloom: 'off' },
+    camera: { tonemap: 'aces-filmic', antialias: 'fxaa', bloom: 'off', bloomIntensity: 1 },
     shadow: {
       directional: { mapSize: 32, cascadeCount: 2 },
       spotMapSize: 32,

package/src/__tests__/gpu-driven-shadow-views.integration.test.ts

@@ -24,7 +24,7 @@ function topology(): RenderPipelineTopology {
       storageFormat: 'rgba8unorm',
       viewFormat: 'rgba8unorm',
     },
-    camera: { tonemap: 'aces-filmic', antialias: 'fxaa', bloom: 'off' },
+    camera: { tonemap: 'aces-filmic', antialias: 'fxaa', bloom: 'off', bloomIntensity: 1 },
     shadow: {
       directional: { mapSize: 32, cascadeCount: 2 },
       spotMapSize: 32,

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

@@ -247,6 +247,7 @@ export async function runGpuDrivenViewGpuEvidence(): Promise<GpuDrivenViewGpuEvi
     })
     .unwrap();
   const graph = new RenderGraphBuilder<{ readonly encoder: RhiCommandEncoder }>();
+  view.setTelemetrySubmit({ frameId: 1, deviceGeneration: 0 });
   view.addPasses(graph).unwrap();
   const compiled = graph.compile({ device, surfaceSize: { width: 1, height: 1 } }).unwrap();
   const encoder = device.createCommandEncoder({ label: 'gpu-driven-evidence' }).unwrap();
@@ -279,6 +280,9 @@ export async function runGpuDrivenViewGpuEvidence(): Promise<GpuDrivenViewGpuEvi
   if (lodSelection === undefined || lodSelection.batches.length !== lodSelection.batchCount) {
     throw new Error('GPU-driven LOD selection readback unavailable or incomplete');
   }
+  if (lodSelection.submit?.frameId !== 1 || lodSelection.submit.deviceGeneration !== 0) {
+    throw new Error('GPU-driven LOD telemetry lost the copy submit identity');
+  }
   await device.queue.onSubmittedWorkDone();
 
   // After unmap, a later cached-graph submission must restore telemetry
@@ -292,6 +296,7 @@ export async function runGpuDrivenViewGpuEvidence(): Promise<GpuDrivenViewGpuEvi
       frustum.fromViewProjection(frustum.create(), recoveryProjection),
     )
     .unwrap();
+  view.setTelemetrySubmit({ frameId: 2, deviceGeneration: 0 });
   const recoveryEncoder = device
     .createCommandEncoder({ label: 'gpu-driven-evidence-recovery' })
     .unwrap();
@@ -306,6 +311,12 @@ export async function runGpuDrivenViewGpuEvidence(): Promise<GpuDrivenViewGpuEvi
   ) {
     throw new Error('GPU-driven LOD telemetry did not recover after a skipped copy');
   }
+  if (
+    recoveredLodSelection.submit?.frameId !== 2 ||
+    recoveredLodSelection.submit.deviceGeneration !== 0
+  ) {
+    throw new Error('GPU-driven LOD telemetry reused a stale submit identity');
+  }
   const validationError = await rawDevice.popErrorScope();
   if (validationError !== null) {
     throw new Error(`GPU-driven telemetry overlap validation failed: ${validationError.message}`);

package/src/__tests__/gpu-resource-store-stride.unit.test.ts

@@ -107,6 +107,13 @@ describe('GpuResidencyCache mesh stride', () => {
     };
     const world = new World();
     const handle = world.allocSharedRef('MeshAsset', root);
+    // The root can be pulled before the lower pack finishes loading. A later
+    // call with the complete chain must upgrade the same cache key.
+    const rootOnly = store.ensureResident(handle, root);
+    expect(rootOnly.ok).toBe(true);
+    if (!rootOnly.ok) return;
+    expect(rootOnly.value.lodRanges).toBeUndefined();
+
     const resident = store.ensureResident(handle, root, 0, [lower]);
     expect(resident.ok).toBe(true);
     if (!resident.ok) return;
@@ -120,6 +127,11 @@ describe('GpuResidencyCache mesh stride', () => {
     expect(packedIndices).toBeDefined();
     if (packedIndices === undefined) return;
     expect(new Uint16Array(packedIndices.buffer)).toEqual(new Uint16Array([0, 1, 2, 0, 2, 1]));
+
+    // A stable chain remains an O(1) hit and does not replace the entry again.
+    const stable = store.ensureResident(handle, root, 0, [lower]);
+    expect(stable.ok).toBe(true);
+    if (stable.ok) expect(stable.value).toBe(resident.value);
   });
 
   it('refuses a payload whose bytes do not match the projected stride', async () => {

package/src/__tests__/gpu-scene.unit.test.ts

@@ -126,6 +126,34 @@ function instanceSnapshot(entityKey: number, translationX: number): RenderableSn
   };
 }
 
+function multiInstanceSnapshot(
+  entityKey: number,
+  translations: readonly number[],
+  generations: readonly number[],
+): RenderableSnapshot {
+  const base = snapshot(entityKey);
+  const transforms = new Float32Array(translations.length * 16);
+  for (let ordinal = 0; ordinal < translations.length; ordinal += 1) {
+    const offset = ordinal * 16;
+    transforms[offset] = 1;
+    transforms[offset + 5] = 1;
+    transforms[offset + 10] = 1;
+    transforms[offset + 12] = translations[ordinal] ?? 0;
+    transforms[offset + 15] = 1;
+  }
+  return {
+    ...base,
+    instances: {
+      transforms,
+      generations: new Uint32Array(generations),
+      instanceCount: translations.length,
+      cacheKey: entityKey,
+      archVersion: 1,
+      revision: 1,
+    },
+  };
+}
+
 function persistentFrame(
   renderables: readonly RenderableSnapshot[],
   cameras: ExtractedFrame['cameras'] = [],
@@ -399,6 +427,69 @@ describe('GpuScene', () => {
     });
   });
 
+  it('maps GPU previous instance transforms by stable generation after reorder', () => {
+    const queue = new RecordingQueue();
+    const created = GpuScene.create(createDevice(queue), 4).unwrap();
+    if (created.status !== 'available') return;
+    const projection = new RenderScene();
+    projection.setTemporalTracking(true);
+    const initial = multiInstanceSnapshot(0, [2, 8], [101, 202]);
+    created.scene.sync(projection.apply([updateSnapshot(initial)])).unwrap();
+    projection.commitSubmission(projection.captureSubmission([{ worldId: 0, entityKey: 0 }]));
+
+    const reordered = multiInstanceSnapshot(0, [9, 3], [202, 101]);
+    const delta = projection.apply([updateInstances(reordered)]);
+    const slot = projection.slotsSnapshot()[0];
+    expect(slot).toBeDefined();
+    if (slot === undefined) return;
+    expect(projection.temporalSnapshotBySlot(slot.slot)?.motionValid).toBe(true);
+
+    queue.writes.length = 0;
+    created.scene
+      .sync(delta, (current) => projection.temporalSnapshotBySlot(current.slot))
+      .unwrap();
+    const transformWrite = queue.writes.find(
+      ({ bytes }) => bytes.byteLength === 2 * GPU_SCENE_LAYOUTS.transform.stride,
+    );
+    expect(transformWrite).toBeDefined();
+    if (transformWrite === undefined) return;
+    const previousTranslation =
+      gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.transform, 'previousWorld') + 12 * 4;
+    const transforms = new DataView(transformWrite.bytes.buffer);
+    expect(transforms.getFloat32(previousTranslation, true)).toBe(8);
+    expect(
+      transforms.getFloat32(GPU_SCENE_LAYOUTS.transform.stride + previousTranslation, true),
+    ).toBe(2);
+
+    created.scene.commitTemporalFrame().unwrap();
+    projection.commitSubmission(projection.captureSubmission([{ worldId: 0, entityKey: 0 }]));
+    const retired = multiInstanceSnapshot(0, [11], [202]);
+    const retiredDelta = projection.apply([updateInstances(retired)]);
+    expect(projection.temporalSnapshotBySlot(slot.slot)?.motionValid).toBe(true);
+    queue.writes.length = 0;
+    created.scene
+      .sync(retiredDelta, (current) => projection.temporalSnapshotBySlot(current.slot))
+      .unwrap();
+    const compactedRows = queue.writes
+      .filter(({ bytes }) => bytes.byteLength % GPU_SCENE_LAYOUTS.transform.stride === 0)
+      .flatMap(({ bytes }) =>
+        Array.from({ length: bytes.byteLength / GPU_SCENE_LAYOUTS.transform.stride }, (_, row) => {
+          const view = new DataView(bytes.buffer);
+          return {
+            current: view.getFloat32(
+              row * GPU_SCENE_LAYOUTS.transform.stride + currentWorldOffset() + 12 * 4,
+              true,
+            ),
+            previous: view.getFloat32(
+              row * GPU_SCENE_LAYOUTS.transform.stride + previousTranslation,
+              true,
+            ),
+          };
+        }),
+      );
+    expect(compactedRows).toContainEqual({ current: 11, previous: 9 });
+  });
+
   it('advances GPU previous transforms after a successful temporal commit', () => {
     const queue = new RecordingQueue();
     const created = GpuScene.create(createDevice(queue), 4).unwrap();

package/src/__tests__/instances-store.unit.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 import { InstanceCollectionStore, instanceUploadRangesForResident } from '../instances';
 import { instanceCollectionCacheKey } from '../record/frame-snapshot';
+import { packInstanceStorageBuffer } from '../record/mesh-ssbo';
 
 function identityTransforms(count: number): Float32Array {
   const transforms = new Float32Array(count * 16);
@@ -14,6 +15,14 @@ function identityTransforms(count: number): Float32Array {
   return transforms;
 }
 
+function translatedTransforms(...translations: readonly number[]): Float32Array {
+  const transforms = identityTransforms(translations.length);
+  for (const [index, translation] of translations.entries()) {
+    transforms[index * 16 + 12] = translation;
+  }
+  return transforms;
+}
+
 describe('InstanceCollectionStore', () => {
   it('keeps large payloads outside ECS-sized storage and preserves one identity', () => {
     const store = new InstanceCollectionStore();
@@ -40,6 +49,72 @@ describe('InstanceCollectionStore', () => {
     expect(after.transforms[3 * 16 + 12]).toBe(4);
   });
 
+  it('keeps identity generations stable across pose updates and seeds topology changes', () => {
+    const store = new InstanceCollectionStore();
+    const created = store.create({ transforms: translatedTransforms(1, 2) }).unwrap();
+    const before = store.snapshot(created.collectionId).unwrap();
+
+    store
+      .update(created.collectionId, {
+        start: 1,
+        transforms: translatedTransforms(9),
+      })
+      .unwrap();
+    const moved = store.snapshot(created.collectionId).unwrap();
+    expect([...moved.generations]).toEqual([...before.generations]);
+    const movedPayload = packInstanceStorageBuffer(
+      moved.transforms,
+      before.transforms,
+      moved.generations,
+      before.generations,
+    );
+    expect(movedPayload[16 + 12]).toBe(1);
+    expect(movedPayload[32 + 12]).toBe(9);
+    expect(movedPayload[32 + 16 + 12]).toBe(2);
+
+    store.replace(created.collectionId, translatedTransforms(20)).unwrap();
+    const compacted = store.snapshot(created.collectionId).unwrap();
+    expect(compacted.generations[0]).toBeGreaterThan(moved.generations[0] ?? 0);
+    const compactedPayload = packInstanceStorageBuffer(
+      compacted.transforms,
+      moved.transforms,
+      compacted.generations,
+      moved.generations,
+    );
+    // The surviving ordinal was replaced/compacted, so its previous slot is
+    // seeded from the current pose instead of inheriting instance 0 or 1.
+    expect(compactedPayload[16 + 12]).toBe(20);
+  });
+
+  it('maps real previous transforms through an explicit compaction reorder', () => {
+    const store = new InstanceCollectionStore();
+    const created = store.create({ transforms: translatedTransforms(1, 2) }).unwrap();
+    const before = store.snapshot(created.collectionId).unwrap();
+    const reordered = store
+      .replace(
+        created.collectionId,
+        translatedTransforms(20, 10),
+        new Uint32Array([before.generations[1] ?? 0, before.generations[0] ?? 0]),
+      )
+      .unwrap();
+    const after = store.snapshot(created.collectionId).unwrap();
+
+    expect(after.generations).toEqual(
+      new Uint32Array([before.generations[1] ?? 0, before.generations[0] ?? 0]),
+    );
+    const payload = packInstanceStorageBuffer(
+      after.transforms,
+      before.transforms,
+      after.generations,
+      before.generations,
+    );
+    expect(payload[12]).toBe(20);
+    expect(payload[16 + 12]).toBe(2);
+    expect(payload[32 + 12]).toBe(10);
+    expect(payload[32 + 16 + 12]).toBe(1);
+    expect(reordered.count).toBe(2);
+  });
+
   it('keeps the full union when partial updates overlap out of order', () => {
     const store = new InstanceCollectionStore();
     const created = store.create({ transforms: identityTransforms(16) }).unwrap();
@@ -51,6 +126,21 @@ describe('InstanceCollectionStore', () => {
     ]);
   });
 
+  it('keeps renderer dirty ranges intact when inspection peeks between updates', () => {
+    const store = new InstanceCollectionStore();
+    const created = store.create({ transforms: identityTransforms(2) }).unwrap();
+    store.snapshot(created.collectionId).unwrap();
+
+    store.update(created.collectionId, { start: 0, transforms: identityTransforms(1) }).unwrap();
+    const inspected = store.peek(created.collectionId).unwrap();
+    expect(inspected.dirtyRanges).toEqual([{ start: 0, end: 1 }]);
+    store.update(created.collectionId, { start: 1, transforms: identityTransforms(1) }).unwrap();
+
+    expect(store.snapshot(created.collectionId).unwrap().dirtyRanges).toEqual([
+      { start: 0, end: 2 },
+    ]);
+  });
+
   it('keeps collection identity in the renderer cache key', () => {
     const first = instanceCollectionCacheKey(0, { cacheKey: 9, collectionId: 1 });
     const second = instanceCollectionCacheKey(0, { cacheKey: 9, collectionId: 2 });

package/src/__tests__/mesh-submission-lifetime.unit.test.ts

@@ -59,3 +59,34 @@ it('fences ordinary mesh submissions independently of candidates, including reve
   expect(replacement.vertexBuffer.isDestroyed).toBe(true);
   expect(scope.resourceDelta()).toBe(0);
 });
+
+it('separates recycled shared mesh generations while old GPU work is still retained', async () => {
+  const device = (await (await rhi.requestAdapter()).unwrap().requestDevice()).unwrap();
+  const store = new GpuResidencyCache();
+  store.configureGpuDevice(
+    device,
+    undefined,
+    () => {
+      throw new Error('no cubemap');
+    },
+    device.caps,
+  );
+  const world = new World();
+  const first = createBoxGeometry(1, 1, 1).unwrap();
+  const oldHandle = world.allocSharedRef('MeshAsset', first);
+  const oldMesh = store.ensureResident(oldHandle, first, world).unwrap();
+  const lease = store.retainMeshResidency(oldHandle, world);
+  if (lease === undefined) throw new Error('mesh residency missing');
+  world.sharedRefs.release(oldHandle).unwrap();
+  const next = createBoxGeometry(8, 8, 8).unwrap();
+  const newHandle = world.allocSharedRef('MeshAsset', next);
+  expect(Number(newHandle) & 0xffffff).toBe(Number(oldHandle) & 0xffffff);
+  expect(newHandle).not.toBe(oldHandle);
+  const newMesh = store.ensureResident(newHandle, next, world).unwrap();
+  expect(newMesh).not.toBe(oldMesh);
+  store.invalidateMesh(oldHandle, world);
+  lease.release(true);
+  expect(store.getMeshGpuHandles(newHandle, world)).toBe(newMesh);
+  expect(newMesh.vertexBuffer.isDestroyed).toBe(false);
+  store.destroyAll();
+});