@forgeax/engine-render 0.1.30 → 0.1.32

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

@@ -6,6 +6,7 @@ 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 mainPass = read('../record/main-pass.ts');
 const shadowPass = read('../record/shadow-pass.ts');
 const paletteAllocator = read('../systems/skin-palette-allocator.ts');
 const extractRoot = read('../render-system-extract.ts');
@@ -46,6 +47,17 @@ describe('GPU-driven baseline characterization', () => {
     expect(productionRaster).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).not.toContain(
+      'gpuDrivenStandardPbrFrameResources.materialBindGroups.some((group) => group === undefined)',
+    );
+    expect(productionRaster).toMatch(
+      /material bind group for global slot \$\{globalMaterialSlot\}/,
+    );
+  });
+
   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-production.integration.test.ts

@@ -824,6 +824,7 @@ describe('GPU-driven production projection', () => {
         device.createBindGroup({ layout: materialBindGroup, entries: [] }).unwrap(),
       ],
     };
+    let activeFrameResources = frameResources;
     const color = graph
       .createTexture('gpu-driven-production-color', {
         format: 'rgba8unorm',
@@ -842,7 +843,8 @@ describe('GPU-driven production projection', () => {
             clearValue: { r: 0, g: 0, b: 0, a: 1 },
           },
         ],
-        encode: ({ pass, resources }) => gpu.encode(viewBindGroup, pass, resources, frameResources),
+        encode: ({ pass, resources }) =>
+          gpu.encode(viewBindGroup, pass, resources, activeFrameResources),
       })
       .unwrap();
     const compiled = graph.compile({ device, surfaceSize: { width: 1, height: 1 } }).unwrap();
@@ -872,6 +874,30 @@ describe('GPU-driven production projection', () => {
       production.inspect().batchCount,
     );
 
+    const missingMaterialFrameResources = {
+      ...frameResources,
+      materialBindGroups: [undefined] as unknown as typeof frameResources.materialBindGroups,
+    };
+    activeFrameResources = missingMaterialFrameResources;
+    const missingMaterialEncoder = device
+      .createCommandEncoder({ label: 'gpu-driven-production-missing-material' })
+      .unwrap();
+    const missingMaterialResult = compiled.execute({
+      viewBindGroup,
+      encoder: missingMaterialEncoder,
+      gpuDrivenStandardPbrFrameResources: missingMaterialFrameResources,
+    } as unknown as RenderPipelineFrame);
+    expect(missingMaterialResult.ok).toBe(false);
+    if (!missingMaterialResult.ok) {
+      expect(missingMaterialResult.error.code).toBe('pass-encode-failed');
+      const detail = missingMaterialResult.error.detail;
+      expect(detail).toBeDefined();
+      expect(detail !== undefined && 'cause' in detail).toBe(true);
+      if (detail === undefined || !('cause' in detail)) return;
+      expect(detail.cause).toBeInstanceOf(RhiError);
+      expect((detail.cause as RhiError).code).toBe('rhi-not-available');
+    }
+
     // The facet projection is the same admission set consumed by the GPU
     // candidate upload. A suppressed entity must disappear from the indirect
     // plan without making the remaining entity fall back to CPU validation.

package/src/__tests__/instances-store.unit.test.ts

@@ -51,6 +51,21 @@ describe('InstanceCollectionStore', () => {
     ]);
   });
 
+  it('keeps renderer dirty ranges intact when inspection peeks between updates', () => {
+    const store = new InstanceCollectionStore();
+    const created = store.create({ transforms: identityTransforms(2) }).unwrap();
+    store.snapshot(created.collectionId).unwrap();
+
+    store.update(created.collectionId, { start: 0, transforms: identityTransforms(1) }).unwrap();
+    const inspected = store.peek(created.collectionId).unwrap();
+    expect(inspected.dirtyRanges).toEqual([{ start: 0, end: 1 }]);
+    store.update(created.collectionId, { start: 1, transforms: identityTransforms(1) }).unwrap();
+
+    expect(store.snapshot(created.collectionId).unwrap().dirtyRanges).toEqual([
+      { start: 0, end: 2 },
+    ]);
+  });
+
   it('keeps collection identity in the renderer cache key', () => {
     const first = instanceCollectionCacheKey(0, { cacheKey: 9, collectionId: 1 });
     const second = instanceCollectionCacheKey(0, { cacheKey: 9, collectionId: 2 });

package/src/__tests__/prepared-gpu-driven-pbr.integration.test.ts

@@ -404,6 +404,34 @@ describe('prepared Standard PBR producer-to-record integration', () => {
     expect(result.ok).toBe(true);
   });
 
+  it('keeps a video material on the CPU residual beside an eligible static PBR draw', () => {
+    const source = artifact();
+    const staticMaterial = material();
+    const videoMaterial: MaterialSnapshot = {
+      ...staticMaterial,
+      videoTextureFields: new Map([['baseColorTexture', 7]]) as never,
+    };
+    const mesh = createBoxGeometry(1, 1, 1).unwrap();
+    const staticDraws = buildGpuDrivenDraws({
+      mesh,
+      materials: [staticMaterial],
+      fallbackMaterial: staticMaterial,
+      baseSnapshot: snapshot(staticMaterial),
+      getMaterialShaderArtifact: () => source,
+    });
+    const videoDraws = buildGpuDrivenDraws({
+      mesh,
+      materials: [videoMaterial],
+      fallbackMaterial: videoMaterial,
+      baseSnapshot: snapshot(videoMaterial),
+      getMaterialShaderArtifact: () => source,
+    });
+
+    expect(staticDraws[0]?.prepared).toBeDefined();
+    expect(videoDraws[0]?.prepared).toBeUndefined();
+    expect(videoDraws[0]?.preparationError).toBeUndefined();
+  });
+
   it('admits a producer-backed custom material without a Standard shader name', () => {
     const source = customArtifact();
     const customMaterial: MaterialSnapshot = {

package/src/assembly/webgpu-ready.ts

@@ -28,6 +28,7 @@ import { ok, RhiError } from '@forgeax/engine-rhi';
 import { findVariantByKey, type ShaderCatalog } from '@forgeax/engine-shader';
 import type { ManifestEntry } from '@forgeax/engine-types';
 import { handleSlot } from '@forgeax/engine-types';
+import { prewarmDepthOfField } from '../features/depth-of-field/depth-of-field-assembly';
 import { prewarmAtmosphereShaders } from './atmosphere-shader-prewarm';
 import { prewarmSsrShaders } from './ssr-shader-prewarm';
 
@@ -222,6 +223,7 @@ export async function buildReadyWebGPU(
     readonly motionBlur?: string;
     readonly taaResolve?: string;
   }) => void,
+  registerBuiltinDepthOfField: Parameters<typeof prewarmDepthOfField>[2],
   /** Install manifest-owned volume utility sources only after all four modules compile. */
   setVolumetricFogShaderSources: (sources: VolumetricFogShaderSources) => void,
   /** Install manifest-owned SSR utility sources only after all five modules compile. */
@@ -1145,11 +1147,8 @@ export async function buildReadyWebGPU(
     );
     registerBuiltinTonemap(tonemapEntry.wgsl);
 
-    // Temporal fullscreen passes execute synchronously from the compiled graph,
-    // so their shader modules must be warmed before the initialization barrier
-    // resolves. Otherwise the first tight draw loop sees an asynchronous
-    // `rhi-not-available` result and leaves the temporal targets cleared even
-    // though the graph topology is present.
+    // Prewarm temporal fullscreen modules before readiness so first-frame
+    // recording cannot encounter an asynchronous compile miss.
     const prewarmTemporal = async (entry: ManifestEntry | undefined, id: string) => {
       if (entry === undefined) return;
       const prewarm = await runShimStep(
@@ -1172,6 +1171,7 @@ export async function buildReadyWebGPU(
     };
     await prewarmTemporal(motionBlurEntry, 'forgeax.motion-blur');
     await prewarmTemporal(taaResolveEntry, 'forgeax.taa-resolve');
+    await prewarmDepthOfField(manifestEntries, prewarmTemporal, registerBuiltinDepthOfField);
     registerBuiltinTemporalPostProcesses({
       ...(motionBlurEntry === undefined ? {} : { motionBlur: motionBlurEntry.wgsl }),
       ...(taaResolveEntry === undefined ? {} : { taaResolve: taaResolveEntry.wgsl }),

package/src/assembly/webgpu-renderer.ts

@@ -53,6 +53,10 @@ import {
   RenderFeatureCapabilityMissingError,
   RenderFeatureStageFailedError,
 } from '../errors/render';
+import {
+  dofInspection,
+  registerDepthOfFieldBuiltins,
+} from '../features/depth-of-field/depth-of-field-assembly';
 import { createRenderFeatureHost } from '../features/host';
 import { RENDER_FEATURE_VERTEX_LAYOUTS } from '../features/prepared-graphics';
 import type { RenderFeature, RenderFeatureShaderModuleMode } from '../features/types';
@@ -1248,13 +1252,6 @@ async function makeWebGPURenderer(
     }
     return undefined;
   };
-  // feat-20260622-s5 M3 / w17: the pipeline build is factored into a closure so
-  // the recover() rebuild can re-run the SAME three-step assembly against the
-  // freshly-acquired device (SSOT — one build path, one set of seed callbacks).
-  // All captured references (getShader / gpuStore / getShaderModuleAdapter /
-  // materialShaderPipelineCache / renderSystem) are stable across recover; only
-  // `internals.device` / `internals.pack` are read live, so a rebuild after a
-  // device swap compiles against the new device.
   const promotePipelineExtendedLighting = (state: PipelineState, scope: DeviceScope): void => {
     if (
       state.extendedLightingAvailable !== true ||
@@ -1287,9 +1284,10 @@ async function makeWebGPURenderer(
     };
     extendedLightingState = promoteExtendedLightingCandidate(extendedLightingState, candidate);
   };
-  let tonemapRegistered = false;
-  let fxaaRegistered = false;
-  let temporalPostProcessesRegistered = false;
+  let tonemapRegistered = false,
+    fxaaRegistered = false;
+  let temporalPostProcessesRegistered = false,
+    depthOfFieldRegistered = false;
   const buildPipeline = (
     scope: DeviceScope = activeDeviceScope,
     device: RhiDevice = currentBuildDevice(),
@@ -1311,7 +1309,6 @@ async function makeWebGPURenderer(
           ),
       materialShaderUvSetCounts.get('forgeax::default-standard-pbr') ?? 0,
       requiredFullscreenPostProcesses,
-      // Publish growth and capacity together for the active or candidate device.
       (hook, state) => {
         if (candidateBuildState !== undefined) {
           candidateBuildState.growMeshSsbo = hook;
@@ -1321,12 +1318,10 @@ async function makeWebGPURenderer(
           internals.meshSsboState = state;
         }
       },
-      // Both module adapters consume the generation's eager shader cache.
       (label, module) => {
         getShaderModuleAdapter().seedModule(label, module);
         getImmediateShaderModuleAdapter().seedModule(label, module);
       },
-      // Prewarm only the active build generation's material pipeline cache.
       (key, pso, group2Contract) => {
         const pipelineCache = currentPipelineCacheState().materialShaderPipelineCache;
         if (!pipelineCache.has(key)) {
@@ -1334,7 +1329,6 @@ async function makeWebGPURenderer(
         }
         materialShaderPipelineGroup2Contracts.set(pso as object, group2Contract);
       },
-      // Register the output transform after manifest loading, once RenderSystem exists.
       (source: string) => {
         if (candidateBuildState !== undefined || tonemapRegistered) return;
         renderSystem.registerBuiltinPostProcess(STANDARD_OUTPUT_TRANSFORM_FEATURE_ID, {
@@ -1371,6 +1365,11 @@ async function makeWebGPURenderer(
         }
         temporalPostProcessesRegistered = true;
       },
+      (entries: { readonly singleSample?: string; readonly multisampled?: string }) => {
+        if (candidateBuildState !== undefined || depthOfFieldRegistered) return;
+        registerDepthOfFieldBuiltins(renderSystem, entries);
+        depthOfFieldRegistered = true;
+      },
       (sources: VolumetricFogShaderSources) => {
         internals.volumetricFogShaders = sources;
       },
@@ -2810,6 +2809,7 @@ async function makeWebGPURenderer(
         ...(renderSystem.motionBlurInspection === undefined
           ? {}
           : { motionBlur: Object.freeze(renderSystem.motionBlurInspection) }),
+        ...dofInspection(renderSystem.depthOfFieldInspection),
         ...(renderSystem.lodOcclusionInspection === undefined
           ? {}
           : { lodOcclusion: Object.freeze(renderSystem.lodOcclusionInspection) }),

package/src/components/depth-of-field.ts

@@ -0,0 +1,45 @@
+import { defineComponent, type SchemaOf, type ShapeOf } from '@forgeax/engine-ecs';
+
+/** Closed quality budget used by the built-in camera depth-of-field pass. */
+export type DepthOfFieldQuality = 'low' | 'medium' | 'high';
+
+export const DepthOfFieldQualityValue = Object.freeze({
+  low: 0,
+  medium: 1,
+  high: 2,
+} as const);
+
+/** Selects which signed circle-of-confusion side contributes to the image. */
+export type DepthOfFieldSide = 'both' | 'near' | 'far';
+
+export const DepthOfFieldSideValue = Object.freeze({
+  both: 0,
+  near: 1,
+  far: 2,
+} as const);
+
+/** Active-camera physical depth-of-field authoring data; presence enables it. */
+export const DepthOfField = defineComponent('DepthOfField', {
+  focusDistance: { type: 'f32', default: 8 },
+  fStop: { type: 'f32', default: 2.8 },
+  sensorHeight: { type: 'f32', default: 0.024 },
+  maxRadiusPixels: { type: 'f32', default: 16 },
+  quality: { type: 'f32', default: DepthOfFieldQualityValue.medium },
+  blurSide: { type: 'f32', default: DepthOfFieldSideValue.both },
+});
+
+export type DepthOfFieldData = ShapeOf<SchemaOf<typeof DepthOfField>>;
+
+export function depthOfFieldQualityFromF32(value: number): DepthOfFieldQuality | undefined {
+  if (value === DepthOfFieldQualityValue.low) return 'low';
+  if (value === DepthOfFieldQualityValue.medium) return 'medium';
+  if (value === DepthOfFieldQualityValue.high) return 'high';
+  return undefined;
+}
+
+export function depthOfFieldSideFromF32(value: number): DepthOfFieldSide | undefined {
+  if (value === DepthOfFieldSideValue.both) return 'both';
+  if (value === DepthOfFieldSideValue.near) return 'near';
+  if (value === DepthOfFieldSideValue.far) return 'far';
+  return undefined;
+}

package/src/components/directional-light.ts

@@ -60,7 +60,8 @@ export {
  *   splitLambda    ∈ [0,1]      — PSSM split weight (default 0.75)
  *   cascadeBlend   ∈ [0,0.5]    — blend width between cascades (default 0.2)
  *   mapSize        >= 1         — shadow map resolution (default 2048)
- *   depthBias                    — normalized receiver depth subtraction (default 0.00001)
+ *   depthBias                    — normalized receiver depth floor (default 0.00001),
+ *                                  plus automatic texel/filter/slope coverage
  *   normalBias                   — world-space receiver normal offset (default 0.05)
  *   shadowDistance > 0           — how far shadows reach in front of the camera,
  *                                  in world units (default 200). This is the sole

package/src/components/index.ts

@@ -1,6 +1,7 @@
 export * from './atmosphere';
 export * from './camera';
 export * from './cube-camera';
+export * from './depth-of-field';
 export * from './directional-light';
 export * from './dynamic-resolution';
 export * from './fog';

package/src/extract/camera.ts

@@ -11,12 +11,17 @@ import {
   tonemapFromF32,
   validateCameraColorGrading,
 } from '../components/camera';
+import { DepthOfField } from '../components/depth-of-field';
 import {
   DynamicResolution,
   validateDynamicResolutionCamera,
 } from '../components/dynamic-resolution';
 import { MotionBlur } from '../components/motion-blur';
 import { ScreenSpaceReflection } from '../components/screen-space-reflection';
+import {
+  depthOfFieldRequestFailure,
+  resolveDepthOfFieldParams,
+} from '../features/depth-of-field/depth-of-field-params';
 import type { CameraSnapshot } from '../render-contract';
 import { getActiveCamera, selectActiveCameraIndex } from '../systems/active-camera';
 
@@ -32,15 +37,26 @@ export function extractCameraSnapshots(world: World): CameraSnapshot[] {
   const cameraQuery = world
     .query({
       read: [Camera],
-      optional: [MotionBlur, DynamicResolution, ScreenSpaceReflection],
+      optional: [MotionBlur, DynamicResolution, ScreenSpaceReflection, DepthOfField],
       with: [GlobalTransform],
     })
     .unwrap();
   for (const row of cameraQuery) {
     const cam = row.get(Camera);
     const motionBlur = row.get(MotionBlur);
+    const depthOfField = row.get(DepthOfField);
     validateCameraColorGrading(cam.temperature, cam.tint, cam.colorLutStrength);
     const dynamicResolution = row.get(DynamicResolution);
+    const projection = cameraProjectionFromF32(cam.projection);
+    const depthOfFieldResult = resolveDepthOfFieldParams(depthOfField, {
+      projection,
+      fov: cam.fov,
+      near: cam.near,
+      far: cam.far,
+    });
+    const depthOfFieldError = depthOfFieldResult.ok
+      ? undefined
+      : depthOfFieldRequestFailure(depthOfFieldResult.error);
     const screenSpaceReflection = row.get(ScreenSpaceReflection);
     const entity = row.entity as EntityHandle;
     const worldMat = readWorldMatrix(world, entity);
@@ -57,7 +73,7 @@ export function extractCameraSnapshots(world: World): CameraSnapshot[] {
       aspect: cam.aspect,
       near: cam.near,
       far: cam.far,
-      projection: cameraProjectionFromF32(cam.projection),
+      projection,
       orthoLeft: cam.left,
       orthoRight: cam.right,
       orthoBottom: cam.bottom,
@@ -86,6 +102,10 @@ export function extractCameraSnapshots(world: World): CameraSnapshot[] {
         cam.clearColor[2] ?? 0,
         cam.clearColor[3] ?? 1,
       ],
+      ...(depthOfFieldResult.ok && depthOfFieldResult.value !== undefined
+        ? { depthOfField: depthOfFieldResult.value }
+        : {}),
+      ...(depthOfFieldError === undefined ? {} : { depthOfFieldError }),
       ...(motionBlur === undefined
         ? {}
         : {