@forgeax/engine-render 0.1.4 → 0.1.7

package/src/__tests__/gpu-driven-view.unit.test.ts

@@ -1,11 +1,9 @@
 import { frustum, mat4 } from '@forgeax/engine-math';
 import { describe, expect, it } from 'vitest';
 import { BatchTopology } from '../gpu-driven/batch-topology';
-import { gpuDrivenRasterEligibility } from '../gpu-driven/production-raster';
-import { classifyGpuDrivenView } from '../gpu-driven/view-reference';
-import { buildCascadeLocalCacheTokens, evaluateDirectionalShadowCache } from '../record/frame';
-import { RenderSceneProjection } from '../render-scene-projection';
 import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
+import { RenderScene } from '../scene/render-scene';
+import { classifyGpuDrivenView } from './gpu-driven-view-reference';
 
 const material = {
   baseColor: new Float32Array([1, 1, 1]),
@@ -27,9 +25,6 @@ function snapshot(entityKey: number, x: number, resourceClass = 'plain'): Render
     entityKey,
     gpuDrivenDraws: [
       {
-        submeshIndex: 0,
-        passIndex: 0,
-        queue: 2000,
         kind: 'indexed',
         first: 3,
         count: 36,
@@ -45,7 +40,7 @@ function snapshot(entityKey: number, x: number, resourceClass = 'plain'): Render
 
 describe('GPU-driven batch topology and CPU oracle', () => {
   it('patches topology only when compatibility membership changes', () => {
-    const projection = new RenderSceneProjection();
+    const projection = new RenderScene();
     projection.apply([
       { kind: 'create', snapshot: snapshot(1, 0) },
       { kind: 'create', snapshot: snapshot(2, 0.5) },
@@ -74,7 +69,7 @@ describe('GPU-driven batch topology and CPU oracle', () => {
   });
 
   it('compacts visible primitive indices and writes portable indexed indirect args', () => {
-    const projection = new RenderSceneProjection();
+    const projection = new RenderScene();
     projection.apply([
       { kind: 'create', snapshot: snapshot(1, 0) },
       { kind: 'create', snapshot: snapshot(2, 10) },
@@ -101,7 +96,7 @@ describe('GPU-driven batch topology and CPU oracle', () => {
   });
 
   it('keeps multi-submesh draw items independent and writes non-indexed indirect args', () => {
-    const projection = new RenderSceneProjection();
+    const projection = new RenderScene();
     const source = snapshot(1, 0);
     const first = source.gpuDrivenDraws?.[0];
     expect(first).toBeDefined();
@@ -140,7 +135,7 @@ describe('GPU-driven batch topology and CPU oracle', () => {
     const identity = mat4.identity(mat4.create());
     const outside = mat4.identity(mat4.create());
     outside[12] = 10;
-    const projection = new RenderSceneProjection();
+    const projection = new RenderScene();
     projection.apply([
       {
         kind: 'create',
@@ -169,7 +164,7 @@ describe('GPU-driven batch topology and CPU oracle', () => {
   });
 
   it('reports overflow instead of silently accepting a truncated batch', () => {
-    const projection = new RenderSceneProjection();
+    const projection = new RenderScene();
     projection.apply([
       { kind: 'create', snapshot: snapshot(1, 0) },
       { kind: 'create', snapshot: snapshot(2, 0.5) },
@@ -190,266 +185,15 @@ describe('GPU-driven batch topology and CPU oracle', () => {
     expect(result.visibleCount).toBe(1);
   });
 
-  it('keeps pass-agnostic shadow topology while forward capability stays explicit', () => {
-    const projection = new RenderSceneProjection();
+  it('keeps the ineligible inspection bounded to current projection membership', () => {
+    const projection = new RenderScene();
     const { localAabb: _localAabb, ...withoutBounds } = snapshot(1, 0);
     const topology = new BatchTopology();
     topology.rebuild(projection.apply([{ kind: 'create', snapshot: withoutBounds }]).createdSlots);
-    expect(topology.inspect()).toMatchObject({ candidateCount: 1, ineligible: 0 });
-    const batch = topology.plan().batches[0];
-    expect(batch).toBeDefined();
-    if (batch === undefined) return;
-    expect(gpuDrivenRasterEligibility(withoutBounds, batch)).toEqual({
-      eligible: false,
-      reason: 'missing-local-bounds-capability-lane',
-    });
+    expect(topology.inspect().ineligible).toBe(1);
 
     const removed = projection.apply([{ kind: 'remove', worldId: 0, entityKey: 1 }]);
     topology.apply(removed);
-    expect(topology.inspect()).toMatchObject({ candidateCount: 0, ineligible: 0 });
-  });
-
-  it('invalidates only the cascade containing the changed scene fact', () => {
-    const cascade = (revision: number, offset: number) => ({
-      revision,
-      lightViewProj: new Float32Array([offset]),
-      clipLightBounds: new Float32Array([offset, offset + 1]),
-      casterBroadphaseWorldAabb: new Float32Array([offset, 0, 0, offset + 1, 1, 1]),
-      rasterViewport: { x: offset * 16, y: 0, w: 16, h: 16 },
-    });
-    const revisions = (transform: number) => ({
-      transform,
-      geometry: 1,
-      material: 1,
-      eligibility: 1,
-      space: 1,
-      batch: 1,
-      resource: 1,
-    });
-    const scene = (firstTransform: number, planRevision: number, useProjectionOwner = false) => {
-      const slots = [
-        { slot: 0, generation: 1, fact: { revisions: revisions(firstTransform) } },
-        { slot: 1, generation: 1, fact: { revisions: revisions(1) } },
-      ];
-      return {
-        // The projection-owner case deliberately leaves `slots` empty. If the
-        // token builder regresses to rebuilding the compatibility map, the
-        // resulting tokens differ from the owner-backed result.
-        slots: useProjectionOwner ? [] : slots,
-        ...(useProjectionOwner
-          ? { projection: { slotByIndex: (slot: number) => slots[slot] } }
-          : {}),
-        plan: {
-          revision: planRevision,
-          batches: [
-            {
-              batchId: 10,
-              generation: 1,
-              key: {
-                resourceRevision: 1,
-                materialRevision: 1,
-                pipelineClass: 'shadow',
-                materialClass: 'opaque',
-                materialResourceClass: 'plain',
-              },
-              candidates: [{ primitiveIndex: 0 }],
-            },
-            {
-              batchId: 11,
-              generation: 1,
-              key: {
-                resourceRevision: 1,
-                materialRevision: 1,
-                pipelineClass: 'shadow',
-                materialClass: 'opaque',
-                materialResourceClass: 'plain',
-              },
-              candidates: [{ primitiveIndex: 1 }],
-            },
-          ],
-        },
-      };
-    };
-    const visibility = (spatialIndexRevision: number) => ({
-      views: [
-        { kind: 'cascade', cascadeIndex: 0, stableIds: [0], spatialIndexRevision },
-        { kind: 'cascade', cascadeIndex: 1, stableIds: [1], spatialIndexRevision },
-      ],
-    });
-    const lights = {
-      cascadeCount: 2,
-      directionalCsm: { cascades: [cascade(1, 0), cascade(2, 1)] },
-    };
-    const baseline = buildCascadeLocalCacheTokens({
-      lights: lights as never,
-      visibility: visibility(7) as never,
-      scene: scene(1, 20) as never,
-      validated: [],
-    }).tokens;
-    const changed = buildCascadeLocalCacheTokens({
-      lights: lights as never,
-      visibility: visibility(8) as never,
-      scene: scene(2, 21) as never,
-      validated: [],
-    }).tokens;
-    const ownerBacked = buildCascadeLocalCacheTokens({
-      lights: lights as never,
-      visibility: visibility(7) as never,
-      scene: scene(1, 20, true) as never,
-      validated: [],
-    }).tokens;
-
-    expect(changed[0]).not.toBe(baseline[0]);
-    expect(changed[1]).toBe(baseline[1]);
-    expect(ownerBacked).toEqual(baseline);
-  });
-
-  it('does not reuse a compatibility token after an in-place slots mutation', () => {
-    const cascade = {
-      revision: 1,
-      lightViewProj: new Float32Array([0]),
-      clipLightBounds: new Float32Array([0, 1]),
-      casterBroadphaseWorldAabb: new Float32Array([0, 0, 0, 1, 1, 1]),
-      rasterViewport: { x: 0, y: 0, w: 16, h: 16 },
-    };
-    const slots = [
-      {
-        slot: 0,
-        generation: 1,
-        fact: {
-          revisions: {
-            transform: 1,
-            geometry: 1,
-            material: 1,
-            eligibility: 1,
-            space: 1,
-            batch: 1,
-            resource: 1,
-          },
-        },
-      },
-    ];
-    const input = {
-      lights: { cascadeCount: 1, directionalCsm: { cascades: [cascade] } },
-      visibility: { views: [{ kind: 'cascade', cascadeIndex: 0, stableIds: [0] }] },
-      scene: {
-        slots,
-        plan: {
-          revision: 1,
-          batches: [
-            {
-              batchId: 1,
-              generation: 1,
-              key: {
-                resourceRevision: 1,
-                materialRevision: 1,
-                pipelineClass: 'shadow',
-                materialClass: 'opaque',
-                materialResourceClass: 'plain',
-              },
-              candidates: [{ primitiveIndex: 0 }],
-            },
-          ],
-        },
-      },
-      validated: [],
-    } as never;
-    const before = buildCascadeLocalCacheTokens(input).tokens;
-    const firstSlot = slots[0];
-    expect(firstSlot).toBeDefined();
-    if (firstSlot === undefined) return;
-    firstSlot.fact.revisions.transform = 2;
-    const after = buildCascadeLocalCacheTokens(input).tokens;
-    expect(after[0]).not.toBe(before[0]);
-  });
-
-  it('normalizes visible batch token input independent of submission order', () => {
-    const cascade = {
-      revision: 1,
-      lightViewProj: new Float32Array([0]),
-      clipLightBounds: new Float32Array([0, 1]),
-      casterBroadphaseWorldAabb: new Float32Array([0, 0, 0, 1, 1, 1]),
-      rasterViewport: { x: 0, y: 0, w: 16, h: 16 },
-    };
-    const slots = [0, 1].map((slot) => ({
-      slot,
-      generation: 1,
-      fact: {
-        revisions: {
-          transform: 1,
-          geometry: 1,
-          material: 1,
-          eligibility: 1,
-          space: 1,
-          batch: 1,
-          resource: 1,
-        },
-      },
-    }));
-    const planFor = (batchOrder: readonly number[]) => ({
-      revision: 1,
-      batches: batchOrder.map((batchId) => ({
-        batchId,
-        generation: 1,
-        key: {
-          resourceRevision: 1,
-          materialRevision: 1,
-          pipelineClass: 'shadow',
-          materialClass: 'opaque',
-          materialResourceClass: 'plain',
-        },
-        candidates: [{ primitiveIndex: batchId - 10 }],
-      })),
-    });
-    const makeInput = (batchOrder: readonly number[]) =>
-      ({
-        lights: { cascadeCount: 1, directionalCsm: { cascades: [cascade] } },
-        visibility: { views: [{ kind: 'cascade', cascadeIndex: 0, stableIds: [0, 1] }] },
-        scene: { slots, plan: planFor(batchOrder) },
-        validated: [],
-      }) as never;
-    const ascending = buildCascadeLocalCacheTokens(makeInput([10, 11])).tokens;
-    const descending = buildCascadeLocalCacheTokens(makeInput([11, 10])).tokens;
-    expect(descending).toEqual(ascending);
-  });
-
-  it('requires a complete CSM hit before allowing atlas reuse', () => {
-    const common = {
-      shadowMapSize: 1024,
-      cascadeCount: 2,
-      pipelineHandle: 7,
-      graphTopologyKey: 'shadow-graph-v1',
-      assetCatalogEpoch: 3,
-      meshResidencyEpoch: 4,
-      productionSceneToken: true,
-      worldStateMatches: true,
-    };
-    const cached = {
-      worlds: [],
-      worldStateTokens: [],
-      ...common,
-      cascadeTokens: ['csm-0-a', 'csm-1-b'],
-    } as never;
-    const hit = evaluateDirectionalShadowCache({
-      cached,
-      cascadeTokens: ['csm-0-a', 'csm-1-b'],
-      ...common,
-    });
-    expect(hit).toEqual({ reuse: true, hitMask: 3, missReason: undefined });
-
-    const partial = evaluateDirectionalShadowCache({
-      cached,
-      cascadeTokens: ['csm-0-a', 'csm-1-changed'],
-      ...common,
-    });
-    expect(partial).toEqual({ reuse: false, hitMask: 1, missReason: 'cascade-token' });
-
-    const forced = evaluateDirectionalShadowCache({
-      cached,
-      cascadeTokens: ['csm-0-a', 'csm-1-b'],
-      ...common,
-      graphTopologyKey: 'shadow-graph-v2',
-    });
-    expect(forced).toEqual({ reuse: false, hitMask: 0, missReason: 'graph-topology' });
+    expect(topology.inspect().ineligible).toBe(0);
   });
 });

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

@@ -3,13 +3,13 @@ import { deriveVertexLayoutProjection } from '@forgeax/engine-geometry';
 import { rhi } from '@forgeax/engine-rhi-null';
 import type { MeshAsset } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
-import { GpuResourceStore } from '../gpu-resource-store';
+import { GpuResidencyCache } from '../device/gpu-residency';
 
-describe('GpuResourceStore mesh stride', () => {
+describe('GpuResidencyCache mesh stride', () => {
   it('keeps the canonical 18F plus UV1 stride from the complete projection', async () => {
     const adapter = (await rhi.requestAdapter()).unwrap();
     const device = (await adapter.requestDevice()).unwrap();
-    const store = new GpuResourceStore();
+    const store = new GpuResidencyCache();
     store.configureGpuDevice(
       device,
       undefined,

package/src/__tests__/gpu-scene-render-graph-gpu.ts

@@ -4,8 +4,8 @@ import { createShaderModule, rhi } from '@forgeax/engine-rhi-webgpu';
 import { GpuScene } from '../gpu-scene';
 import { GPU_SCENE_LAYOUTS, GPU_SCENE_WGSL } from '../gpu-scene-schema';
 import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_MAP_READ } from '../gpu-usage';
-import { RenderSceneProjection } from '../render-scene-projection';
 import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
+import { RenderScene } from '../scene/render-scene';
 
 const BUFFER_USAGE_STORAGE = 0x0080;
 const COMPUTE_VISIBILITY = 0x4;
@@ -115,10 +115,9 @@ export async function runGpuSceneGraph(): Promise<GpuSceneGraphEvidence> {
   const availability = GpuScene.create(device, 4).unwrap();
   if (availability.status !== 'available') throw new Error(availability.reason);
   const scene = availability.scene;
-  const projection = new RenderSceneProjection();
+  const projection = new RenderScene();
   scene
     .sync(
-      projection,
       projection.apply([
         { kind: 'create', snapshot: snapshot(10, -3) },
         { kind: 'create', snapshot: snapshot(11, -0.5) },

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

@@ -3,8 +3,8 @@ import { describe, expect, it } from 'vitest';
 import { GpuScene } from '../gpu-scene';
 import { GPU_SCENE_LAYOUTS, gpuSceneFieldOffset } from '../gpu-scene-schema';
 import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_MAP_READ } from '../gpu-usage';
-import { RenderSceneProjection } from '../render-scene-projection';
 import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
+import { RenderScene } from '../scene/render-scene';
 
 const material = {
   baseColor: new Float32Array([0.25, 0.5, 0.75]),
@@ -28,9 +28,6 @@ function snapshot(entityKey: number, translationX: number): RenderableSnapshot {
     localAabb: new Float32Array([-1, -2, -3, 1, 2, 3]),
     gpuDrivenDraws: [
       {
-        submeshIndex: 0,
-        passIndex: 0,
-        queue: 2000,
         kind: 'indexed',
         first: 3,
         count: 36,
@@ -56,7 +53,7 @@ describe('GpuScene Dawn residency', () => {
     const availability = GpuScene.create(device, 2).unwrap();
     expect(availability.status).toBe('available');
     if (availability.status !== 'available') return;
-    const projection = new RenderSceneProjection();
+    const projection = new RenderScene();
     const first = snapshot(7, 3);
     const firstDraw = first.gpuDrivenDraws?.[0];
     const secondMaterial = {
@@ -67,7 +64,6 @@ describe('GpuScene Dawn residency', () => {
     if (firstDraw === undefined) throw new Error('GPU draw fixture unavailable');
     availability.scene
       .sync(
-        projection,
         projection.apply([
           {
             kind: 'create',

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

@@ -3,8 +3,8 @@ import { RhiNullCommandEncoder, RhiNullDevice, RhiNullQueue } from '@forgeax/eng
 import { describe, expect, it } from 'vitest';
 import { GpuScene } from '../gpu-scene';
 import { GPU_SCENE_LAYOUTS, gpuSceneFieldOffset } from '../gpu-scene-schema';
-import { RenderSceneProjection } from '../render-scene-projection';
 import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
+import { RenderScene } from '../scene/render-scene';
 
 interface WriteRecord {
   readonly offset: number;
@@ -71,32 +71,24 @@ describe('GpuScene', () => {
     const created = GpuScene.create(createDevice(queue), 4).unwrap();
     expect(created.status).toBe('available');
     if (created.status !== 'available') return;
-    const projection = new RenderSceneProjection();
+    const projection = new RenderScene();
 
     const initial = projection.apply([
       { kind: 'create', snapshot: snapshot(0) },
       { kind: 'create', snapshot: snapshot(1) },
       { kind: 'create', snapshot: snapshot(2) },
     ]);
-    expect(created.scene.sync(projection, initial).unwrap()).toMatchObject({
-      ranges: 5,
-      bytes: 1344,
-    });
+    expect(created.scene.sync(initial).unwrap()).toMatchObject({ ranges: 5, bytes: 1344 });
     const writesAfterInitial = queue.writes.length;
 
-    created.scene.sync(projection, projection.apply([])).unwrap();
+    created.scene.sync(projection.apply([])).unwrap();
     expect(queue.writes).toHaveLength(writesAfterInitial);
 
     const dirty = projection.apply([
       { kind: 'update-transform', worldId: 0, entityKey: 0, world: snapshot(0, 4).transform.world },
       { kind: 'update-transform', worldId: 0, entityKey: 2, world: snapshot(2, 8).transform.world },
     ]);
-    // Transform-only Scene Fact deltas touch only the transform table; the
-    // primitive/instance/draw/material rows stay resident.
-    expect(created.scene.sync(projection, dirty).unwrap()).toMatchObject({
-      ranges: 2,
-      bytes: 256,
-    });
+    expect(created.scene.sync(dirty).unwrap()).toMatchObject({ ranges: 10 });
     expect(queue.writes.length).toBeGreaterThan(writesAfterInitial);
     expect(created.scene.inspect()).toMatchObject({ noChangeFrames: 1 });
   });
@@ -105,10 +97,9 @@ describe('GpuScene', () => {
     const queue = new RecordingQueue();
     const created = GpuScene.create(createDevice(queue), 2).unwrap();
     if (created.status !== 'available') return;
-    const projection = new RenderSceneProjection();
+    const projection = new RenderScene();
     created.scene
       .sync(
-        projection,
         projection.apply([
           { kind: 'create', snapshot: snapshot(0) },
           { kind: 'create', snapshot: snapshot(1) },
@@ -119,16 +110,14 @@ describe('GpuScene', () => {
     expect(created.scene.inspect()).toMatchObject({ capacity: 8, capacityGrows: 1 });
 
     const beforeRemove = queue.writes.length;
-    created.scene
-      .sync(projection, projection.apply([{ kind: 'remove', worldId: 0, entityKey: 1 }]))
-      .unwrap();
+    created.scene.sync(projection.apply([{ kind: 'remove', worldId: 0, entityKey: 1 }])).unwrap();
     expect(queue.writes.slice(beforeRemove)).toHaveLength(5);
     expect(queue.writes.at(-1)?.bytes.every((value) => value === 0)).toBe(true);
     expect(created.scene.inspect().clearedSlots).toBe(1);
 
     const rebuilt = GpuScene.create(createDevice(new RecordingQueue()), 1).unwrap();
     if (rebuilt.status !== 'available') return;
-    expect(rebuilt.scene.rebuild(projection).unwrap()).toMatchObject({ ranges: 5 });
+    expect(rebuilt.scene.rebuild(projection.slotsSnapshot()).unwrap()).toMatchObject({ ranges: 5 });
     expect(rebuilt.scene.inspect()).toMatchObject({ capacity: 4, fullRebuilds: 1 });
   });
 
@@ -136,14 +125,11 @@ describe('GpuScene', () => {
     const queue = new RecordingQueue();
     const created = GpuScene.create(createDevice(queue), 1).unwrap();
     if (created.status !== 'available') return;
-    const projection = new RenderSceneProjection();
-    created.scene
-      .sync(projection, projection.apply([{ kind: 'create', snapshot: snapshot(1, 2) }]))
-      .unwrap();
+    const projection = new RenderScene();
+    created.scene.sync(projection.apply([{ kind: 'create', snapshot: snapshot(1, 2) }])).unwrap();
 
     created.scene
       .sync(
-        projection,
         projection.apply([
           { kind: 'remove', worldId: 0, entityKey: 1 },
           { kind: 'create', snapshot: snapshot(1, 9) },

package/src/__tests__/ibl/face-uniforms.unit.test.ts

@@ -0,0 +1,46 @@
+import { RhiNullAdapter } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import {
+  createFaceUniformsBuffer,
+  createPrefilterUniformsBuffer,
+  writeAllFaceUniforms,
+  writeAllPrefilterUniforms,
+  writeFaceUniforms,
+  writePrefilterUniforms,
+} from '../../device/gpu-residency';
+
+async function createDevice() {
+  const adapterResult = await new RhiNullAdapter().requestDevice();
+  if (!adapterResult.ok) throw adapterResult.error;
+  return adapterResult.value;
+}
+
+describe('IBL face uniform RHI contract', () => {
+  it('allocates opaque buffers and writes all dynamic uniform slots', async () => {
+    const device = await createDevice();
+    const faceBuffer = createFaceUniformsBuffer(device);
+    const prefilterBuffer = createPrefilterUniformsBuffer(device);
+
+    expect(faceBuffer.ok).toBe(true);
+    expect(prefilterBuffer.ok).toBe(true);
+    if (!faceBuffer.ok || !prefilterBuffer.ok) return;
+
+    expect(writeAllFaceUniforms(device, faceBuffer.value).ok).toBe(true);
+    expect(writeAllPrefilterUniforms(device, prefilterBuffer.value).ok).toBe(true);
+  });
+
+  it('returns structured RHI errors for invalid uniform coordinates', async () => {
+    const device = await createDevice();
+    const bufferResult = createFaceUniformsBuffer(device);
+    expect(bufferResult.ok).toBe(true);
+    if (!bufferResult.ok) return;
+
+    const badFace = writeFaceUniforms(device, bufferResult.value, 6, new Float32Array(16));
+    const badMatrix = writeFaceUniforms(device, bufferResult.value, 0, new Float32Array(15));
+    const badSubPass = writePrefilterUniforms(device, bufferResult.value, 30, 0.5, 128);
+
+    expect(badFace).toMatchObject({ ok: false, error: { code: 'webgpu-runtime-error' } });
+    expect(badMatrix).toMatchObject({ ok: false, error: { code: 'webgpu-runtime-error' } });
+    expect(badSubPass).toMatchObject({ ok: false, error: { code: 'webgpu-runtime-error' } });
+  });
+});