@forgeax/engine-render 0.1.29 → 0.1.31

package/src/assembly/recovery/renderer-recover.ts

@@ -19,7 +19,6 @@ import {
   postProcessShaderEntrySignature,
   postProcessShaderPipelineLabel,
 } from '../../fullscreen-post-process-pass';
-import { resolveStandardPbrProgram } from '../../gpu-driven/pbr-program';
 import type { PipelineState, RenderSystemInternals } from '../../record/render-context';
 import type {
   RecoveryGraphCandidate,
@@ -143,6 +142,9 @@ export interface RendererRecoveryDependencies {
   readonly getMaterialShaderPipelineEntry: NonNullable<
     RenderSystemInternals['getMaterialShaderPipelineEntry']
   >;
+  readonly getMaterialShaderArtifact: NonNullable<
+    RenderSystemInternals['getMaterialShaderArtifact']
+  >;
   readonly getCachedMaterialShaderBindingContract: NonNullable<
     RenderSystemInternals['getMaterialShaderBindingContract']
   >;
@@ -201,6 +203,7 @@ export function createRendererRecovery(deps: RendererRecoveryDependencies): Rend
     buildPipeline,
     getMaterialShaderPipeline,
     getMaterialShaderPipelineEntry,
+    getMaterialShaderArtifact,
     getCachedMaterialShaderBindingContract,
     getParamSchema,
     getMaterialBindGroupLayout,
@@ -329,6 +332,7 @@ export function createRendererRecovery(deps: RendererRecoveryDependencies): Rend
           candidateShaderCatalog.installMaterialArtifact(identifier, {
             source: entry.value.source,
             paramSchema: entry.value.paramSchema,
+            ...(entry.value.receipt === undefined ? {} : { receipt: entry.value.receipt }),
           });
         }
       }
@@ -571,14 +575,7 @@ export function createRendererRecovery(deps: RendererRecoveryDependencies): Rend
       dynamicTextureStore: { value: candidateState.dynamicTextureStore },
       getMaterialShaderPipeline: { value: getMaterialShaderPipeline },
       getMaterialShaderPipelineEntry: { value: getMaterialShaderPipelineEntry },
-      getMaterialShaderArtifact: {
-        value: (materialShaderId: string, vertexColorAvailable = false) =>
-          resolveStandardPbrProgram(
-            candidatePipelineState.gpuDrivenPbrPrograms,
-            materialShaderId,
-            vertexColorAvailable,
-          )?.artifact,
-      },
+      getMaterialShaderArtifact: { value: getMaterialShaderArtifact },
       getMaterialShaderBindingContract: { value: getCachedMaterialShaderBindingContract },
       getParamSchema: { value: getParamSchema },
       getMaterialBindGroupLayout: { value: getMaterialBindGroupLayout },

package/src/assembly/renderer-facade.ts

@@ -30,6 +30,7 @@ import type {
   RenderProfile,
   RenderResult,
 } from '../render-contract';
+import { resolveSsaoParameters } from '../ssao-config';
 import type { RendererHostImplementation } from './host-contract';
 import { createRendererLifecycle, isRendererStateOperational } from './renderer-lifecycle';
 
@@ -108,6 +109,8 @@ export function exposeRenderer(renderer: RendererHostImplementation): Renderer {
       candidate: DynamicGeometryCandidate,
       ordering: DynamicGeometryOrdering,
     ) => renderer.acceptDynamicGeometry(candidate, ordering),
+    acceptDynamicGeometryCandidates: (candidates, ordering) =>
+      renderer.acceptDynamicGeometryCandidates(candidates, ordering),
     dynamicGeometryReceipt: (candidate: DynamicGeometryCandidate) =>
       renderer.dynamicGeometryReceipt(candidate),
     cancelDynamicGeometry: (candidate: DynamicGeometryCandidate) =>
@@ -349,9 +352,26 @@ export function validateRenderProfile(profile: RenderProfile): string | undefine
   if (profile.shadows !== 'off' && profile.shadows !== 'hard' && profile.shadows !== 'filtered') {
     return "RenderProfile.shadows must be 'off', 'hard', or 'filtered'";
   }
-  for (const field of ['pbr', 'ibl', 'ssao'] as const) {
+  for (const field of ['pbr', 'ibl'] as const) {
     if (typeof profile[field] !== 'boolean') return `RenderProfile.${field} must be boolean`;
   }
+  if (
+    typeof profile.ssao !== 'boolean' &&
+    (typeof profile.ssao !== 'object' || profile.ssao === null || Array.isArray(profile.ssao))
+  )
+    return 'RenderProfile.ssao must be boolean or AO parameters';
+  if (typeof profile.ssao === 'object') {
+    if (
+      Object.keys(profile.ssao).some(
+        (key) => !['radius', 'bias', 'intensity', 'quality'].includes(key),
+      )
+    )
+      return 'RenderProfile.ssao contains an unsupported parameter';
+    const resolved = resolveSsaoParameters(profile.ssao);
+    if (!resolved.ok) return resolved.error.hint;
+  }
+  if (profile.ssao !== false && profile.renderPath !== 'deferred')
+    return 'SSAO needs current depth and normals: set renderPath to deferred';
   const stages = STANDARD_POST_STAGE_NAMES;
   if (
     !Array.isArray(profile.postStages) ||
@@ -366,6 +386,7 @@ export function validateRenderProfile(profile: RenderProfile): string | undefine
 export function freezeRenderProfile(profile: RenderProfile): RenderProfile {
   return Object.freeze({
     ...profile,
+    ssao: typeof profile.ssao === 'object' ? Object.freeze({ ...profile.ssao }) : profile.ssao,
     postStages: Object.freeze([...profile.postStages]) as RenderProfile['postStages'],
   });
 }

package/src/assembly/shader-prewarm-policy.ts

@@ -2,7 +2,13 @@ import type { Result, RhiError, ShaderModule } from '@forgeax/engine-rhi';
 import { findVariantByKey, type MaterialShaderManifestEntry } from '@forgeax/engine-shader';
 
 /** Minimum sampled-texture limit needed by Standard transmission variants. */
-export const STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES = 17;
+export const STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES = 18;
+
+function isOrdinaryMaterialVariant(
+  variant: MaterialShaderManifestEntry['variants'][number],
+): boolean {
+  return variant.defines.COVERAGE_ONLY !== true;
+}
 
 /** Select HDRP variants that must be seeded during ready-state construction. */
 export function selectHdrpPbrPrewarmVariants(
@@ -27,6 +33,7 @@ export function selectHdrpPbrPrewarmVariants(
   return (
     variants.filter(
       (variant) =>
+        isOrdinaryMaterialVariant(variant) &&
         variant.defines.STORAGE_BUFFER_AVAILABLE === storageBufferCapable &&
         (!('EXTENDED_LIGHTING_AVAILABLE' in variant.defines) ||
           variant.defines.EXTENDED_LIGHTING_AVAILABLE === extendedLightingShaderAvailable) &&
@@ -49,6 +56,7 @@ export function selectSkinPrewarmVariants(
   return (
     manifestEntry?.variants.filter(
       (variant) =>
+        isOrdinaryMaterialVariant(variant) &&
         variant.defines.STORAGE_BUFFER_AVAILABLE === storageBufferCapable &&
         (storageBufferCapable || variant.defines.CLUSTER_FORWARD_AVAILABLE !== true) &&
         variant.defines.PROBE_BLEND_AVAILABLE !== true,
@@ -70,6 +78,7 @@ export function selectGpuDrivenSceneIndexVariant(
 ): MaterialShaderManifestEntry['variants'][number] | undefined {
   return manifestEntry?.variants.find(
     (variant) =>
+      isOrdinaryMaterialVariant(variant) &&
       variant.defines.STORAGE_BUFFER_AVAILABLE === true &&
       variant.defines.GPU_DRIVEN_SCENE_INDEX_AVAILABLE === true &&
       (!('CLUSTER_FORWARD_AVAILABLE' in variant.defines) ||
@@ -83,6 +92,8 @@ export function selectGpuDrivenSceneIndexVariant(
         variant.defines.DIRECTIONAL_PCSS_AVAILABLE === directionalPcssAvailable) &&
       (!('PROJECTOR_AVAILABLE' in variant.defines) ||
         variant.defines.PROJECTOR_AVAILABLE === projectorAvailable) &&
+      (!('REFLECTION_FALLBACK_AVAILABLE' in variant.defines) ||
+        variant.defines.REFLECTION_FALLBACK_AVAILABLE === false) &&
       (!('TRANSMISSION_AVAILABLE' in variant.defines) ||
         variant.defines.TRANSMISSION_AVAILABLE === false),
   );
@@ -103,6 +114,7 @@ export function selectProbePrewarmVariants(
     manifestEntry?.variants.filter((variant) => {
       const defines = variant.defines;
       return (
+        isOrdinaryMaterialVariant(variant) &&
         defines.PROBE_BLEND_AVAILABLE === true &&
         defines.STORAGE_BUFFER_AVAILABLE === storageBufferCapable &&
         (!('WEBGL2_COMPAT' in defines) || defines.WEBGL2_COMPAT === webgl2Downlevel) &&
@@ -156,6 +168,7 @@ export function selectStandardPbrTransmissionPrewarmVariants(
   for (const transmissionAvailable of [false, true]) {
     const declared = manifestEntry.variants.find(
       (variant) =>
+        isOrdinaryMaterialVariant(variant) &&
         variant.defines.STORAGE_BUFFER_AVAILABLE === storageBufferCapable &&
         variant.defines.CLUSTER_FORWARD_AVAILABLE === standardBootClusterAxis() &&
         variant.defines.VERTEX_COLOR_AVAILABLE === false &&

package/src/assembly/webgpu-ready.ts

@@ -1,4 +1,5 @@
 import type { GpuDrivenPbrProgram } from '../gpu-driven/pbr-program';
+import { transmissionBackdropAvailable } from './device-feature-admission';
 // WebGPU generation-scoped ready-state builder.
 // This owner performs one complete device-generation promotion; it receives
 // policy/adapters and returns a fully prepared PipelineState.
@@ -225,18 +226,11 @@ export async function buildReadyWebGPU(
   setVolumetricFogShaderSources: (sources: VolumetricFogShaderSources) => void,
   /** Install manifest-owned SSR utility sources only after all five modules compile. */
   setSsrShaderSources: (sources: SsrShaderSources) => void,
-  /** Install manifest-owned atmosphere utility sources only after both modules compile. */
+  /** Install manifest-owned atmosphere utility sources only after all modules compile. */
   setAtmosphereShaderSources: (sources: AtmosphereShaderSources) => void,
 ): Promise<PipelineState> {
   const extendedLightingShaderAvailable = deriveExtendedLightingCapability(rhiDevice).admitted;
-  // bug-20260610: WebGL2 fallback path — read storage-buffer capability up
-  // front so both Step 2 (shader-module compile, where we patch engine
-  // entries to the STORAGE_BUFFER_AVAILABLE=false variant) and Step 3
-  // (buildPbrPipelineLayouts, which switches between read-only-storage
-  // and uniform BGL entries) walk the same axis. Step 0 already ran in
-  // `prepareMaterialShaders`; this is an idempotent re-read driven by
-  // `device.limits.maxStorageBuffersPerShaderStage`, which is 0 on the
-  // wgpu-wasm WebGL2 backend (downlevel_webgl2_defaults).
+  // Shader and layout construction consume the same storage capability.
   const capValue = (rhiDevice.limits as Readonly<Record<string, number>>)
     .maxStorageBuffersPerShaderStage;
   const webgl2Downlevel = rhiDevice.caps.backendKind === 'wgpu-webgl2';
@@ -386,6 +380,7 @@ export async function buildReadyWebGPU(
     let iblIrradianceEntry: ManifestEntry | undefined;
     let iblPrefilterEntry: ManifestEntry | undefined;
     let iblBrdfLutEntry: ManifestEntry | undefined;
+    let probeBackgroundEntry: ManifestEntry | undefined;
     let fxaaEntry: ManifestEntry | undefined;
     let skyboxEntry: ManifestEntry | undefined;
     let bloomBrightEntry: ManifestEntry | undefined;
@@ -441,6 +436,10 @@ export async function buildReadyWebGPU(
         iblBrdfLutEntry ??= entry;
         continue;
       }
+      if (entry.wgsl.includes('probe_background_fs')) {
+        probeBackgroundEntry ??= entry;
+        continue;
+      }
       if (entry.wgsl.includes('f_schlick')) {
         pbrEntry ??= entry;
         continue;
@@ -522,6 +521,7 @@ export async function buildReadyWebGPU(
         const exact = ms.variants.find(
           (v) =>
             v.defines.STORAGE_BUFFER_AVAILABLE === false &&
+            v.defines.COVERAGE_ONLY !== true &&
             (!('CLUSTER_FORWARD_AVAILABLE' in v.defines) ||
               v.defines.CLUSTER_FORWARD_AVAILABLE === false) &&
             (!('VERTEX_COLOR_AVAILABLE' in v.defines) ||
@@ -564,6 +564,7 @@ export async function buildReadyWebGPU(
       const exact = ms.variants.find(
         (variant) =>
           variant.defines.STORAGE_BUFFER_AVAILABLE === storageBufferCapable &&
+          variant.defines.COVERAGE_ONLY !== true &&
           (!('CLUSTER_FORWARD_AVAILABLE' in variant.defines) ||
             variant.defines.CLUSTER_FORWARD_AVAILABLE === false) &&
           (!('VERTEX_COLOR_AVAILABLE' in variant.defines) ||
@@ -642,13 +643,7 @@ export async function buildReadyWebGPU(
         }
       }
     }
-    // Wire composed IBL shaders into IblPipelineCache before the cache's
-    // createIblPipelines runs (called downstream by the internal
-    // GpuResidencyCache equirect-to-cubemap projection during the first Skylight
-    // dispatch). When all 4 are present, register them; otherwise leave
-    // the cache untouched (charter F1: tests / non-IBL hosts that ship
-    // empty / 3-entry manifests still boot, and the IBL pipeline cache's
-    // own error surfacing covers the "missing" case downstream).
+    // Publish the generation's compiled IBL programs before resource preparation.
     if (
       iblEquirectEntry !== undefined &&
       iblIrradianceEntry !== undefined &&
@@ -660,6 +655,9 @@ export async function buildReadyWebGPU(
         irradiance: iblIrradianceEntry.wgsl,
         prefilter: iblPrefilterEntry.wgsl,
         brdfLut: iblBrdfLutEntry.wgsl,
+        ...(probeBackgroundEntry === undefined
+          ? {}
+          : { probeBackground: probeBackgroundEntry.wgsl }),
       });
     }
     // Points/Lines are an engine-owned record path rather than a producer
@@ -986,7 +984,8 @@ export async function buildReadyWebGPU(
     const coloredUnlitVariant = unlitManifestEntry?.variants.find(
       (variant) =>
         variant.defines.VERTEX_COLOR_AVAILABLE === true &&
-        variant.defines.STORAGE_BUFFER_AVAILABLE === storageBufferCapable,
+        variant.defines.STORAGE_BUFFER_AVAILABLE === storageBufferCapable &&
+        variant.defines.COVERAGE_ONLY !== true,
     );
     if (coloredUnlitVariant !== undefined && coloredUnlitVariant.composedWgsl !== unlitEntry.wgsl) {
       const coloredUnlitShaderResult = await runShimStep(
@@ -1013,7 +1012,8 @@ export async function buildReadyWebGPU(
     const uncoloredUnlitVariant = unlitManifestEntry?.variants.find(
       (variant) =>
         variant.defines.VERTEX_COLOR_AVAILABLE === false &&
-        variant.defines.STORAGE_BUFFER_AVAILABLE === storageBufferCapable,
+        variant.defines.STORAGE_BUFFER_AVAILABLE === storageBufferCapable &&
+        variant.defines.COVERAGE_ONLY !== true,
     );
     if (uncoloredUnlitVariant !== undefined) {
       seedShaderModule(
@@ -1411,7 +1411,10 @@ export async function buildReadyWebGPU(
     // feat-20260612-hdrp-ssao M6 / w27: SSAO shader module compilation.
     // Optional manifest entry — absent on legacy manifests (zero-overhead
     // opt-out, same as bloom). Identified by 'fs_ssao_calc' content marker.
-    if (ssaoEntry !== undefined) {
+    // The GLES translator cannot read raw depth through this SSAO program.
+    // Keep optional AO out of fallback startup; requesting it is refused by
+    // the record owner instead of breaking every AO-disabled renderer.
+    if (ssaoEntry !== undefined && !webgl2Downlevel) {
       const entry = ssaoEntry;
       const ssaoShaderResult = await runShimStep(
         () =>
@@ -1460,6 +1463,9 @@ export async function buildReadyWebGPU(
           storageBuffer: storageBufferCapable,
           extendedLighting: extendedLightingShaderAvailable,
           projectorAvailable,
+          transmissionBackdrop: transmissionBackdropAvailable(
+            rhiDevice.limits.maxSampledTexturesPerShaderStage,
+          ),
         }),
       ),
     'webgpu-runtime-error',
@@ -1485,6 +1491,7 @@ export async function buildReadyWebGPU(
   // (URP layout) so the manifest entry's URP variant WGSL still builds a
   // valid PSO instead of hard-disabling the entire HDRP-variant build path.
   let hdrpPbrPipelineLayoutHandle: PipelineLayout | null = null;
+  let hdrpMeshBindGroupLayoutHandle: BindGroupLayout | null = null;
   let hdrpProbePbrPipelineLayoutHandle: PipelineLayout | null = null;
   // The cluster layout is storage-buffer backed. On the WebGL2/fallback
   // capability tier its uniform-buffer projection exceeds the backend's
@@ -1493,6 +1500,7 @@ export async function buildReadyWebGPU(
     const hdrpUnifiedBglDesc = createHdrpBindGroupLayoutDescriptor();
     const hdrpUnifiedBglRes = rhiDevice.createBindGroupLayout(hdrpUnifiedBglDesc);
     if (hdrpUnifiedBglRes.ok) {
+      hdrpMeshBindGroupLayoutHandle = hdrpUnifiedBglRes.value;
       const hdrpPlRes = rhiDevice.createPipelineLayout({
         label: 'hdrp-pbr-pl',
         bindGroupLayouts: [
@@ -3919,6 +3927,7 @@ export async function buildReadyWebGPU(
     // HDRP variant uses the unified group(2) layout built above.
     hdrpPbrPipelineLayout:
       unlitModule !== null && pbrModule !== null ? hdrpPbrPipelineLayoutHandle : null,
+    hdrpMeshBindGroupLayout: hdrpMeshBindGroupLayoutHandle,
     hdrpProbePbrPipelineLayout:
       unlitModule !== null && pbrModule !== null ? hdrpProbePbrPipelineLayoutHandle : null,
     hdrpClusterMembershipPipeline,