@forgeax/engine-render 0.1.2

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

@@ -0,0 +1,455 @@
+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';
+
+const material = {
+  baseColor: new Float32Array([1, 1, 1]),
+  metallic: 0,
+  roughness: 1,
+} as MaterialSnapshot;
+
+function snapshot(entityKey: number, x: number, resourceClass = 'plain'): RenderableSnapshot {
+  const world = mat4.identity(mat4.create());
+  world[12] = x;
+  return {
+    assetHandle: 7,
+    transform: { world: new Float32Array(world) },
+    localAabb: new Float32Array([-0.25, -0.25, -0.25, 0.25, 0.25, 0.25]),
+    material,
+    materials: [material],
+    materialBindingSources: ['engine-default'],
+    worldId: 0,
+    entityKey,
+    gpuDrivenDraws: [
+      {
+        submeshIndex: 0,
+        passIndex: 0,
+        queue: 2000,
+        kind: 'indexed',
+        first: 3,
+        count: 36,
+        baseVertex: -2,
+        materialSlot: 0,
+        topology: 'triangle-list',
+        pipelineClass: 'opaque-pbr',
+        materialResourceClass: resourceClass,
+      },
+    ],
+  };
+}
+
+describe('GPU-driven batch topology and CPU oracle', () => {
+  it('patches topology only when compatibility membership changes', () => {
+    const projection = new RenderSceneProjection();
+    projection.apply([
+      { kind: 'create', snapshot: snapshot(1, 0) },
+      { kind: 'create', snapshot: snapshot(2, 0.5) },
+      { kind: 'create', snapshot: snapshot(3, 0, 'textured') },
+    ]);
+    const topology = new BatchTopology();
+    topology.rebuild(projection.slotsSnapshot());
+    expect(topology.inspect()).toMatchObject({ batchCount: 2, candidateCount: 3, rebuilds: 1 });
+    expect(topology.plan()).toBe(topology.plan());
+
+    const transformOnly = projection.apply([
+      {
+        kind: 'update-transform',
+        worldId: 0,
+        entityKey: 1,
+        world: snapshot(1, 0.25).transform.world,
+      },
+    ]);
+    expect(topology.apply(transformOnly)).toBe(false);
+    expect(topology.plan()).toBe(topology.plan());
+    expect(topology.inspect().patches).toBe(0);
+
+    const removed = projection.apply([{ kind: 'remove', worldId: 0, entityKey: 3 }]);
+    expect(topology.apply(removed)).toBe(true);
+    expect(topology.inspect()).toMatchObject({ batchCount: 1, candidateCount: 2, patches: 1 });
+  });
+
+  it('compacts visible primitive indices and writes portable indexed indirect args', () => {
+    const projection = new RenderSceneProjection();
+    projection.apply([
+      { kind: 'create', snapshot: snapshot(1, 0) },
+      { kind: 'create', snapshot: snapshot(2, 10) },
+    ]);
+    const topology = new BatchTopology();
+    topology.rebuild(projection.slotsSnapshot());
+    const planes = frustum.fromViewProjection(frustum.create(), mat4.identity(mat4.create()));
+    const result = classifyGpuDrivenView(topology.plan(), projection.slotsSnapshot(), planes);
+
+    expect(result).toMatchObject({
+      candidateCount: 2,
+      rejectedCount: 1,
+      visibleCount: 1,
+      overflowedBatches: [],
+    });
+    expect([...result.visibleInstanceIndices]).toEqual([0, 0]);
+    expect([...result.batchCounters]).toEqual([1]);
+    const args = new DataView(result.indirectArgs);
+    expect(args.getUint32(0, true)).toBe(36);
+    expect(args.getUint32(4, true)).toBe(1);
+    expect(args.getUint32(8, true)).toBe(3);
+    expect(args.getInt32(12, true)).toBe(-2);
+    expect(args.getUint32(16, true)).toBe(0);
+  });
+
+  it('keeps multi-submesh draw items independent and writes non-indexed indirect args', () => {
+    const projection = new RenderSceneProjection();
+    const source = snapshot(1, 0);
+    const first = source.gpuDrivenDraws?.[0];
+    expect(first).toBeDefined();
+    if (first === undefined) return;
+    projection.apply([
+      {
+        kind: 'create',
+        snapshot: {
+          ...source,
+          gpuDrivenDraws: [
+            { ...first, kind: 'non-indexed', first: 0, count: 3 },
+            { ...first, kind: 'non-indexed', first: 3, count: 6 },
+          ],
+        },
+      },
+    ]);
+    const topology = new BatchTopology();
+    topology.rebuild(projection.slotsSnapshot());
+    const plan = topology.plan();
+    expect(plan).toMatchObject({ candidateCount: 2, batches: [{}, {}] });
+    const result = classifyGpuDrivenView(
+      plan,
+      projection.slotsSnapshot(),
+      frustum.fromViewProjection(frustum.create(), mat4.identity(mat4.create())),
+    );
+    const firstArgs = new DataView(result.indirectArgs, plan.batches[0]?.indirectOffset ?? 0, 20);
+    const secondArgs = new DataView(result.indirectArgs, plan.batches[1]?.indirectOffset ?? 0, 20);
+    expect([firstArgs.getUint32(0, true), firstArgs.getUint32(8, true)]).toEqual([3, 0]);
+    expect([secondArgs.getUint32(0, true), secondArgs.getUint32(8, true)]).toEqual([6, 3]);
+    expect(firstArgs.getUint32(12, true)).toBe(0);
+    expect(secondArgs.getUint32(12, true)).toBe(0);
+  });
+
+  it('culls ordinary instance-local transforms and emits instance identities', () => {
+    const source = snapshot(1, 0);
+    const identity = mat4.identity(mat4.create());
+    const outside = mat4.identity(mat4.create());
+    outside[12] = 10;
+    const projection = new RenderSceneProjection();
+    projection.apply([
+      {
+        kind: 'create',
+        snapshot: {
+          ...source,
+          instances: {
+            transforms: new Float32Array([...identity, ...outside]),
+            instanceCount: 2,
+            cacheKey: 1,
+            archVersion: 1,
+          },
+        },
+      },
+    ]);
+    const topology = new BatchTopology();
+    topology.rebuild(projection.slotsSnapshot());
+    expect(topology.inspect()).toMatchObject({ candidateCount: 2, ineligible: 0 });
+    const result = classifyGpuDrivenView(
+      topology.plan(),
+      projection.slotsSnapshot(),
+      frustum.fromViewProjection(frustum.create(), mat4.identity(mat4.create())),
+    );
+    expect(result).toMatchObject({ candidateCount: 2, visibleCount: 1, rejectedCount: 1 });
+    expect([...result.visibleInstanceIndices]).toEqual([0, 0]);
+    expect(new DataView(result.indirectArgs).getUint32(4, true)).toBe(1);
+  });
+
+  it('reports overflow instead of silently accepting a truncated batch', () => {
+    const projection = new RenderSceneProjection();
+    projection.apply([
+      { kind: 'create', snapshot: snapshot(1, 0) },
+      { kind: 'create', snapshot: snapshot(2, 0.5) },
+    ]);
+    const topology = new BatchTopology();
+    topology.rebuild(projection.slotsSnapshot());
+    const plan = topology.plan();
+    const batch = plan.batches[0];
+    expect(batch).toBeDefined();
+    if (batch === undefined) return;
+    const result = classifyGpuDrivenView(
+      plan,
+      projection.slotsSnapshot(),
+      frustum.fromViewProjection(frustum.create(), mat4.identity(mat4.create())),
+      new Map([[batch.batchId, 1]]),
+    );
+    expect(result.overflowedBatches).toEqual([batch.batchId]);
+    expect(result.visibleCount).toBe(1);
+  });
+
+  it('keeps pass-agnostic shadow topology while forward capability stays explicit', () => {
+    const projection = new RenderSceneProjection();
+    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',
+    });
+
+    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' });
+  });
+});

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

@@ -0,0 +1,59 @@
+import { World } from '@forgeax/engine-ecs';
+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';
+
+describe('GpuResourceStore 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();
+    store.configureGpuDevice(
+      device,
+      undefined,
+      () => {
+        throw new Error('cubemap registration is not part of this test');
+      },
+      device.caps,
+    );
+
+    const mesh: MeshAsset = {
+      kind: 'mesh',
+      // The producer owns a canonical 20-float interleaved buffer:
+      // 18F skinned data plus one additional UV set. Importers must publish
+      // the complete map even when source accessors are sparse.
+      vertices: new Float32Array(4 * 20),
+      attributes: {
+        position: new Float32Array(4 * 3),
+        normal: new Float32Array(4 * 3),
+        uv: new Float32Array(4 * 2),
+        tangent: new Float32Array(4 * 4),
+        skinIndex: new Uint16Array(4 * 4),
+        skinWeight: new Float32Array(4 * 4),
+        uv1: new Float32Array(4 * 2),
+      },
+      submeshes: [
+        {
+          indexOffset: 0,
+          indexCount: 0,
+          vertexCount: 4,
+          topology: 'triangle-list',
+          materialSlot: 0,
+        },
+      ],
+      materialSlots: [{ slotName: 'default' }],
+    };
+    const world = new World();
+    const handle = world.allocSharedRef('MeshAsset', mesh);
+
+    const resident = store.ensureResident(handle, mesh);
+
+    expect(resident.ok).toBe(true);
+    const entry = store.getMeshGpuHandles(handle);
+    expect(entry?.layoutProjection).toEqual(deriveVertexLayoutProjection(mesh.attributes));
+    expect(entry?.layoutProjection.arrayStride).toBe(80);
+    expect(entry?.vertexCount).toBe(4);
+  });
+});

package/src/__tests__/gpu-scene-field-type-owner.test-d.ts

@@ -0,0 +1,27 @@
+/// <reference types="node" />
+
+import { readFileSync } from 'node:fs';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type { GpuSceneField, GpuSceneFieldType, GpuSceneScalar } from '../gpu-scene-schema';
+
+type ExpectedGpuSceneFieldType = 'u32' | 'i32' | 'f32' | 'vec4<f32>' | 'mat4x4<f32>';
+
+const schemaSource = readFileSync(new URL('../gpu-scene-schema.ts', import.meta.url), 'utf8');
+
+describe('GPU Scene field type owner', () => {
+  it('keeps the exact scalar and field-type declarations', () => {
+    expectTypeOf<GpuSceneScalar>().toEqualTypeOf<'u32' | 'i32' | 'f32'>();
+    expectTypeOf<GpuSceneFieldType>().toEqualTypeOf<ExpectedGpuSceneFieldType>();
+    expectTypeOf<ExpectedGpuSceneFieldType>().toEqualTypeOf<GpuSceneFieldType>();
+    expectTypeOf<GpuSceneField['type']>().toEqualTypeOf<GpuSceneFieldType>();
+    expectTypeOf<'unknown'>().not.toExtend<GpuSceneFieldType>();
+  });
+
+  it('keeps TYPE_LAYOUT as the executable field-type owner', () => {
+    expect(schemaSource).toContain('const TYPE_LAYOUT = {');
+    expect(schemaSource).toContain('export type GpuSceneFieldType = keyof typeof TYPE_LAYOUT;');
+    expect(schemaSource).not.toContain(
+      "export type GpuSceneFieldType = GpuSceneScalar | 'vec4<f32>' | 'mat4x4<f32>';",
+    );
+  });
+});