@forgeax/engine-render 0.1.29 → 0.1.31

package/src/record/main-pass-material.ts

@@ -1,3 +1,4 @@
+import { transmissionBackdropAvailable } from '../assembly/device-feature-admission';
 import { getOrCreateIblCache } from '../ibl/IblPipelineCache';
 import type { _InternalRenderPipelineContext } from './render-context';
 // @forgeax/engine-runtime - RenderSystem record stage: main-pass-material.
@@ -947,7 +948,7 @@ export interface PerSubmeshMaterialBgDeps {
   readonly resolveReflectionProbeResources?: (
     materialWorld: World,
     entityKey: number,
-  ) => SkylightBindGroupResources | undefined;
+  ) => { readonly resources: SkylightBindGroupResources; readonly probeIndex: number } | undefined;
   readonly materialBgShared: Map<string, WeakMap<object, unknown>>;
   /** Cross-frame final BG reuse keyed by the stable source material handle. */
   readonly materialBgAssemblyCache: Map<string, MaterialBgAssemblyCacheEntry>;
@@ -1007,6 +1008,7 @@ export function isMaterialBgAssemblyCacheHit(
   skylightResources: SkylightBindGroupResources,
   materialResourceEpoch: number,
   transmissionBackdropView?: TextureView | null,
+  sceneMaterialBuffer?: Buffer,
 ): cached is MaterialBgAssemblyCacheEntry {
   if (transmissionBackdropView != null) return false;
   return (
@@ -1014,9 +1016,11 @@ export function isMaterialBgAssemblyCacheHit(
     cached.materialResourceEpoch === materialResourceEpoch &&
     cached.materialBgl === materialBgl &&
     cached.materialBuffer === materialBuffer &&
+    cached.sceneMaterialBuffer === sceneMaterialBuffer &&
     cached.skylightResources.irradianceView === skylightResources.irradianceView &&
     cached.skylightResources.irradianceSampler === skylightResources.irradianceSampler &&
     cached.skylightResources.prefilterView === skylightResources.prefilterView &&
+    cached.skylightResources.skylightPrefilterView === skylightResources.skylightPrefilterView &&
     cached.skylightResources.prefilterSampler === skylightResources.prefilterSampler &&
     cached.skylightResources.brdfLutView === skylightResources.brdfLutView &&
     cached.skylightResources.brdfLutSampler === skylightResources.brdfLutSampler &&
@@ -1046,13 +1050,13 @@ export function buildPerSubmeshMaterialBg(
     bindGroupCounts,
     frameState,
   } = deps;
-  const effectiveSkylightResources =
-    resolveReflectionProbeResources?.(materialWorld, entityKey) ?? skylightResources;
+  const selectedProbe = resolveReflectionProbeResources?.(materialWorld, entityKey);
+  const effectiveSkylightResources = selectedProbe?.resources ?? skylightResources;
   const smMaterialHandle = submeshMaterial.materialHandle;
   const materialCacheKey =
     smMaterialHandle === undefined
       ? undefined
-      : `${materialWorld.identity}:${smMaterialHandle}:${materialShaderId ?? ''}`;
+      : `${materialWorld.identity}:${smMaterialHandle}:${materialShaderId ?? ''}:${selectedProbe?.probeIndex ?? 'sky'}`;
   const smHasVideoFields = (submeshMaterial.videoTextureFields?.size ?? 0) > 0;
   const smShaderId = materialShaderId;
   // The cooked shader schema owns the resource ABI. A material snapshot may
@@ -1079,6 +1083,9 @@ export function buildPerSubmeshMaterialBg(
       ? BUILTIN_USER_REGION_TEXTURE_FIELDS
       : userRegionTextureFieldOrder(smSchema).filter((field) => !physicalFields.includes(field));
   const hasActiveTransmissionBackdrop = transmissionBackdropView != null;
+  const sceneMaterialBuffer = runtime.device.caps.storageBuffer
+    ? (deps.sceneMaterialBuffer ?? pipelineState.meshStorageBuffer.buffer)
+    : undefined;
   const diagnosticsEnabled = materialDiagnosticsEnabled();
   if (smMaterialHandle !== undefined && !smHasVideoFields && !hasActiveTransmissionBackdrop) {
     const cached =
@@ -1092,8 +1099,8 @@ export function buildPerSubmeshMaterialBg(
         effectiveSkylightResources,
         store.materialResourceEpoch,
         transmissionBackdropView,
-      ) &&
-      deps.sceneMaterialBuffer === undefined
+        sceneMaterialBuffer,
+      )
     ) {
       if (diagnosticsEnabled) {
         recordIblMaterialBinding(
@@ -1103,31 +1110,34 @@ export function buildPerSubmeshMaterialBg(
           [
             {
               binding: 1 + smUserRegionFields.length * 2,
-              resource: { kind: 'textureView', value: skylightResources.irradianceView },
+              resource: { kind: 'textureView', value: effectiveSkylightResources.irradianceView },
             },
             {
               binding: 2 + smUserRegionFields.length * 2,
-              resource: { kind: 'sampler', value: skylightResources.irradianceSampler },
+              resource: { kind: 'sampler', value: effectiveSkylightResources.irradianceSampler },
             },
             {
               binding: 3 + smUserRegionFields.length * 2,
-              resource: { kind: 'textureView', value: skylightResources.prefilterView },
+              resource: { kind: 'textureView', value: effectiveSkylightResources.prefilterView },
             },
             {
               binding: 4 + smUserRegionFields.length * 2,
-              resource: { kind: 'sampler', value: skylightResources.prefilterSampler },
+              resource: { kind: 'sampler', value: effectiveSkylightResources.prefilterSampler },
             },
             {
               binding: 5 + smUserRegionFields.length * 2,
-              resource: { kind: 'textureView', value: skylightResources.brdfLutView },
+              resource: { kind: 'textureView', value: effectiveSkylightResources.brdfLutView },
             },
             {
               binding: 6 + smUserRegionFields.length * 2,
-              resource: { kind: 'sampler', value: skylightResources.brdfLutSampler },
+              resource: { kind: 'sampler', value: effectiveSkylightResources.brdfLutSampler },
             },
             {
               binding: 7 + smUserRegionFields.length * 2,
-              resource: { kind: 'buffer', value: { buffer: skylightResources.intensityBuffer } },
+              resource: {
+                kind: 'buffer',
+                value: { buffer: effectiveSkylightResources.intensityBuffer },
+              },
             },
           ],
           1 + smUserRegionFields.length * 2,
@@ -1264,10 +1274,14 @@ export function buildPerSubmeshMaterialBg(
   const smMergedEntries = assembleMaterialWithSkylightEntries(
     smBaseEntries,
     effectiveSkylightResources,
-    {
-      sampler: transmissionSampler,
-      ...(transmissionBackdropView === undefined ? {} : { backdropView: transmissionBackdropView }),
-    } satisfies TransmissionBindGroupResources,
+    transmissionBackdropAvailable(runtime.device.limits.maxSampledTexturesPerShaderStage)
+      ? ({
+          sampler: transmissionSampler,
+          ...(transmissionBackdropView === undefined
+            ? {}
+            : { backdropView: transmissionBackdropView }),
+        } satisfies TransmissionBindGroupResources)
+      : null,
     physicalTextureInjections,
   );
   // Storage-capable devices share one Standard material BGL with the
@@ -1354,7 +1368,6 @@ export function buildPerSubmeshMaterialBg(
     smMaterialHandle !== undefined &&
     !smHasVideoFields &&
     materialResourcesResident &&
-    deps.sceneMaterialBuffer === undefined &&
     !hasActiveTransmissionBackdrop
   ) {
     if (materialCacheKey !== undefined) {
@@ -1363,6 +1376,7 @@ export function buildPerSubmeshMaterialBg(
         materialResourceEpoch: store.materialResourceEpoch,
         materialBgl: smMaterialBgl,
         materialBuffer: pipelineState.materialUniformBuffer.buffer,
+        ...(sceneMaterialBuffer === undefined ? {} : { sceneMaterialBuffer }),
         skylightResources: effectiveSkylightResources,
         bindGroup: smBindGroup,
       });
@@ -1387,6 +1401,7 @@ export function resolveMaterialSkylight(
   pipelineState: Pick<PipelineState, 'skylightFallback'>,
   skylight: SkylightSnapshot | undefined,
   skylightCount: number,
+  environmentIbl?: _InternalRenderPipelineContext['environmentIbl'],
 ) {
   const skylightFallback = pipelineState.skylightFallback;
   if (skylightFallback === null) {
@@ -1440,6 +1455,13 @@ export function resolveMaterialSkylight(
       };
     }
   }
+  if (environmentIbl !== undefined && skylight !== undefined && skylight.equirectHandle === 0) {
+    activeViews = {
+      irr: environmentIbl.irradiance,
+      pref: environmentIbl.prefilter,
+      brdf: activeViews?.brdf ?? skylightFallback.brdfLutView,
+    };
+  }
   const skylightResources =
     activeViews !== undefined
       ? {
@@ -1465,5 +1487,11 @@ export function resolveMaterialSkylight(
 
 /** The same scene resources back material bindings in depth and color passes. */
 export function prepareMaterialSkylight(c: _InternalRenderPipelineContext) {
-  return resolveMaterialSkylight(c.runtime, c.pipelineState, c.skylight, c.skylightCount);
+  return resolveMaterialSkylight(
+    c.runtime,
+    c.pipelineState,
+    c.skylight,
+    c.skylightCount,
+    c.environmentIbl,
+  );
 }

package/src/record/main-pass.ts

@@ -8,7 +8,11 @@ import {
   type TextureView,
 } from '@forgeax/engine-rhi';
 import type { PassKind, PassSelector } from '@forgeax/engine-types';
-import { createHdrpUnifiedBindGroup, getOrCreateHdrpBuffers } from '../hdrp-buffers';
+import {
+  createGpuDrivenLightingBindGroup,
+  createHdrpUnifiedBindGroup,
+  getOrCreateHdrpBuffers,
+} from '../hdrp-buffers';
 import { getOrCreateIblCache } from '../ibl/IblPipelineCache';
 import type { SkylightBindGroupResources } from '../ibl/skylight-bind-group';
 import { buildBeginRenderPassDescriptor, standardTopologyBindGroupReady } from '../pipeline-spec';
@@ -67,6 +71,8 @@ export type MainPassOptions = {
   /** Require the same material to contribute to another graph lane. */
   readonly includeSelector?: PassSelector;
   readonly transmissionBackdropView?: TextureView | null;
+  /** Select the material temporal entry's binary coverage output. */
+  readonly coverageOnly?: boolean;
   readonly gpuDriven?: {
     readonly projection: RenderPipelineGpuDrivenProjection;
     readonly resources: GraphResourceResolver;
@@ -469,6 +475,13 @@ export function recordMainPass(
     // which cannot render a PBR decal). Captures only frame-stable closure
     // state; the caller passes the per-submesh material snapshot + entityKey
     // (for video texture routing) and sets the dynamic UBO offset itself.
+    // Selection keys use the extracted frame index, never World.identity.
+    const hasProbeBindings = (c.reflectionProbes?.table.rows.length ?? 0) > 0;
+    const worldIndices = hasProbeBindings
+      ? new Map(
+          validatedOrdered.map((entry) => [entry.world ?? world, entry.source.worldId] as const),
+        )
+      : undefined;
     const perSubmeshMaterialBgDeps: PerSubmeshMaterialBgDeps = {
       runtime,
       pipelineState,
@@ -480,8 +493,10 @@ export function recordMainPass(
       resolveRenderTargetTextureSource: runtime.resolveRenderTargetTextureSource,
       resolveReflectionProbeResources: (materialWorld, entityKey) => {
         const reflectionProbes = c.reflectionProbes;
-        if (reflectionProbes === undefined) return undefined;
-        const selection = reflectionProbes.selections.get(`${materialWorld.identity}:${entityKey}`);
+        if (reflectionProbes === undefined || !hasProbeBindings) return undefined;
+        const selection = reflectionProbes.selections.get(
+          `${worldIndices?.get(materialWorld)}:${entityKey}`,
+        );
         if (selection === undefined) return undefined;
         const binding = resolveReflectionProbeBinding(selection, reflectionProbes.table);
         if (binding.useSkylight || binding.probeIndex === undefined) return undefined;
@@ -499,12 +514,13 @@ export function recordMainPass(
           irradianceView: skylightResources.irradianceView,
           irradianceSampler: skylightResources.irradianceSampler,
           prefilterView: row.filteredView,
+          skylightPrefilterView: skylightResources.prefilterView,
           prefilterSampler: row.sampler,
           brdfLutView: skylightResources.brdfLutView,
           brdfLutSampler: skylightResources.brdfLutSampler,
           intensityBuffer: row.uniformBuffer,
         };
-        return probeResources;
+        return { resources: probeResources, probeIndex: row.index };
       },
       materialBgShared: frameState.materialBgShared,
       materialBgAssemblyCache: c.materialBgAssemblyCache,
@@ -551,12 +567,53 @@ export function recordMainPass(
       );
     }
     if (gpuDrivenStandardPbrFrameResources !== undefined) {
+      gpuDrivenStandardPbrFrameResources.resolveClusteredMeshBindGroup = (binding) => {
+        const buffers = getOrCreateHdrpBuffers(
+          runtime,
+          frameState.installedPipelineConfig?.clusterGrid,
+        );
+        const layout =
+          binding.paletteBuffer === undefined
+            ? pipelineState.hdrpMeshBindGroupLayout
+            : pipelineState.hdrpSkinMeshBindGroupLayout;
+        const group =
+          buffers === null || layout == null
+            ? null
+            : createGpuDrivenLightingBindGroup(
+                runtime,
+                buffers,
+                layout,
+                binding,
+                c.hdrpSsaoBlurredView,
+              );
+        if (group === null)
+          throw new RhiError({
+            code: 'rhi-not-available',
+            expected: 'scene-index clustered lighting binding',
+            hint: 'publish scene rows and the current lighting/AO resources before indirect drawing',
+          });
+        return group;
+      };
       gpuDrivenStandardPbrFrameResources.materialBindGroups.length = 0;
       gpuDrivenStandardPbrFrameResources.materialBindGroups.push(...preparedMaterialBindGroups);
+      gpuDrivenStandardPbrFrameResources.colorFormats = colorFormats;
+      const selectedMaterialSlots = new Set<number>();
+      if (matchedMaterials === null)
+        delete gpuDrivenStandardPbrFrameResources.selectedMaterialSlots;
+      else gpuDrivenStandardPbrFrameResources.selectedMaterialSlots = selectedMaterialSlots;
       gpuDrivenStandardPbrFrameResources.materialSlotIndicesByEntity.clear();
       for (let index = 0; index < validatedOrdered.length; index += 1) {
         const entry = validatedOrdered[index];
         if (entry === undefined) continue;
+        const selected = matchedMaterials?.get(entry.renderableIndex);
+        const materials =
+          entry.source.materials.length > 0 ? entry.source.materials : [entry.source.material];
+        for (let slot = 0; slot < materials.length; slot += 1) {
+          const handle = materials[slot]?.materialHandle ?? -1;
+          const globalSlot = materialSlotIndices[index]?.[slot];
+          if (globalSlot !== undefined && selected?.has(handle))
+            selectedMaterialSlots.add(globalSlot);
+        }
         gpuDrivenStandardPbrFrameResources.materialSlotIndicesByEntity.set(
           worldEntityKey(entry.source.worldId, entry.source.entityKey),
           materialSlotIndices[index] ?? [],
@@ -570,6 +627,7 @@ export function recordMainPass(
       materialWorld: World = world,
       materialShaderId: string | undefined = material.materialShaderId,
     ): BindGroup =>
+      !hasProbeBindings &&
       materialShaderId === material.materialShaderId &&
       materialShaderId !== POINTS_LINES_MATERIAL_SHADER_ID
         ? (preparedMaterialBindGroups[materialSlot] ??
@@ -597,6 +655,7 @@ export function recordMainPass(
         passKind,
         selectedDispatch,
         colorFormats,
+        options?.coverageOnly ?? false,
       );
     };
     if (c.profilePhase === undefined) {

package/src/record/prepared-material-bindings.ts

@@ -10,6 +10,7 @@ import {
   materialValuesToLinearRuntime,
   type SamplerAsset,
 } from '@forgeax/engine-types';
+import { transmissionBackdropAvailable } from '../assembly/device-feature-admission';
 import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_UNIFORM } from '../gpu-usage';
 import type { SkylightBindGroupResources } from '../ibl/skylight-bind-group';
 import { assembleMaterialWithSkylightEntries } from '../ibl/skylight-bind-group';
@@ -205,6 +206,9 @@ export function preparedMaterialBindings(
       brdfLutSampler: fallback.sampler,
       intensityBuffer: fallback.intensityBuffer,
     },
+    transmissionBackdropAvailable(runtime.device.limits.maxSampledTexturesPerShaderStage)
+      ? undefined
+      : null,
   );
   // Per-shader PBR layouts reserve the scene-material SSBO at binding 46 on
   // storage-capable devices. Prepared feature materials use this same layout,

package/src/record/recovery-pipeline.ts

@@ -31,6 +31,7 @@ import { geometryRenderStateForTopology } from './main-pass-material';
 import type {
   MaterialShaderPipelineEntry,
   PipelineState,
+  RecoveryColdWorkGuard,
   RenderSystemInternals,
 } from './render-context';
 
@@ -38,6 +39,60 @@ export interface RecoveryPipelineReadiness {
   readonly pipelineSpecs: readonly PipelineSpec[];
   /** Re-resolve every candidate request and assert a stable cache hit. */
   readonly assertPreparedCache: () => void;
+  readonly assertFirstRecoveryFrame: () => void;
+}
+
+/**
+ * Create the one-shot assertion used by the first frame after publication.
+ * Recording a miss is a failure at the owner seam; the draw path never gets a
+ * chance to submit a frame that hides a shader/pipeline or static-residency
+ * cold build behind an apparently successful receipt.
+ */
+export function createRecoveryColdWorkGuard(): RecoveryColdWorkGuard {
+  let armed = false;
+  let recording = false;
+  let finished = false;
+  let pipelineColdWork = 0;
+  let uploadColdWork = 0;
+  const fail = (kind: 'pipeline' | 'upload'): never => {
+    if (kind === 'pipeline') pipelineColdWork += 1;
+    else uploadColdWork += 1;
+    throw new Error(
+      `recovery first frame performed cold ${kind} work ` +
+        `(pipeline=${pipelineColdWork}, upload=${uploadColdWork})`,
+    );
+  };
+  return {
+    arm(): void {
+      armed = true;
+      finished = false;
+      pipelineColdWork = 0;
+      uploadColdWork = 0;
+    },
+    beginFrame(): void {
+      recording = true;
+    },
+    endFrame(): void {
+      recording = false;
+    },
+    notePipelineColdWork(): void {
+      if (armed && recording && !finished) fail('pipeline');
+    },
+    noteUploadColdWork(): void {
+      if (armed && recording && !finished) fail('upload');
+    },
+    finish(): void {
+      if (!armed || finished) return;
+      finished = true;
+      armed = false;
+      if (pipelineColdWork !== 0 || uploadColdWork !== 0) {
+        throw new Error(
+          `recovery first frame cold-work assertion failed ` +
+            `(pipeline=${pipelineColdWork}, upload=${uploadColdWork})`,
+        );
+      }
+    },
+  };
 }
 
 interface RecoveryPipelineRequest {
@@ -614,5 +669,6 @@ export function prepareRecoveryPipelineReadiness(input: {
   return {
     pipelineSpecs: Object.freeze(requests.map((request) => request.spec)),
     assertPreparedCache,
+    assertFirstRecoveryFrame: assertPreparedCache,
   };
 }

package/src/record/render-context.ts

@@ -88,7 +88,7 @@ export interface ReflectionProbeRecordState {
   >;
   /** Demand is derived from this frame's renderable/source selection. */
   readonly fallbackDemand?: boolean;
-  /** True when at least one selected row must prove a non-zero readback. */
+  /** Non-neutral sources require a nonzero diagnostic sample when capture is enabled. */
   readonly fallbackHasNonNeutral?: boolean;
   readonly completeSubmission: (
     submitted: boolean,
@@ -144,6 +144,22 @@ import type {
 } from './frame-snapshot';
 import type { FoldDispatchPlan } from './mesh-ssbo';
 
+/**
+ * Armed only for the first published recovery frame. Candidate preparation
+ * must make every pipeline and static residency lookup a cache hit before this
+ * guard is armed; a miss during draw is a hard failure before queue submission.
+ * Explicit preparation between draws remains allowed, including new geometry
+ * admitted on the first fixed step after device recovery.
+ */
+export interface RecoveryColdWorkGuard {
+  arm(): void;
+  beginFrame(): void;
+  endFrame(): void;
+  notePipelineColdWork(): void;
+  noteUploadColdWork(): void;
+  finish(): void;
+}
+
 export interface RenderSystemRuntime {
   readonly device: RhiDevice;
   /** Current renderer device generation used to fence receipt-bound captures. */
@@ -178,7 +194,16 @@ export interface RenderSystemRuntime {
   /** Producer-owned cooked Standard PBR artifact used by GPU-driven projection. */
   readonly getMaterialShaderArtifact?: (
     materialShaderId: string,
-    vertexColorAvailable?: boolean,
+    request?:
+      | {
+          readonly vertexColorAvailable?: boolean;
+          readonly deformation?: 'rigid' | 'skin';
+          readonly clustered?: boolean;
+          readonly reflectionFallback?: boolean;
+          readonly pass?: 'forward' | 'shadow' | 'depth';
+          readonly address?: 'direct' | 'scene-index';
+        }
+      | boolean,
   ) => MaterialShaderArtifact | undefined;
   readonly getMaterialShaderPipeline?: (
     materialShaderId: string,
@@ -221,7 +246,7 @@ export interface RenderSystemRuntime {
     vertexLayout?: string,
     vertexLayoutProjection?: VertexLayoutProjection,
     shaderModuleMode?: RenderFeatureShaderModuleMode,
-    layoutKindOverride?: 'pbr' | 'pbr-skin',
+    layoutKindOverride?: 'pbr' | 'pbr-skin' | 'gpu-driven-pbr' | 'gpu-driven-skin',
     /** Optional vertex entry override for receipt-owned scene-index passes. */
     vertexEntryPoint?: string,
     additionalColorFormats?: readonly GPUTextureFormat[],
@@ -249,6 +274,8 @@ export interface RenderSystemRuntime {
   ) => BindGroupLayout | undefined;
   /** Handle-first factory for built-in same-frame GPU producers. */
   readonly immediateShaderModuleFactory?: PipelineBuilderShaderModuleFactory;
+  /** Optional guard for the first recovery frame's cold-work boundary. */
+  readonly recoveryColdWorkGuard?: RecoveryColdWorkGuard | undefined;
   readonly metrics: EngineMetrics;
   readonly lookupPostProcess?: (
     id: string,
@@ -422,6 +449,7 @@ export interface PipelineState {
   readonly gpuDrivenPbrSkinPipelineLayout?: PipelineLayout | null;
   readonly pbrProbePipelineLayout?: PipelineLayout | null;
   readonly hdrpPbrPipelineLayout: PipelineLayout | null;
+  readonly hdrpMeshBindGroupLayout?: BindGroupLayout | null;
   readonly hdrpProbePbrPipelineLayout?: PipelineLayout | null;
   readonly hdrpClusterMembershipPipeline: ComputePipeline | null;
   readonly hdrpClusterMembershipBindGroupLayout: BindGroupLayout | null;
@@ -462,6 +490,7 @@ export interface RenderSystemInternals extends RenderSystemRuntime {
   readonly build?: string | undefined;
   /** Host identity binding for the renderer-owned SSR dependency seam. */
   readonly ssrIdentity?: SsrAdmissionIdentity | undefined;
+  readonly captureReflectionFallbackReadback?: boolean | undefined;
   readonly standardProfile?: StandardProfile | undefined;
   readonly standardPipeline: RenderFrameState['activePipeline'];
   readonly featureHost?: RenderFeatureHost | undefined;
@@ -518,6 +547,8 @@ export interface RenderSystemInternals extends RenderSystemRuntime {
 }
 
 export interface _StandardForwardSceneView {
+  readonly environmentIbl?: { readonly irradiance: TextureView; readonly prefilter: TextureView };
+  readonly captureDispatch?: readonly DispatchEntry[];
   readonly assets: AssetRegistry;
   readonly store: import('../device/gpu-residency').GpuResidencyCache;
   readonly pipelineState: PipelineState;