@forgeax/engine-render 0.1.29 → 0.1.31

package/src/render-system-extract.ts

@@ -139,6 +139,7 @@ import {
   cameraExposureFromColumns,
   cameraProjectionFromF32,
   cubeCameraUpdateIntentFromF32,
+  DynamicResolution,
   Fog,
   MotionBlur,
   ReflectionProbe,
@@ -146,6 +147,7 @@ import {
   ScreenSpaceReflection,
   tonemapFromF32,
   tonemapToU32,
+  validateDynamicResolutionCamera,
 } from './components';
 import type { DirectionalShadowQuality } from './components/directional-shadow-filter';
 import type { LightValidationError } from './components/light-helpers';
@@ -932,6 +934,10 @@ export interface MaterialSnapshot {
    */
   readonly materialShaderId?: string | undefined;
   readonly materialProgramKeys?: Readonly<Record<string, string>> | undefined;
+  /** Producer-selected scene-index program keys, when a cooked publication carries them. */
+  readonly materialSceneIndexProgramKeys?:
+    | Readonly<Record<string, MaterialSceneIndexProgramKey>>
+    | undefined;
   /**
    * Stable source handle for the material asset. Record uses this only for
    * same-frame assembly reuse; GPU bind-group validity still comes from the
@@ -1055,6 +1061,15 @@ export interface MaterialSnapshot {
   readonly transparent?: boolean | undefined;
 }
 
+/**
+ * One producer-selected scene-index program, retaining the effective Pass
+ * kind so record does not infer shadow/depth semantics from an authored name.
+ */
+export interface MaterialSceneIndexProgramKey {
+  readonly specializationKey: string;
+  readonly pass: 'forward' | 'shadow' | 'depth';
+}
+
 export interface MaterialCacheChainIdentity {
   readonly asset: MaterialAsset;
   readonly parentGuid: string | undefined;
@@ -1262,8 +1277,13 @@ export interface ShadowCasterMembership {
   readonly materialHandle: number;
   readonly passIndex: number;
   readonly materialShaderId?: string;
+  /** Selected authored ShadowCaster entry points, when published. */
+  readonly vertexEntry?: string;
+  readonly fragmentEntry?: string;
   readonly renderState?: MaterialRenderState;
   readonly cpuReason?: ShadowCasterCpuReason;
+  /** Producer-owned result of the complete ShadowCaster admission check. */
+  readonly gpuDrivenEligible?: boolean;
 }
 
 /** Producer evidence for a concrete ShadowCaster pass that remains on CPU. */
@@ -1520,28 +1540,85 @@ export function materialProgramKeysForMaterial(
   assets: AssetRegistry,
   context: MaterialCookProgramContext | undefined,
 ): Readonly<Record<string, string>> | undefined {
+  return materialProgramKeysForAddress(material, assets, context, 'direct');
+}
+
+/** Resolve the producer's scene-index program key for each cooked Pass. */
+export function materialSceneIndexProgramKeysForMaterial(
+  material: MaterialAsset,
+  assets: AssetRegistry,
+  context: MaterialCookProgramContext | undefined,
+): Readonly<Record<string, MaterialSceneIndexProgramKey>> | undefined {
   const projection = assets.getMaterialProjectionForPayload(material);
   if (projection === undefined) return undefined;
   if (context === undefined)
     throw new Error('Published material selection requires renderer-owned compiler context');
-  return Object.fromEntries(
-    projection.passes.map((pass) => {
-      const mode = String(
-        (pass.renderState?.tags as Record<string, unknown> | undefined)?.LightMode ?? pass.name,
-      );
-      const selectedContext: MaterialCookProgramContext = {
-        ...context,
-        pass: /shadow/i.test(mode) ? 'shadow' : /depth/i.test(mode) ? 'depth' : 'forward',
-        pipeline: /deferred|gbuffer/i.test(mode) ? 'deferred' : context.pipeline,
-      };
-      return [
+  const entries: Record<string, MaterialSceneIndexProgramKey> = {};
+  for (const pass of projection.passes) {
+    const mode = String(
+      (pass.renderState?.tags as Record<string, unknown> | undefined)?.LightMode ?? pass.name,
+    );
+    const passKind = /shadow/i.test(mode)
+      ? ('shadow' as const)
+      : /depth/i.test(mode)
+        ? ('depth' as const)
+        : ('forward' as const);
+    const selectedContext: MaterialCookProgramContext = {
+      ...context,
+      pass: passKind,
+      pipeline: /deferred|gbuffer/i.test(mode) ? 'deferred' : context.pipeline,
+    };
+    try {
+      const selected = selectMaterialPassProgram(
+        projection,
         pass.name,
-        selectMaterialPassProgram(projection, pass.name, selectedContext).specializationKey,
-      ];
-    }),
+        selectedContext,
+        'scene-index',
+      );
+      entries[pass.name] = { specializationKey: selected.specializationKey, pass: passKind };
+    } catch (error) {
+      if (!isMissingMaterialProgram(error)) throw error;
+    }
+  }
+  return Object.keys(entries).length === 0 ? undefined : entries;
+}
+
+function isMissingMaterialProgram(error: unknown): boolean {
+  return (
+    error !== null &&
+    typeof error === 'object' &&
+    (error as { readonly code?: unknown }).code === 'material-specialization-not-cooked'
   );
 }
 
+function materialProgramKeysForAddress(
+  material: MaterialAsset,
+  assets: AssetRegistry,
+  context: MaterialCookProgramContext | undefined,
+  address: 'direct' | 'scene-index',
+): Readonly<Record<string, string>> | undefined {
+  const projection = assets.getMaterialProjectionForPayload(material);
+  if (projection === undefined) return undefined;
+  if (context === undefined)
+    throw new Error('Published material selection requires renderer-owned compiler context');
+  const entries: [string, string][] = [];
+  for (const pass of projection.passes) {
+    const mode = String(
+      (pass.renderState?.tags as Record<string, unknown> | undefined)?.LightMode ?? pass.name,
+    );
+    const selectedContext: MaterialCookProgramContext = {
+      ...context,
+      pass: /shadow/i.test(mode) ? 'shadow' : /depth/i.test(mode) ? 'depth' : 'forward',
+      pipeline: /deferred|gbuffer/i.test(mode) ? 'deferred' : context.pipeline,
+    };
+    entries.push([
+      pass.name,
+      selectMaterialPassProgram(projection, pass.name, selectedContext, address).specializationKey,
+    ]);
+  }
+  return entries.length === 0 ? undefined : Object.fromEntries(entries);
+}
+
 export function runtimeMaterialShaderIdForMaterial(
   passes: readonly MaterialPass[],
   programs: Readonly<Record<string, string>> | undefined,
@@ -1620,38 +1697,18 @@ export function shadowCasterCpuReason(
     return 'transparent';
   }
   if (morph !== undefined) return 'morph';
-  const isStandardPbr =
-    material.materialShaderId === 'forgeax::default-standard-pbr' ||
-    material.materialShaderId === 'forgeax::pbr-skin' ||
-    material.materialShaderId === 'forgeax::default-standard-pbr-skin';
-  if (!isStandardPbr) return 'unsupported-shader';
   const shadowEntry = shadowEntries[0];
-  if (
-    shadowEntry !== undefined &&
-    shadowEntry.materialShaderId !== undefined &&
-    shadowEntry.materialShaderId !== 'forgeax::default-shadow-caster'
-  ) {
-    return 'unsupported-shader';
-  }
   if (shadowEntry?.renderState !== undefined) return 'unsupported-render-state';
   if (draw === undefined) return 'missing-gpu-draw';
   if (draw.prepared === undefined) return 'unprepared';
-  const isSkinnedPbr =
-    material.materialShaderId === 'forgeax::pbr-skin' ||
-    material.materialShaderId === 'forgeax::default-standard-pbr-skin';
   const preparedMaterial = draw.prepared.identity.material;
   const preparedDeformation = draw.prepared.identity.deformation;
-  const materialContractMatches =
-    (material.materialShaderId === 'forgeax::default-standard-pbr' &&
-      preparedMaterial === 'forgeax::default-standard-pbr') ||
-    (isSkinnedPbr &&
-      (preparedMaterial === 'forgeax::pbr-skin' ||
-        preparedMaterial === 'forgeax::default-standard-pbr-skin'));
+  const materialContractMatches = preparedMaterial === material.materialShaderId;
   const deformationContractMatches =
     (skin === undefined && preparedDeformation === 'rigid') ||
     (skin !== undefined && preparedDeformation === 'skin');
   if (!materialContractMatches || !deformationContractMatches) return 'prepared-contract';
-  if (isSkinnedPbr && !hasFiniteOrderedSkinBounds(skin?.bounds)) {
+  if (preparedDeformation === 'skin' && !hasFiniteOrderedSkinBounds(skin?.bounds)) {
     return 'missing-skin-bounds';
   }
   return undefined;
@@ -2247,6 +2304,11 @@ export function resolveMaterialSnapshot(
   const resolved = resolvedResult.value;
   const allPasses = resolved.passes;
   const materialProgramKeys = materialProgramKeysForMaterial(asset, assetsRef, materialContext);
+  const materialSceneIndexProgramKeys = materialSceneIndexProgramKeysForMaterial(
+    asset,
+    assetsRef,
+    materialContext,
+  );
   const authoredFirstPassShader = runtimeMaterialShaderIdForMaterial(allPasses, undefined);
   const firstPassShader = runtimeMaterialShaderIdForMaterial(allPasses, materialProgramKeys);
   const pv = materialValuesToLinearRuntime(
@@ -2351,6 +2413,7 @@ export function resolveMaterialSnapshot(
     normalScale: normalScalePv,
     materialShaderId: firstPassShader,
     materialProgramKeys,
+    materialSceneIndexProgramKeys,
     materialHandle: handleRaw,
     renderState: pipelineRenderState(allPasses[0]?.renderState),
     paramSnapshot: paramSnap,
@@ -2726,7 +2789,11 @@ export function computeDirectionalCsm(
       resultLightViewProjs.push(new Float32Array(16));
       continue;
     }
-    const cascadeNear = cIdx === 0 ? sNear : (splits[cIdx - 1] ?? sFar);
+    // The receiver blends into this cascade before the preceding split.
+    // Fit that same overlap instead of sampling outside the next projection.
+    const previousSplit = splits[cIdx - 1] ?? sNear;
+    const cascadeNear =
+      cIdx === 0 ? sNear : Math.max(sNear, previousSplit * (1 - config.cascadeBlend));
     const cascadeFar = splits[cIdx] ?? sFar;
     const corners = computeFrustumCorners(
       cameraVP,
@@ -2768,7 +2835,7 @@ export function computeDirectionalCsm(
       minY,
       maxY,
       minZ,
-      maxZ,
+      maxZ: nearZ,
     });
     resultLightViewProjs.push(new Float32Array(mat4.multiply(mat4.create(), orthoProj, lightView)));
   }
@@ -2831,7 +2898,12 @@ export interface PreparedExtractContext {
   readonly getMaterialShaderArtifact:
     | ((
         materialShaderId: string,
-        vertexColorAvailable?: boolean,
+        request?: {
+          readonly vertexColorAvailable?: boolean;
+          readonly deformation?: 'rigid' | 'skin';
+          readonly pass?: 'forward' | 'shadow' | 'depth';
+          readonly address?: 'direct' | 'scene-index';
+        },
       ) => MaterialShaderArtifact | undefined)
     | undefined;
   /** Renderer-owned canonical source for explicit large instance collections. */
@@ -2852,13 +2924,14 @@ function collectCameraSnapshots(world: World): CameraSnapshot[] {
   const cameraQuery = world
     .query({
       read: [Camera],
-      optional: [MotionBlur, ScreenSpaceReflection],
+      optional: [MotionBlur, DynamicResolution, ScreenSpaceReflection],
       with: [Transform, GlobalTransform],
     })
     .unwrap();
   for (const row of cameraQuery) {
     const cam = row.get(Camera);
     const motionBlur = row.get(MotionBlur);
+    const dynamicResolution = row.get(DynamicResolution);
     const screenSpaceReflection = row.get(ScreenSpaceReflection);
     const entity = row.entity;
     const view = worldInternal._getArrayView(entity, GlobalTransform, 'world');
@@ -2881,6 +2954,9 @@ function collectCameraSnapshots(world: World): CameraSnapshot[] {
           colorLutStrength: cam.colorLutStrength,
         }
       : undefined;
+    const antialias = antialiasFromF32(cam.antialias);
+    const dynamicResolutionResult = validateDynamicResolutionCamera(dynamicResolution, antialias);
+    if (!dynamicResolutionResult.ok) throw dynamicResolutionResult.error;
     cameras.push({
       entityKey: entity as number,
       ...(target === undefined ? {} : { target }),
@@ -2900,7 +2976,10 @@ function collectCameraSnapshots(world: World): CameraSnapshot[] {
       exposure: cam.exposure,
       whitePoint: cam.whitePoint,
       ...(output === undefined ? {} : { output }),
-      antialias: antialiasFromF32(cam.antialias),
+      antialias,
+      ...(dynamicResolutionResult.value === undefined
+        ? {}
+        : { dynamicResolution: dynamicResolutionResult.value }),
       bloom: bloomEnabledFromF32(cam.bloom),
       bloomThreshold: cam.bloomThreshold,
       bloomIntensity: cam.bloomIntensity,
@@ -2982,6 +3061,7 @@ export function collectReflectionProbeFacts(world: World): ReflectionProbeFact[]
       priority: probe.priority,
       intensity: probe.intensity,
       resolution: probe.resolution,
+      boxProjection: probe.boxProjection,
       revision: probe.invalidationVersion,
       updateIntent: reflectionProbeUpdateIntentFromF32(probe.updateIntent),
       invalidationVersion: probe.invalidationVersion,
@@ -3068,7 +3148,12 @@ export function prepareExtractContext(
     readonly worldId?: number;
     readonly getMaterialShaderArtifact?: (
       materialShaderId: string,
-      vertexColorAvailable?: boolean,
+      request?: {
+        readonly vertexColorAvailable?: boolean;
+        readonly deformation?: 'rigid' | 'skin';
+        readonly pass?: 'forward' | 'shadow' | 'depth';
+        readonly address?: 'direct' | 'scene-index';
+      },
     ) => MaterialShaderArtifact | undefined;
     readonly instanceCollections?: InstanceCollectionStore;
   } = {},

package/src/render-system.ts

@@ -1,3 +1,4 @@
+import { projectCaptureScene } from './capture/scene-projection';
 import type { RenderSceneBounds } from './scene/render-scene-types';
 // @forgeax/engine-runtime - RenderSystem main entry (D-S2 three-stage Extract ->
 // Prepare -> Record + 4-tier error fan-out).
@@ -1246,7 +1247,7 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
     // explicit texture/sampler handles resolved to resident GPU resources.
     materialBgAssemblyCache: new Map(),
     // singleton material cache (flat Map<variant, BindGroup>; D-6).
-    singletonMaterialCache: new Map(),
+    shadowMaterialBindGroups: new WeakMap(),
     // post-process bind group cache (bloom / fxaa / ssao): identity-keyed
     // WeakMap chain so resize-retired transient targets rebuild automatically.
     postProcessBgCache: new WeakMap(),
@@ -2294,8 +2295,9 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
       if (producer === undefined || target === undefined) {
         return undefined;
       }
-      const width = Math.max(1, internals.canvas.width);
-      const height = Math.max(1, internals.canvas.height);
+      const descriptor = target.descriptor.kind === 'texture' ? target.descriptor : undefined;
+      const width = descriptor?.width ?? Math.max(1, internals.canvas.width);
+      const height = descriptor?.height ?? Math.max(1, internals.canvas.height);
       return Object.freeze({
         identity: 'standard-scene-temporal',
         producerId: 'forgeax::standard::scene-data',
@@ -2420,6 +2422,7 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
         }
       }
       try {
+        internals.recoveryColdWorkGuard?.beginFrame();
         pointsLinesOwner.beginFrame();
         // cameraOwner drives the surfaced cameras + frustum
         // cull; resourceOwner drives skylight/skybox/postProcess + per-world
@@ -2540,6 +2543,19 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
           cameras[0],
           frameState.frameNumber,
           skylight,
+          frame.reflectionProbes?.some((probe) => probe.updateIntent === 'on-change')
+            ? JSON.stringify([
+                persistentRenderScene.reflectionCaptureRevision(),
+                lights.directional,
+                lights.point,
+                lights.spot,
+                lights.rect,
+                skylight,
+                frame.skybox,
+                environment?.environmentSignature,
+              ])
+            : '',
+          frame.skybox,
         );
         latestCamera = cameras[0];
         frameState.ssrRequested = latestCamera?.screenSpaceReflection !== undefined;
@@ -3144,14 +3160,19 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
             Number.isFinite(deltaTime) ? Math.max(0, deltaTime) : 0,
           );
         }
+        const probeCaptureScene =
+          shadowCasterProjection !== undefined &&
+          reflectionProbeRecord.graph.work.some((work) => work.rawCaptureFace !== undefined)
+            ? projectCaptureScene(shadowCasterProjection, submissionRenderables, orderedDispatch)
+            : undefined;
         submitted = runProfiledRenderPhase(profileSession, 'record', () =>
           recordFrame(
             internals,
             resourceWorld,
             cameras,
             lights,
-            submissionRenderables,
-            orderedDispatch,
+            probeCaptureScene?.renderables ?? submissionRenderables,
+            probeCaptureScene?.displayDispatch ?? orderedDispatch,
             frameState,
             dispatchCounts,
             bindGroupCounts,
@@ -3181,6 +3202,9 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
               scheduler: cubeCaptureScheduler,
               state: cubeCaptureState,
               reflectionProbes: reflectionProbeRecord,
+              ...(probeCaptureScene === undefined
+                ? {}
+                : { captureDispatch: probeCaptureScene.captureDispatch }),
             } satisfies CubeCaptureFrameInput,
             environment?.environmentSignature ?? '',
             environment?.fogSignature ?? '',
@@ -3322,6 +3346,7 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
           }),
         );
       } finally {
+        internals.recoveryColdWorkGuard?.endFrame();
         if (ownsProfileFrame) {
           try {
             profileSession?.endFrame();
@@ -3439,7 +3464,10 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
           ? config
           : {
               clusterGrid: DEFAULT_CLUSTER_GRID,
-              ...(profileConfig.ssao ? { ssao: { enabled: true } } : {}),
+              ssao: {
+                enabled: profileConfig.ssao !== false,
+                ...(typeof profileConfig.ssao === 'object' ? profileConfig.ssao : {}),
+              },
               ...config,
             };
       if (resolvedConfig?.clusterGrid !== undefined) {
@@ -3792,7 +3820,7 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
       frameState.instancesBgPerEntity.clear();
       frameState.materialBgShared.clear();
       frameState.materialBgAssemblyCache.clear();
-      frameState.singletonMaterialCache.clear();
+      frameState.shadowMaterialBindGroups = new WeakMap();
       frameState.postProcessBgCache = new WeakMap();
       // Fullscreen PSOs are cached outside frameState because the normal
       // path reuses them across frames. They still carry opaque handles from

package/src/scene/render-scene.ts

@@ -758,6 +758,10 @@ export class RenderScene {
     return records;
   }
 
+  get contentRevision(): number {
+    return this.revision;
+  }
+
   inspect(): RenderSceneInspection {
     return {
       records: this.slotsSnapshot().map(({ slot, generation, worldId, entityKey }) => ({
@@ -2449,6 +2453,10 @@ export class PersistentRenderScene {
     return { min: [...bounds.min], max: [...bounds.max] };
   }
 
+  reflectionCaptureRevision(): string {
+    return `${this.fullRebuilds}:${this.composition?.projection.contentRevision ?? 0}`;
+  }
+
   inspect(): PersistentRenderSceneInspection {
     const entry = this.composition;
     const pointsLines = this.pointsLinesInspections;

package/src/ssao-config.ts

@@ -1,22 +1,24 @@
 // @forgeax/engine-render - SSAO parameter authority.
 
-import { err, ok, type Result } from '@forgeax/engine-types';
+import { err, ok, type RenderPipelineAsset, type Result } from '@forgeax/engine-types';
 import { PostProcessError } from './post-process-errors';
 
 export const SSAO_DEFAULT_RADIUS = 0.5;
 export const SSAO_DEFAULT_BIAS = 0.025;
 export const SSAO_DEFAULT_INTENSITY = 1.0;
 
-export interface SsaoParameterConfig {
-  readonly radius?: number | undefined;
-  readonly bias?: number | undefined;
-  readonly intensity?: number | undefined;
-}
+export type SsaoParameterConfig = Omit<
+  NonNullable<NonNullable<RenderPipelineAsset['config']>['ssao']>,
+  'enabled'
+>;
+
+export const SSAO_SAMPLE_COUNTS = { low: 16, medium: 32, high: 64 } as const;
 
 export interface ResolvedSsaoParameters {
   readonly radius: number;
   readonly bias: number;
   readonly intensity: number;
+  readonly quality: 'low' | 'medium' | 'high';
 }
 
 /**
@@ -29,6 +31,7 @@ export function getSsaoParameters(config: SsaoParameterConfig | undefined): Reso
     radius: config?.radius ?? SSAO_DEFAULT_RADIUS,
     bias: config?.bias ?? SSAO_DEFAULT_BIAS,
     intensity: config?.intensity ?? SSAO_DEFAULT_INTENSITY,
+    quality: config?.quality ?? 'high',
   };
 }
 
@@ -41,7 +44,7 @@ export function resolveSsaoParameters(
   config: SsaoParameterConfig | undefined,
 ): Result<ResolvedSsaoParameters, PostProcessError> {
   const resolved = getSsaoParameters(config);
-  if (resolved.radius <= 0) {
+  if (!Number.isFinite(resolved.radius) || resolved.radius <= 0) {
     return err(
       new PostProcessError({
         code: 'ssao-radius-non-positive',
@@ -49,7 +52,7 @@ export function resolveSsaoParameters(
       }),
     );
   }
-  if (resolved.bias < 0) {
+  if (!Number.isFinite(resolved.bias) || resolved.bias < 0) {
     return err(
       new PostProcessError({
         code: 'ssao-bias-negative',
@@ -57,5 +60,19 @@ export function resolveSsaoParameters(
       }),
     );
   }
+  if (
+    !Number.isFinite(resolved.intensity) ||
+    resolved.intensity < 0 ||
+    !Object.hasOwn(SSAO_SAMPLE_COUNTS, resolved.quality)
+  ) {
+    const paramName =
+      !Number.isFinite(resolved.intensity) || resolved.intensity < 0 ? 'intensity' : 'quality';
+    return err(
+      new PostProcessError({
+        code: 'ssao-parameter-invalid',
+        detail: { paramName, value: resolved[paramName] },
+      }),
+    );
+  }
   return ok(resolved);
 }