@forgeax/engine-render 0.1.32 → 0.1.34

package/src/__tests__/feature-depth-input.dawn.test.ts

@@ -1,11 +1,52 @@
 import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
 import type { RhiCommandEncoder } from '@forgeax/engine-rhi';
-import { createShaderModule, rhi } from '@forgeax/engine-rhi-webgpu';
+import { createShaderModule, createShaderModuleImmediate, rhi } from '@forgeax/engine-rhi-webgpu';
 import { ok } from '@forgeax/engine-types';
 import { expect, it } from 'vitest';
 import { createRenderFeatureGpuWorkOwner } from '../features/prepared-gpu-work';
 import { RenderFeatureComputeGraphProjection } from '../features/render-graph-compute';
 import { createRenderFeatureTarget } from '../features/targets';
+import {
+  GPU_TEXTURE_USAGE_COPY_SRC,
+  GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
+} from '../gpu-texture-usage';
+import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_MAP_READ } from '../gpu-usage';
+
+it('binds a depth-only view for the single-layer nearest depth input', async () => {
+  const adapter = (await rhi.requestAdapter()).unwrap();
+  const device = (await adapter.requestDevice()).unwrap();
+  const depth = device
+    .createTexture({
+      label: 'single-layer-nearest-depth-dawn',
+      size: { width: 1, height: 1 },
+      format: 'depth24plus-stencil8',
+      usage: 0x04 | 0x10,
+      textureBindingViewDimension: '2d',
+    })
+    .unwrap();
+  try {
+    const depthOnlyView = device
+      .createTextureView(depth, {
+        label: 'single-layer-nearest-depth-dawn.depth-only',
+        aspect: 'depth-only',
+      })
+      .unwrap();
+    const layout = device
+      .createBindGroupLayout({
+        label: 'single-layer-nearest-depth-dawn-bgl',
+        entries: [{ binding: 0, visibility: 4, texture: { sampleType: 'depth' } }],
+      })
+      .unwrap();
+    const bindGroup = device.createBindGroup({
+      label: 'single-layer-nearest-depth-dawn-bg',
+      layout,
+      entries: [{ binding: 0, resource: { kind: 'textureView', value: depthOnlyView } }],
+    });
+    expect(bindGroup.ok).toBe(true);
+  } finally {
+    device.destroyTexture(depth).unwrap();
+  }
+});
 
 it('samples this frame graph depth after its producer on the real GPU', async () => {
   const adapter = (await rhi.requestAdapter()).unwrap();
@@ -41,7 +82,7 @@ it('samples this frame graph depth after its producer on the real GPU', async ()
       size: { width: 1, height: 1 },
       format: 'depth32float',
       usage: 0x04 | 0x10,
-      textureBindingViewDimension: undefined,
+      textureBindingViewDimension: '2d',
     })
     .unwrap();
   const fallback = device.createTextureView(fallbackTexture, {}).unwrap();
@@ -119,3 +160,89 @@ it('samples this frame graph depth after its producer on the real GPU', async ()
     device.destroyTexture(fallbackTexture).unwrap();
   }
 });
+
+it('keeps fragment window depth aligned with the nearest-layer depth comparison', async () => {
+  const adapter = (await rhi.requestAdapter()).unwrap();
+  const device = (await adapter.requestDevice()).unwrap();
+  const source = `
+struct VsOut { @builtin(position) clipPosition: vec4<f32> }
+${await (
+  async () => {
+    const { readFile } = await import('node:fs/promises');
+    const { resolve } = await import('node:path');
+    const { fileURLToPath } = await import('node:url');
+    const root = fileURLToPath(new URL('../../../shader/src/', import.meta.url));
+    const medium = await readFile(resolve(root, 'single-layer-medium.wgsl'), 'utf8');
+    const match = medium.match(/fn clipDepth\(input: VsOut\) -> f32 \{[^}]+\}/u);
+    if (match === null) throw new Error('single-layer-medium clipDepth function is missing');
+    return match[0];
+  }
+)()}
+@vertex fn vs_main(@builtin(vertex_index) index: u32) -> VsOut {
+  var positions = array<vec2<f32>, 3>(
+    vec2<f32>(-1.0, -1.0), vec2<f32>(3.0, -1.0), vec2<f32>(-1.0, 3.0));
+  return VsOut(vec4<f32>(positions[index] * 5.0, 2.5, 5.0));
+}
+@fragment fn fs_main(input: VsOut) -> @location(0) vec4<f32> {
+  let mediumDepth = clipDepth(input);
+  if (mediumDepth > 0.5005) { discard; }
+  return vec4<f32>(input.clipPosition.z, mediumDepth, 1.0, 1.0);
+}`;
+  const shader = createShaderModuleImmediate(device, { code: source }).unwrap();
+  const output = device
+    .createTexture({
+      size: { width: 1, height: 1 },
+      format: 'rgba32float',
+      usage: GPU_TEXTURE_USAGE_COPY_SRC | GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
+      textureBindingViewDimension: '2d',
+    })
+    .unwrap();
+  const readback = device
+    .createBuffer({ size: 256, usage: GPU_BUFFER_USAGE_COPY_DST | GPU_BUFFER_USAGE_MAP_READ })
+    .unwrap();
+  try {
+    const emptyLayout = device.createPipelineLayout({ bindGroupLayouts: [] }).unwrap();
+    const pipeline = device
+      .createRenderPipeline({
+        layout: emptyLayout,
+        vertex: { module: shader, entryPoint: 'vs_main', buffers: [] },
+        fragment: {
+          module: shader,
+          entryPoint: 'fs_main',
+          targets: [{ format: 'rgba32float' }],
+        },
+        primitive: { topology: 'triangle-list' },
+      })
+      .unwrap();
+    const encoder = device.createCommandEncoder().unwrap();
+    const pass = encoder.beginRenderPass({
+      colorAttachments: [
+        {
+          view: device.createTextureView(output, {}).unwrap(),
+          loadOp: 'clear',
+          storeOp: 'store',
+          clearValue: [0, 0, 0, 0],
+        },
+      ],
+    });
+    pass.setPipeline(pipeline);
+    pass.draw(3);
+    pass.end();
+    encoder.copyTextureToBuffer(
+      { texture: output },
+      { buffer: readback, bytesPerRow: 256, rowsPerImage: 1 },
+      { width: 1, height: 1, depthOrArrayLayers: 1 },
+    );
+    device.queue.submit([encoder.finish().unwrap()]).unwrap();
+    await device.queue.onSubmittedWorkDone();
+    const mapped = (await readback.mapAsync(GPU_BUFFER_USAGE_MAP_READ)).unwrap();
+    const values = Array.from(new Float32Array(mapped.getMappedRange().unwrap().slice(0, 16)));
+    mapped.unmap();
+    expect(values[0]).toBeCloseTo(0.5, 5);
+    expect(values[1]).toBeCloseTo(0.5, 5);
+    expect(values[3]).toBeCloseTo(1.0, 5);
+  } finally {
+    device.destroyTexture(output).unwrap();
+    device.destroyBuffer(readback).unwrap();
+  }
+});

package/src/__tests__/frame-camera-selection.unit.test.ts

@@ -1,6 +1,6 @@
 import { World } from '@forgeax/engine-ecs';
 import { Transform } from '@forgeax/engine-scene';
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import { Atmosphere, Camera, DirectionalLight } from '../components';
 import {
   extractFrame,
@@ -89,6 +89,44 @@ describe('FrameCamera entity selection', () => {
 });
 
 describe('Atmosphere sun extraction', () => {
+  it('routes a missing sun through World, then retries after ownership is fixed', () => {
+    const world = new World();
+    world.spawn({ component: Atmosphere, data: {} }).unwrap();
+    spawnCamera(world, 1);
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    try {
+      expect(() =>
+        extractFrame(world, prepareExtractContext(world, { renderables: 'none' })),
+      ).toThrow(
+        expect.objectContaining({ code: 'sun-cardinality', detail: { field: 'sun', value: 0 } }),
+      );
+      const firstRouted = consoleError.mock.calls[0]?.[1] as
+        | { code?: string; detail?: { value?: number } }
+        | undefined;
+      expect(consoleError.mock.calls[0]?.[0]).toBe(
+        '[RenderSystem.extract (environment-selection)]',
+      );
+      expect(firstRouted?.code).toBe('sun-cardinality');
+      expect(firstRouted?.detail?.value).toBe(0);
+
+      // This is the direct extraction boundary. App.onError owns frame-loop
+      // Result failures and renderer events; World routes this internal
+      // producer error to its documented console boundary.
+
+      const firstSun = world
+        .spawn({
+          component: DirectionalLight,
+          data: { direction: [0, -0.25, 1], color: [1, 1, 1], intensity: 1 },
+        })
+        .unwrap();
+      const recovered = extractFrame(world, prepareExtractContext(world, { renderables: 'none' }));
+      expect(recovered.lights.directional?.entity).toBe(firstSun);
+      expect(consoleError).toHaveBeenCalledTimes(1);
+    } finally {
+      consoleError.mockRestore();
+    }
+  });
+
   it('keeps DirectionalLight intensity out of SunCandidate color', () => {
     const world = new World();
     world.spawn({ component: Atmosphere, data: {} }).unwrap();

package/src/__tests__/frame-plan-contract.unit.test.ts

@@ -13,6 +13,8 @@ const atmosphereParameters: AtmosphereParameters = {
   mieCoefficient: 0.005,
   mieDirectionalG: 0.8,
   sunAngularRadius: 0.004675,
+  circumsolarStrength: 1,
+  circumsolarWidth: 1,
 };
 
 function unwrapFrame(result: ReturnType<typeof selectEnvironmentFrame>): EnvironmentFrame {

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

@@ -41,10 +41,21 @@ describe('fullscreen RenderFeature plan', () => {
         { name: 'scene-color', kind: 'color', format: 'rgba16float', sampleCount: 1 },
       ]).ok,
     ).toBe(true);
-    expect(planned.value.resources[0]).toMatchObject({
+    const program = planned.value.resources[0];
+    expect(program).toMatchObject({
       kind: 'fullscreen-program',
       source: '@fragment fn fs_main() -> @location(0) vec4f { return vec4f(1); }',
     });
+    if (program?.kind !== 'fullscreen-program') throw new Error('fullscreen program missing');
+    const prewarm = feature.requiredFullscreenPostProcesses?.[0];
+    if (prewarm === undefined) throw new Error('fullscreen prewarm missing');
+    expect(program.name).not.toBe(prewarm.identity);
+    expect(postProcessShaderModuleLabel(program.source)).toBe(
+      postProcessShaderModuleLabel(prewarm.source),
+    );
+    expect(postProcessShaderPipelineLabel(program.name, program.source)).not.toBe(
+      postProcessShaderPipelineLabel(prewarm.identity, prewarm.source),
+    );
     expect(planned.value.passes).toEqual([]);
   });
 
@@ -69,8 +80,8 @@ describe('fullscreen RenderFeature plan', () => {
     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`),
+    expect(postProcessShaderModuleLabel(base.source)).not.toBe(
+      postProcessShaderModuleLabel(`${base.source}\n// next`),
     );
     expect(postProcessShaderPipelineLabel('test::fullscreen', base.source)).not.toBe(
       postProcessShaderPipelineLabel('test::fullscreen', `${base.source}\n// next`),

package/src/__tests__/gpu-dirty-ranges.unit.test.ts

@@ -0,0 +1,22 @@
+import { expect, test } from 'vitest';
+import { GpuDirtyRanges } from '../gpu-dirty-ranges';
+
+test('radix range merging matches an independent comparison-sort oracle', () => {
+  const dirty = new GpuDirtyRanges();
+  let seed = 891;
+  for (let trial = 0; trial < 32; trial++) {
+    const slots = Array.from({ length: trial * 173 }, () => {
+      seed = (Math.imul(seed, 1664525) + 1013904223) >>> 0;
+      return seed % 4096;
+    });
+    slots.push(0xffffffff, 0xfffffffe, 0xffffffff);
+    const expected: { start: number; end: number }[] = [];
+    for (const slot of [...new Set(slots)].sort((a, b) => a - b)) {
+      const last = expected.at(-1);
+      if (last?.end === slot) last.end++;
+      else expected.push({ start: slot, end: slot + 1 });
+    }
+    expect(dirty.coalesce(slots)).toEqual(expected);
+  }
+  expect(dirty.coalesce([])).toEqual([]);
+});

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

@@ -6,6 +6,8 @@ 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 productionRasterMaterial = read('../gpu-driven/production-raster-material.ts');
+const frameRecord = read('../record/frame.ts');
 const mainPass = read('../record/main-pass.ts');
 const shadowPass = read('../record/shadow-pass.ts');
 const paletteAllocator = read('../systems/skin-palette-allocator.ts');
@@ -43,13 +45,15 @@ describe('GPU-driven baseline characterization', () => {
     expect(productionRaster).not.toContain('class GpuDrivenPbrRaster');
     expect(productionRaster).toContain('MaterialAbiRasterAdapter');
     expect(productionRaster).toContain('preparedPbrCandidateEligible');
-    expect(productionRaster).toContain('deriveVertexBufferLayoutFromProjection');
-    expect(productionRaster).toContain('vertexLayout.arrayStride');
+    expect(productionRasterMaterial).toContain('deriveVertexBufferLayoutFromProjection');
+    expect(productionRasterMaterial).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).toMatch(
+      /gpuDrivenStandardPbrFrameResources === undefined\s*\|\|\s*gpuDrivenStandardPbrFrameResources\.materialBindGroups\.length === 0/,
+    );
     expect(mainPass).not.toContain(
       'gpuDrivenStandardPbrFrameResources.materialBindGroups.some((group) => group === undefined)',
     );
@@ -58,6 +62,15 @@ describe('GPU-driven baseline characterization', () => {
     );
   });
 
+  it('keeps probe-bearing rows on the GPU lane with the shared probe buffer', () => {
+    expect(frameRecord).toContain(
+      'const frameGpuDriven = reflectionFallbackCandidate ? undefined : gpuDriven;',
+    );
+    expect(frameRecord).not.toContain('const probeBlendFrame =');
+    expect(frameRecord).toContain('frameGpuDriven.scene?.probeBlend');
+    expect(frameRecord).toContain('probeBlendRecordBuffer: gpuProbeBlendBuffer');
+  });
+
   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-batch-topology-pbr.unit.test.ts

@@ -211,6 +211,18 @@ function resourceClassSnapshot(
 }
 
 describe('PBR prepared GPU-driven batch topology', () => {
+  it('keeps deferred and forward-only materials in separate graph-owned batches', () => {
+    const topology = topologyFor(
+      snapshot(1, prepared(), { deferredPass: true }),
+      snapshot(2, prepared(), { deferredPass: false }),
+    );
+
+    expect(topology.plan().batches).toHaveLength(2);
+    expect(new Set(topology.plan().batches.map((batch) => batch.key.materialPass))).toEqual(
+      new Set(['deferred', 'forward-only']),
+    );
+  });
+
   it('groups only by prepared identity and admits opaque plus Alpha Mask', () => {
     const mask = snapshot(2, prepared(), { paramSnapshot: { alphaCutoff: 0.5 } });
     const topology = topologyFor(snapshot(1, prepared()), mask);

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-material-artifacts.unit.test.ts

@@ -0,0 +1,143 @@
+import {
+  createStandardPbrArtifactReceipt,
+  type MaterialShaderArtifact,
+} from '@forgeax/engine-shader';
+import { describe, expect, it } from 'vitest';
+import { collectGpuDrivenMaterialArtifacts } from '../gpu-driven/material-artifacts';
+import type { PreparedGpuDrivenDraw } from '../gpu-driven/prepared-draw';
+import type { DispatchEntry, RenderableSnapshot } from '../render-system-extract';
+import { defaultMaterialSnapshot } from '../render-system-extract-tail';
+
+const receipt = createStandardPbrArtifactReceipt();
+
+function row(index: number) {
+  const material = { ...defaultMaterialSnapshot(index + 1), materialShaderId: `material-${index}` };
+  const prepared: PreparedGpuDrivenDraw = {
+    identity: { material: material.materialShaderId, geometry: 'cube', deformation: 'rigid' },
+    receiptGeneration: receipt.generation,
+    receiptIdentity: receipt.receiptIdentity,
+    directEntry: receipt.directEntry,
+    sceneIndexEntry: receipt.sceneIndexEntry,
+    materialRow: receipt.materialRow,
+    resourceSlots: receipt.resourceSlots,
+    uvSets: receipt.uvSets,
+    vertexInputs: receipt.vertexInputs,
+    alphaMask: receipt.alphaMask,
+    skinPaletteAddress: receipt.skinPaletteAddress,
+    topology: 'triangle-list',
+    indexed: true,
+    first: 0,
+    count: 36,
+    baseVertex: 0,
+  };
+  const source: RenderableSnapshot = {
+    assetHandle: 1,
+    worldId: 0,
+    entityKey: index,
+    transform: { world: new Float32Array(16) },
+    material,
+    materials: [material],
+    materialBindingSources: ['engine-default'],
+    gpuDrivenDraws: [
+      {
+        kind: 'indexed',
+        first: 0,
+        count: 36,
+        baseVertex: 0,
+        materialSlot: 0,
+        topology: 'triangle-list',
+        pipelineClass: 'pbr',
+        materialResourceClass: '',
+        prepared,
+      },
+    ],
+  };
+  return { source, renderableIndex: index };
+}
+
+function dispatch(index: number, id = `shadow-${index}`): DispatchEntry {
+  return {
+    entityIndex: index,
+    materialHandle: index + 1,
+    renderableIndex: index,
+    passIndex: 0,
+    queue: 2000,
+    layer: 0,
+    tags: { LightMode: 'ShadowCaster' },
+    renderState: undefined,
+    defines: undefined,
+    paramSnapshot: undefined,
+    materialShaderId: id,
+    vertexEntry: `${id}_vs`,
+    fragmentEntry: `${id}_fs`,
+  };
+}
+
+function artifact(id: string): MaterialShaderArtifact {
+  return {
+    material: id,
+    pass: 'Forward',
+    wgsl: '',
+    layoutIdentity: receipt.reflection.layoutIdentity,
+    bindings: [],
+    deps: [],
+    vertexInputs: [],
+    receipt,
+  };
+}
+
+function collect(rows: ReturnType<typeof row>[], shadowDispatch: DispatchEntry[]) {
+  return collectGpuDrivenMaterialArtifacts({
+    rows,
+    shadowRows: rows,
+    dispatch: [],
+    shadowDispatch,
+    resolve: (id) => artifact(id),
+    clustered: false,
+    reflectionFallback: false,
+  });
+}
+
+describe('GPU-driven material artifact selection', () => {
+  it('indexes shadow dispatch once instead of rescanning it for each prepared draw', () => {
+    const count = 64;
+    const rows = Array.from({ length: count }, (_, index) => row(index));
+    let tagReads = 0;
+    const entries = rows.map((_, index) => ({
+      ...dispatch(index),
+      tags: {
+        get LightMode() {
+          tagReads += 1;
+          return 'ShadowCaster';
+        },
+      },
+    }));
+    const result = collect(rows, entries);
+    expect(result.shadowMaterialArtifacts.size).toBe(count);
+    for (const [index, selected] of [...result.shadowMaterialArtifacts.values()].entries()) {
+      expect(selected.material).toBe(`shadow-${index}`);
+      expect(selected.vertexEntry).toBe(`shadow-${index}_vs`);
+      expect(selected.fragmentEntry).toBe(`shadow-${index}_fs`);
+    }
+    expect(tagReads).toBeLessThanOrEqual(count * 2);
+  });
+
+  it('keeps entry points with the selected last shadow program for a repeated draw key', () => {
+    const first = dispatch(0, 'first');
+    const last = { ...dispatch(0, 'last'), passIndex: 1 };
+    const selected = [...collect([row(0)], [first, last]).shadowMaterialArtifacts.values()][0];
+    expect(selected?.material).toBe('last');
+    expect(selected?.vertexEntry).toBe('last_vs');
+    expect(selected?.fragmentEntry).toBe('last_fs');
+  });
+
+  it('re-reads dispatch and program entries on the next collection', () => {
+    const rows = [row(0)];
+    const entries = [dispatch(0, 'before')];
+    const before = collect(rows, entries);
+    entries[0] = dispatch(0, 'after');
+    const after = collect(rows, entries);
+    expect([...before.shadowMaterialArtifacts.values()][0]?.vertexEntry).toBe('before_vs');
+    expect([...after.shadowMaterialArtifacts.values()][0]?.vertexEntry).toBe('after_vs');
+  });
+});

package/src/__tests__/gpu-driven-pbr.dawn.test.ts

@@ -91,11 +91,11 @@ const SHADOW_CASTER_GPU_ALPHA_VARIANT = SHADOW_CASTER_PRODUCER?.variants.find(
     defines.VERTEX_COLOR_AVAILABLE === false,
 );
 
-// The local/native evidence window remains 300 frames. CI already sets the
+// The local/native evidence window remains 60 frames. CI already sets the
 // Dawn lightweight profile for this roster; keep the same assertions while
 // bounding the repeated submit/readback loop so one fixture cannot dominate
 // the shared runner's critical path.
-const STABLE_FRAME_COUNT = process.env.FORGEAX_DAWN_LIGHTWEIGHT === '1' ? 12 : 300;
+const STABLE_FRAME_COUNT = process.env.FORGEAX_DAWN_LIGHTWEIGHT === '1' ? 12 : 60;
 
 function alphaMaskSnapshot(
   coordinateSet: 1 | 7 | undefined,