@forgeax/engine-render 0.1.27 → 0.1.29

package/src/__tests__/gpu-driven-batch-topology-pbr.unit.test.ts

@@ -1,13 +1,64 @@
+import { World } from '@forgeax/engine-ecs';
 import { vec3 } from '@forgeax/engine-math';
 import { createStandardPbrArtifactReceipt } from '@forgeax/engine-shader';
+import type { SamplerAsset, TextureAsset } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
+import { gpuDrivenMaterialResourceClass } from '../extract/gpu-driven';
 import { BatchTopology } from '../gpu-driven/batch-topology';
 import type { PreparedGpuDrivenDraw } from '../gpu-driven/prepared-draw';
 import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
 import { RenderScene } from '../scene/render-scene';
 
 const receipt = createStandardPbrArtifactReceipt();
-const resourceClass = JSON.stringify({ textures: 8, samplers: 8, video: 0 });
+const resourceClass = JSON.stringify({
+  textures: receipt.resourceSlots.filter((slot) => slot.kind === 'texture').length,
+  samplers: receipt.resourceSlots.filter((slot) => slot.kind === 'sampler').length,
+  video: 0,
+});
+
+interface StaticResourceClassEntry {
+  readonly texture: number;
+  readonly sampler: number;
+  readonly textureAsset: TextureAsset;
+  readonly samplerAsset: SamplerAsset;
+}
+
+function staticTextureAsset(index: number): TextureAsset {
+  return {
+    kind: 'texture',
+    shape: { viewDimension: '2d', extent: { width: 1, height: 1 } },
+    format: 'rgba8unorm',
+    data: new Uint8Array([index & 0xff, 127, 255 - (index & 0xff), 255]),
+    colorSpace: 'srgb',
+    mips: { kind: 'none' },
+  };
+}
+
+function staticSamplerAsset(): SamplerAsset {
+  return {
+    kind: 'sampler',
+    magFilter: 'linear',
+    minFilter: 'linear',
+    addressModeU: 'repeat',
+    addressModeV: 'repeat',
+  };
+}
+
+function staticResourceClassFixture(
+  world: World,
+  count: number,
+): readonly StaticResourceClassEntry[] {
+  const samplerAsset = staticSamplerAsset();
+  return Array.from({ length: count }, (_, index) => {
+    const textureAsset = staticTextureAsset(index);
+    return {
+      texture: Number(world.allocSharedRef('TextureAsset', textureAsset)),
+      sampler: Number(world.allocSharedRef('SamplerAsset', samplerAsset)),
+      textureAsset,
+      samplerAsset,
+    };
+  });
+}
 
 function prepared(overrides: Partial<PreparedGpuDrivenDraw> = {}): PreparedGpuDrivenDraw {
   return {
@@ -81,14 +132,83 @@ function snapshot(
   };
 }
 
+function updateSnapshot(value: RenderableSnapshot) {
+  return {
+    kind: 'update' as const,
+    worldId: value.worldId,
+    entityKey: value.entityKey,
+    snapshot: value,
+  };
+}
+
+function updateInstances(value: RenderableSnapshot) {
+  if (value.instances === undefined) throw new Error('expected Instances payload');
+  return {
+    kind: 'update' as const,
+    worldId: value.worldId,
+    entityKey: value.entityKey,
+    instances: value.instances,
+  };
+}
+
+function withInstances(value: RenderableSnapshot, instanceCount: number): RenderableSnapshot {
+  const transforms = new Float32Array(instanceCount * 16);
+  for (let index = 0; index < instanceCount; index += 1) {
+    const offset = index * 16;
+    transforms[offset] = 1;
+    transforms[offset + 5] = 1;
+    transforms[offset + 10] = 1;
+    transforms[offset + 15] = 1;
+  }
+  return {
+    ...value,
+    instances: {
+      transforms,
+      instanceCount,
+      cacheKey: value.entityKey,
+      archVersion: 0,
+      revision: instanceCount,
+    },
+  };
+}
+
 function topologyFor(...snapshots: readonly RenderableSnapshot[]): BatchTopology {
   const projection = new RenderScene();
-  projection.apply(snapshots.map((snapshot) => ({ kind: 'create' as const, snapshot })));
+  projection.apply(snapshots.map((snapshot) => updateSnapshot(snapshot)));
   const topology = new BatchTopology();
   topology.rebuild(projection.slotsSnapshot());
   return topology;
 }
 
+function resourceClassSnapshot(
+  entityKey: number,
+  drawPrepared: PreparedGpuDrivenDraw,
+  resourceIndex: number,
+  resources?: readonly StaticResourceClassEntry[],
+): RenderableSnapshot {
+  const resource = resources?.[resourceIndex];
+  const material = {
+    textureHandles: new Map([
+      ['baseColorTexture', resource?.texture ?? resourceIndex + 1],
+    ]) as never,
+    samplerHandles: new Map([
+      ['baseColorTexture', resource?.sampler ?? resourceIndex + 1001],
+    ]) as never,
+  } satisfies Partial<MaterialSnapshot>;
+  const value = snapshot(entityKey, drawPrepared, material);
+  const draw = value.gpuDrivenDraws?.[0];
+  if (draw === undefined) throw new Error('resource-class fixture draw is missing');
+  return {
+    ...value,
+    gpuDrivenDraws: [
+      {
+        ...draw,
+        materialResourceClass: gpuDrivenMaterialResourceClass(value.material),
+      },
+    ],
+  };
+}
+
 describe('PBR prepared GPU-driven batch topology', () => {
   it('groups only by prepared identity and admits opaque plus Alpha Mask', () => {
     const mask = snapshot(2, prepared(), { paramSnapshot: { alphaCutoff: 0.5 } });
@@ -105,13 +225,13 @@ describe('PBR prepared GPU-driven batch topology', () => {
 
   it('keeps numeric edits in place and patches only resource identity changes', () => {
     const projection = new RenderScene();
-    projection.apply([{ kind: 'create', snapshot: snapshot(1, prepared()) }]);
+    projection.apply([updateSnapshot(snapshot(1, prepared()))]);
     const topology = new BatchTopology();
     topology.rebuild(projection.slotsSnapshot());
     const stableRevision = topology.inspect().revision;
     const numeric = projection.apply([
       {
-        kind: 'update-transform',
+        kind: 'update',
         worldId: 0,
         entityKey: 1,
         world: snapshot(1, prepared()).transform.world,
@@ -122,8 +242,9 @@ describe('PBR prepared GPU-driven batch topology', () => {
 
     const resourceChanged = projection.apply([
       {
-        kind: 'create',
-        snapshot: snapshot(1, prepared({ resourceSlots: receipt.resourceSlots.slice(0, 2) })),
+        ...updateSnapshot(
+          snapshot(1, prepared({ resourceSlots: receipt.resourceSlots.slice(0, 2) })),
+        ),
       },
     ]);
     expect(topology.apply(resourceChanged)).toBe(true);
@@ -131,6 +252,30 @@ describe('PBR prepared GPU-driven batch topology', () => {
     expect(topology.inspect().candidateCount).toBe(1);
   });
 
+  it('patches one resource candidate while retaining unrelated batch membership', () => {
+    const projection = new RenderScene();
+    const first = resourceClassSnapshot(1, prepared(), 0);
+    const second = resourceClassSnapshot(2, prepared(), 0);
+    const control = resourceClassSnapshot(3, prepared(), 1);
+    projection.apply([updateSnapshot(first), updateSnapshot(second), updateSnapshot(control)]);
+    const topology = new BatchTopology();
+    topology.rebuild(projection.slotsSnapshot());
+    const before = topology.plan();
+    const changed = resourceClassSnapshot(2, prepared(), 2);
+    const delta = projection.apply([updateSnapshot(changed)]);
+    expect(topology.apply(delta)).toBe(true);
+    const after = topology.plan();
+    expect(after.candidateCount).toBe(before.candidateCount);
+    expect(topology.inspect()).toMatchObject({ revision: 2, patches: 1, rebuilds: 1 });
+    expect(after.batches).toHaveLength(3);
+    const beforeIdentities = before.batches.map((batch) => batch.key.resourceIdentity);
+    for (const identity of beforeIdentities) {
+      expect(
+        after.batches.find((batch) => batch.key.resourceIdentity === identity)?.candidates,
+      ).toHaveLength(1);
+    }
+  });
+
   it('routes Alpha Blend, morph and unsupported authoring out of the GPU lane', () => {
     const blend = snapshot(2, prepared(), {
       transparent: true,
@@ -143,4 +288,140 @@ describe('PBR prepared GPU-driven batch topology', () => {
     expect(topology.plan().candidateCount).toBe(1);
     expect(topology.inspect().ineligible).toBe(3);
   });
+
+  it('keeps the original draw index when an earlier draw is ineligible', () => {
+    const source = snapshot(1, prepared());
+    const first = source.gpuDrivenDraws?.[0];
+    expect(first).toBeDefined();
+    if (first === undefined) return;
+    const projection = new RenderScene();
+    projection.apply([
+      updateSnapshot({
+        ...source,
+        gpuDrivenDraws: [
+          {
+            ...first,
+            prepared: prepared({ identity: { ...prepared().identity, deformation: 'skin' } }),
+          },
+          { ...first, first: 12, prepared: prepared({ first: 12 }) },
+        ],
+      }),
+    ]);
+    const topology = new BatchTopology();
+    topology.rebuild(projection.slotsSnapshot());
+    expect(topology.plan().candidateCount).toBe(1);
+    expect(topology.plan().batches[0]?.candidates[0]?.drawItemIndex).toBe(1);
+    expect(topology.plan().batches[0]?.candidates[0]?.prepared?.first).toBe(12);
+  });
+
+  it('patches LOD payloads without changing batch topology or generation', () => {
+    const initial = {
+      ...snapshot(1, prepared()),
+      lods: [{ mesh: '00000000-0000-7000-8000-000000000001' as never, screenCoverage: 0.5 }],
+      lodHysteresis: 0.08,
+      instances: {
+        transforms: new Float32Array([
+          ...new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]),
+          ...new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]),
+        ]),
+        instanceCount: 2,
+        cacheKey: 1,
+        archVersion: 1,
+      },
+    };
+    const projection = new RenderScene();
+    projection.apply([updateSnapshot(initial)]);
+    const topology = new BatchTopology();
+    topology.rebuild(projection.slotsSnapshot());
+    const before = topology.plan();
+    const allocationsBefore = topology.inspect().membershipAllocations ?? 0;
+    const batchBefore = before.batches[0];
+    expect(batchBefore).toBeDefined();
+    if (batchBefore === undefined) return;
+
+    const updated = projection.apply([
+      {
+        ...updateSnapshot({
+          ...initial,
+          lods: [{ mesh: '00000000-0000-7000-8000-000000000001' as never, screenCoverage: 0.25 }],
+          lodHysteresis: 0.2,
+        }),
+      },
+    ]);
+    expect(topology.apply(updated)).toBe(true);
+    const after = topology.plan();
+    expect(after.revision).toBe(before.revision);
+    expect(after.payloadRevision).toBeGreaterThan(before.payloadRevision);
+    expect(after.batches[0]?.batchId).toBe(batchBefore.batchId);
+    expect(after.batches[0]?.generation).toBe(batchBefore.generation);
+    expect(after.batches[0]?.candidates[0]?.lodCoverages).toEqual([1, 0.25]);
+    expect(after.batches[0]?.candidates[0]?.lodHysteresis).toBe(0.2);
+    expect(topology.inspect()).toMatchObject({
+      payloadPatches: 1,
+      patches: 0,
+      membershipAllocations: allocationsBefore + 1,
+    });
+  });
+
+  it('updates candidate membership for Instances count transitions', () => {
+    const projection = new RenderScene();
+    const initial = withInstances(snapshot(1, prepared()), 1);
+    projection.apply([updateSnapshot(initial)]);
+    const topology = new BatchTopology();
+    topology.rebuild(projection.slotsSnapshot());
+    expect(topology.plan().candidateCount).toBe(1);
+
+    const sameCount = projection.apply([updateInstances(withInstances(initial, 1))]);
+    expect(sameCount.instanceUpdatedSlots).toHaveLength(1);
+    expect(topology.apply(sameCount)).toBe(false);
+    expect(topology.plan().candidateCount).toBe(1);
+
+    const expanded = projection.apply([updateInstances(withInstances(initial, 3))]);
+    expect(topology.apply(expanded)).toBe(true);
+    expect(topology.plan().candidateCount).toBe(3);
+
+    const empty = projection.apply([updateInstances(withInstances(initial, 0))]);
+    expect(topology.apply(empty)).toBe(true);
+    expect(topology.plan().candidateCount).toBe(0);
+    expect(topology.inspect().ineligible).toBe(1);
+  });
+  it.each([
+    1, 16, 256,
+  ])('keeps 100k prepared PBR candidates in %i resource-identity batches', (resourceClassCount) => {
+    const world = new World();
+    const resources = staticResourceClassFixture(world, resourceClassCount);
+    for (const resource of resources) {
+      expect(
+        world.sharedRefs.resolve<'TextureAsset', TextureAsset>(resource.texture as never),
+      ).toMatchObject({
+        ok: true,
+        value: { kind: 'texture', shape: { viewDimension: '2d' } },
+      });
+      expect(
+        world.sharedRefs.resolve<'SamplerAsset', SamplerAsset>(resource.sampler as never),
+      ).toMatchObject({
+        ok: true,
+        value: { kind: 'sampler' },
+      });
+    }
+    const candidates = Array.from({ length: 100_000 }, (_, entityKey) =>
+      resourceClassSnapshot(entityKey, prepared(), entityKey % resourceClassCount, resources),
+    );
+    const topology = topologyFor(...candidates);
+    const plan = topology.plan();
+    const inspection = topology.inspect();
+    const resourceIdentities = new Set(plan.batches.map((batch) => batch.key.resourceIdentity));
+
+    expect(plan.candidateCount).toBe(100_000);
+    expect(plan.batches).toHaveLength(resourceClassCount);
+    expect(plan.batches.reduce((total, batch) => total + batch.candidates.length, 0)).toBe(100_000);
+    expect(inspection).toMatchObject({
+      candidateCount: 100_000,
+      batchCount: resourceClassCount,
+      ineligible: 0,
+    });
+    expect(resourceIdentities).toHaveLength(resourceClassCount);
+    expect(topology.plan()).toBe(plan);
+    expect(topology.inspect().revision).toBe(1);
+  }, 30_000);
 });