@forgeax/engine-render 0.1.28 → 0.1.30

package/src/__tests__/frame-targets.unit.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+
+import { graphExecutionPhase } from '../record/frame-targets';
+
+describe('graph execution phase classification', () => {
+  it('keeps SSR pass families bounded while retaining mip-level detail in the pass name', () => {
+    expect(graphExecutionPhase('ssr-hiz-seed')).toBe('record/graph-execute/ssr-hiz');
+    expect(graphExecutionPhase('ssr-hiz-reduce-1')).toBe('record/graph-execute/ssr-hiz');
+    expect(graphExecutionPhase('ssr-hiz-reduce-9')).toBe('record/graph-execute/ssr-hiz');
+    expect(graphExecutionPhase('ssr-trace')).toBe('record/graph-execute/ssr-trace');
+    expect(graphExecutionPhase('ssr-temporal')).toBe('record/graph-execute/ssr-temporal');
+    expect(graphExecutionPhase('ssr-reflection-mip-1')).toBe(
+      'record/graph-execute/ssr-reflection-mip',
+    );
+    expect(graphExecutionPhase('ssr-reflection-mip-9')).toBe(
+      'record/graph-execute/ssr-reflection-mip',
+    );
+    expect(graphExecutionPhase('ssr-compose')).toBe('record/graph-execute/ssr-compose');
+  });
+
+  it('keeps unrelated extension passes in the explicit other bucket', () => {
+    expect(graphExecutionPhase('custom-post-process')).toBe('record/graph-execute/other');
+  });
+});

package/src/__tests__/fullscreen-feature-plan.unit.test.ts

@@ -66,6 +66,9 @@ describe('fullscreen RenderFeature plan', () => {
     expect(postProcessShaderEntrySignature(base)).not.toBe(
       postProcessShaderEntrySignature({ ...base, reads: ['other-color'] }),
     );
+    expect(postProcessShaderEntrySignature(base)).not.toBe(
+      postProcessShaderEntrySignature({ ...base, fragmentEntryPoint: 'fs_tone_only' }),
+    );
     expect(postProcessShaderModuleLabel('test::fullscreen', base.source)).not.toBe(
       postProcessShaderModuleLabel('test::fullscreen', `${base.source}\n// next`),
     );

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

@@ -0,0 +1,79 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const read = (path: string): string => readFileSync(new URL(path, import.meta.url), 'utf8');
+const count = (source: string, pattern: RegExp): number => source.match(pattern)?.length ?? 0;
+
+const productionRaster = read('../gpu-driven/production-raster.ts');
+const shadowPass = read('../record/shadow-pass.ts');
+const paletteAllocator = read('../systems/skin-palette-allocator.ts');
+const extractRoot = read('../render-system-extract.ts');
+const extractTail = read('../render-system-extract-tail.ts');
+const rendererSystem = read('../render-system.ts');
+const rendererFactory = read('../assembly/factory.ts');
+const webgpuReady = read('../assembly/webgpu-ready.ts');
+const webgpuPbrReady = read('../assembly/webgpu-pbr-ready.ts');
+const skinPaletteOwner = read('../assembly/skin-palette-owner.ts');
+const gpuDrivenOwner = read('../assembly/gpu-driven-owner.ts');
+
+describe('GPU-driven baseline characterization', () => {
+  it('records the exact source revision and current owner seams', () => {
+    const head = execFileSync('git', ['rev-parse', 'HEAD'], { encoding: 'utf8' }).trim();
+    expect(head).toMatch(/^[0-9a-f]{40}$/);
+    expect(extractRoot).toContain(
+      "export { defaultMaterialSnapshot, extractFrame, extractFrames } from './render-system-extract-tail';",
+    );
+    expect(extractTail).toContain('export function extractFrame');
+    expect(extractTail).toContain('read: [MeshRenderer]');
+    expect(webgpuPbrReady).toContain('export async function buildGpuDrivenPbrReadyModules');
+    expect(webgpuPbrReady).toContain('export function buildGpuDrivenPbrReadyLayouts');
+    expect(webgpuReady).toContain(
+      "import { buildGpuDrivenPbrReadyLayouts, buildGpuDrivenPbrReadyModules } from './webgpu-pbr-ready';",
+    );
+    expect(webgpuReady).toContain('const gpuDrivenModules = await buildGpuDrivenPbrReadyModules({');
+    expect(webgpuReady).toContain('gpuDrivenPbrPrograms:');
+    expect(webgpuReady).toContain('gpuDrivenPbrPipelineLayout:');
+    expect(rendererSystem).toContain('createGpuDrivenOwner(');
+  });
+
+  it('requires the prepared Standard PBR production owner', () => {
+    expect(productionRaster).not.toContain('GPU_DRIVEN_STANDARD_PBR_WGSL');
+    expect(productionRaster).not.toContain('class GpuDrivenPbrRaster');
+    expect(productionRaster).toContain('MaterialAbiRasterAdapter');
+    expect(productionRaster).toContain('preparedPbrCandidateEligible');
+    expect(productionRaster).toContain('deriveVertexBufferLayoutFromProjection');
+    expect(productionRaster).toContain('vertexLayout.arrayStride');
+  });
+
+  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\+\+\)/);
+    expect(shadowPass).toContain('recordShadowCasterDraws');
+  });
+
+  it('freezes the frame-local full palette write behavior', () => {
+    expect(paletteAllocator).toContain('resetForFrame');
+    expect(paletteAllocator).toContain('storageCursor = 0');
+    expect(paletteAllocator).toContain('poolCursor = 0');
+    expect(count(paletteAllocator, /queue\.writeBuffer/g)).toBe(2);
+    expect(paletteAllocator).toContain('writeJointPalette');
+  });
+
+  it('freezes current ownership and stable-frame inspection signals', () => {
+    expect(productionRaster).toContain('ownsAllDrawItems');
+    expect(productionRaster).not.toContain('ownsAllRenderables');
+    expect(rendererSystem).toContain('gpuDriven: gpuDrivenProduction.inspect()');
+    expect(productionRaster).toContain('gpuOwnedSnapshotsMaterialized');
+    expect(productionRaster).toContain('validatedGpuOwnedRows');
+    expect(productionRaster).toContain('cpuFallbackDrawItems');
+  });
+
+  it('keeps the single-query and single-palette-owner constraints visible', () => {
+    expect(count(extractTail, /read: \[MeshRenderer\]/g)).toBe(1);
+    const paletteOwners = [rendererFactory, skinPaletteOwner].join('\n');
+    expect(count(paletteOwners, /createSkinPaletteAllocator\(/g)).toBe(1);
+    expect(paletteAllocator).toContain('export function createSkinPaletteAllocator');
+    expect(gpuDrivenOwner).toContain('createGpuDrivenOwner');
+  });
+});

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

@@ -1,18 +1,70 @@
+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 {
     identity: { material: 'forgeax::default-standard-pbr', geometry: 'cube', deformation: 'rigid' },
     receiptGeneration: receipt.generation,
+    receiptIdentity: receipt.receiptIdentity,
     directEntry: receipt.directEntry,
     sceneIndexEntry: receipt.sceneIndexEntry,
     materialRow: receipt.materialRow,
@@ -81,14 +133,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 } });
@@ -98,20 +219,38 @@ describe('PBR prepared GPU-driven batch topology', () => {
     expect(plan.candidateCount).toBe(2);
     expect(plan.batches).toHaveLength(2);
     expect(plan.batches[0]?.key).toMatchObject({
-      preparedIdentity: 'forgeax::default-standard-pbr|cube|rigid',
+      preparedIdentity: 'forgeax::default-standard-pbr|cube|rigid|standard-pbr/material-row-v3',
       resourceIdentity: resourceClass,
     });
   });
 
+  it('keeps colored and uncolored ABI variants in separate prepared batches', () => {
+    const coloredReceipt = createStandardPbrArtifactReceipt(false, true);
+    const colored = prepared({
+      receiptIdentity: coloredReceipt.receiptIdentity,
+      vertexInputs: coloredReceipt.vertexInputs,
+    });
+    const topology = topologyFor(snapshot(1, prepared()), snapshot(2, colored));
+
+    expect(topology.plan().candidateCount).toBe(2);
+    expect(topology.plan().batches).toHaveLength(2);
+    expect(new Set(topology.plan().batches.map((batch) => batch.key.preparedIdentity))).toEqual(
+      new Set([
+        'forgeax::default-standard-pbr|cube|rigid|standard-pbr/material-row-v3',
+        'forgeax::default-standard-pbr|cube|rigid|standard-pbr/material-row-v3/vertex-color',
+      ]),
+    );
+  });
+
   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 +261,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 +271,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 +307,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);
 });