@forgeax/engine-render 0.1.33 → 0.1.34

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

@@ -42,6 +42,7 @@ import { VideoUploadUnsupportedError } from '../errors/render';
 import {
   assembleMaterialWithSkylightEntries,
   type SkylightBindGroupResources,
+  type SurfaceMediumBindGroupResources,
   type TextureInjectionResource,
   type TransmissionBindGroupResources,
 } from '../ibl/skylight-bind-group';
@@ -956,6 +957,12 @@ export interface PerSubmeshMaterialBgDeps {
   readonly sceneMaterialBuffer?: Buffer;
   /** Active transmission backdrop; undefined/null means layout placeholder. */
   readonly transmissionBackdropView?: TextureView | null;
+  /** Independent sampled raw depth for the active medium graph pass. */
+  readonly surfaceRawDepthView?: TextureView | null;
+  /** Nearest-layer color from the preceding medium graph pass. */
+  readonly surfaceNearestLayerView?: TextureView | null;
+  /** Nearest-layer depth from the preceding medium graph pass. */
+  readonly surfaceNearestDepthView?: TextureView | null;
   readonly bindGroupCounts: BindGroupCounts;
   readonly frameState: RenderFrameState;
 }
@@ -1009,8 +1016,9 @@ export function isMaterialBgAssemblyCacheHit(
   materialResourceEpoch: number,
   transmissionBackdropView?: TextureView | null,
   sceneMaterialBuffer?: Buffer,
+  surfaceRawDepthView?: TextureView | null,
 ): cached is MaterialBgAssemblyCacheEntry {
-  if (transmissionBackdropView != null) return false;
+  if (transmissionBackdropView != null || surfaceRawDepthView != null) return false;
   return (
     cached?.material === material &&
     cached.materialResourceEpoch === materialResourceEpoch &&
@@ -1047,6 +1055,9 @@ export function buildPerSubmeshMaterialBg(
     materialBgShared,
     materialBgAssemblyCache,
     transmissionBackdropView,
+    surfaceRawDepthView,
+    surfaceNearestLayerView,
+    surfaceNearestDepthView,
     bindGroupCounts,
     frameState,
   } = deps;
@@ -1059,6 +1070,39 @@ export function buildPerSubmeshMaterialBg(
       : `${materialWorld.identity}:${smMaterialHandle}:${materialShaderId ?? ''}:${selectedProbe?.probeIndex ?? 'sky'}`;
   const smHasVideoFields = (submeshMaterial.videoTextureFields?.size ?? 0) > 0;
   const smShaderId = materialShaderId;
+  const selectedMaterialShaderArtifact =
+    smShaderId === undefined ? undefined : runtime.getMaterialShaderArtifact?.(smShaderId);
+  const selectedMediumShader =
+    smShaderId === 'forgeax::single-layer-medium' ||
+    selectedMaterialShaderArtifact?.receipt?.surface?.model === 'single-layer-medium';
+  let surfaceMediumResources: SurfaceMediumBindGroupResources | undefined;
+  if (selectedMediumShader) {
+    if (surfaceRawDepthView == null) {
+      throw new RhiError({
+        code: 'rhi-descriptor-invalid',
+        expected: 'single-layer medium material bind group has producer-owned raw depth',
+        hint: 'admit the Surface material only from a graph pass with an available raw-depth pair',
+      });
+    }
+    const nearestLayerView = surfaceNearestLayerView ?? transmissionBackdropView;
+    const nearestDepthView = surfaceNearestDepthView ?? pipelineState.shadowFallbackTextureView;
+    if (nearestLayerView == null || pipelineState.surfaceMediumDepthSampler === undefined) {
+      throw new RhiError({
+        code: 'rhi-descriptor-invalid',
+        expected:
+          'single-layer medium material bind group has paired nearest resources and depth sampler',
+        hint: 'publish the nearest-layer target and the non-filtering raw-depth sampler before recording the Surface pass',
+      });
+    }
+    surfaceMediumResources = {
+      rawDepthSampler: pipelineState.surfaceMediumDepthSampler,
+      rawDepthView: surfaceRawDepthView,
+      nearestLayerSampler: effectiveSkylightResources.prefilterSampler,
+      nearestLayerView,
+      nearestDepthSampler: pipelineState.surfaceMediumDepthSampler,
+      nearestDepthView,
+    };
+  }
   // The cooked shader schema owns the resource ABI. A material snapshot may
   // carry only the authored values (for example a clearcoat-only root omits
   // the standard emissive/occlusion maps), while the Standard template still
@@ -1100,6 +1144,7 @@ export function buildPerSubmeshMaterialBg(
         store.materialResourceEpoch,
         transmissionBackdropView,
         sceneMaterialBuffer,
+        surfaceRawDepthView,
       )
     ) {
       if (diagnosticsEnabled) {
@@ -1232,7 +1277,7 @@ export function buildPerSubmeshMaterialBg(
   // Physical Standard maps are deliberately appended after the stable IBL /
   // transmission tail.  Keep their resource projection separate from the
   // user-region loop so the slot order is the same as
-  // `appendTextureInjection(afterTransmission, physicalFields)` in the
+  // `appendTextureInjection(afterSurfaceMedium, physicalFields)` in the
   // layout owner.
   const physicalTextureInjections: TextureInjectionResource[] = [];
   for (let slot = 0; slot < physicalFields.length; slot += 1) {
@@ -1271,18 +1316,27 @@ export function buildPerSubmeshMaterialBg(
     transmissionBackdropView != null
       ? effectiveSkylightResources.prefilterSampler
       : pipelineState.defaultSampler;
+  // The medium shader keeps the transmission backdrop pair in its fixed
+  // group(1) ABI even on a device that cannot admit the ordinary Standard
+  // transmission topology. Its Surface resources start at binding 10, so
+  // retain a real backdrop pair here whenever the medium resources exist;
+  // otherwise the raw-depth view would slide into binding 9 and Dawn would
+  // reject the unfilterable r32float view as a filtering float texture.
+  const keepMediumBackdropSlots = surfaceMediumResources !== undefined;
   const smMergedEntries = assembleMaterialWithSkylightEntries(
     smBaseEntries,
     effectiveSkylightResources,
-    transmissionBackdropAvailable(runtime.device.limits.maxSampledTexturesPerShaderStage)
+    transmissionBackdropAvailable(runtime.device.limits.maxSampledTexturesPerShaderStage) ||
+      keepMediumBackdropSlots
       ? ({
           sampler: transmissionSampler,
           ...(transmissionBackdropView === undefined
-            ? {}
+            ? { backdropView: pipelineState.defaultWhiteTextureView }
             : { backdropView: transmissionBackdropView }),
         } satisfies TransmissionBindGroupResources)
       : null,
     physicalTextureInjections,
+    surfaceMediumResources,
   );
   // Storage-capable devices share one Standard material BGL with the
   // scene-index GPU lane. Even direct draws need a complete entry for
@@ -1321,6 +1375,14 @@ export function buildPerSubmeshMaterialBg(
         entityKey,
         materialHandle: smMaterialHandle,
         shader: smShaderId,
+        surfaceModel: submeshMaterial.surfaceModel,
+        layoutIdentity: getOpaqueResourceIdentity(smMaterialBgl as object),
+        bindings: smMergedEntries.map((entry) => entry.binding),
+        graphResources: {
+          rawDepth: surfaceRawDepthView != null,
+          nearestLayer: surfaceNearestLayerView != null,
+          nearestDepth: surfaceNearestDepthView != null,
+        },
         paramSnapshot: submeshMaterial.paramSnapshot,
         handleTypes: materialCacheHandles.map((handle) => typeof handle),
       })}`,

package/src/record/main-pass-sprite-draws.ts

@@ -26,6 +26,7 @@ import type {
   MaterialSnapshot,
   SpriteInstancesSnapshot,
 } from '../render-system-extract';
+import { resolveFoldInstanceBuffer } from './fold-instance-buffer';
 import { worldEntityKey } from './frame-snapshot';
 import { recordGeometryDraws, resolveGeometryInstancesBindGroup } from './main-pass-geometry';
 import {
@@ -589,69 +590,10 @@ function recordSpriteEntityDraws(
     const spriteInst = spriteEntry.source.instances;
     const useFold = foldHeadBucket !== undefined && spriteInst === undefined;
     if (useFold && foldHeadBucket !== undefined) {
-      // w6 (D-8): bucket transient buffer reuse — composite cacheKey from
-      // (materialHandle, layer, validatedOrdered head index) so the
-      // existing `frameState.instanceBuffers` byteLength/archVersion path
-      // covers static steady-state upload-skip. Numeric Map<number,…> key
-      // requires a 32-bit-safe fold; we use a negative number-space prefix
-      // (-1, -2, ...) by `((materialHandle << 16) | i)` shifted into the
-      // negative half so it never collides with positive entity-Instances
-      // cacheKeys (which are extracted from Instances component cacheKey
-      // numeric ids, always non-negative). The `archVersion` proxy is
-      // bucketSize (a structural-shape signal) so static frames hit the
-      // cache.
-      const bucketCacheKey = -1 - (((foldHeadBucket.materialHandle & 0xffff) << 16) | (i & 0xffff));
-      const uniformFallback = runtime.device.caps.storageBuffer === false;
-      const bucketPayload = uniformFallback
-        ? foldHeadBucket.transforms
-        : packInstanceStorageBuffer(foldHeadBucket.transforms);
-      const bucketBytes = bucketPayload.byteLength;
-      const bucketBufUsage = uniformFallback
-        ? GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST
-        : GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST;
-      const cachedBucket = frameState.instanceBuffers.get(bucketCacheKey);
-      let activeBucket: InstanceBufferCacheEntry | null = null;
-      if (
-        cachedBucket !== undefined &&
-        cachedBucket.uploadedArchVersion === foldHeadBucket.bucketSize &&
-        cachedBucket.uploadedByteLength === bucketBytes
-      ) {
-        activeBucket = cachedBucket;
-      } else if (bucketBytes > 0) {
-        const bufRes = runtime.device.createBuffer({
-          size: bucketBytes,
-          usage: bucketBufUsage,
-          mappedAtCreation: false,
-        });
-        if (!bufRes.ok) {
-          runtime.errorRegistry.fire(bufRes.error);
-        } else {
-          if (cachedBucket !== undefined && !cachedBucket.buffer.isDestroyed) {
-            const r = cachedBucket.buffer.destroy();
-            if (!r.ok) runtime.errorRegistry.fire(r.error);
-          }
-          const newBuf = new GpuBuffer(runtime.device, bufRes.value);
-          activeBucket = {
-            buffer: newBuf,
-            uploadedArchVersion: foldHeadBucket.bucketSize,
-            uploadedByteLength: bucketBytes,
-          };
-          frameState.instanceBuffers.set(bucketCacheKey, activeBucket);
-        }
-      }
-      if (activeBucket !== null) {
-        const writeRes = runtime.device.queue.writeBuffer(
-          activeBucket.buffer.handle,
-          0,
-          bucketPayload,
-        );
-        if (!writeRes.ok) {
-          runtime.errorRegistry.fire(writeRes.error);
-        } else {
-          spriteInstanceBuffer = activeBucket.buffer.handle;
-          spriteInstanceCount = foldHeadBucket.bucketSize;
-        }
-      }
+      const buffer = resolveFoldInstanceBuffer(c, foldHeadBucket, i);
+      if (buffer === null) continue;
+      spriteInstanceBuffer = buffer;
+      spriteInstanceCount = foldHeadBucket.bucketSize;
     } else if (spriteInst !== undefined) {
       const uniformFallback = runtime.device.caps.storageBuffer === false;
       let spriteBufUsage = GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST;
@@ -681,7 +623,7 @@ function recordSpriteEntityDraws(
           );
           spritePass.setBindGroup(3, spriteInstBg);
           spritePass.drawIndexed(spriteEntry.mesh.indexCount, spriteInstanceCount, 0, 0, 0);
-          c.onRenderableDraw?.(spriteEntry);
+          c.onRenderableDraw?.(spriteEntry, 0);
           continue;
         }
         spriteBufUsage = GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST;
@@ -814,7 +756,7 @@ function recordSpriteEntityDraws(
     spritePass.setBindGroup(1, spritePassBg, [materialSlot * MATERIAL_PER_ENTITY_STRIDE]);
     spritePass.setBindGroup(3, spriteInstancesBg);
     spritePass.drawIndexed(spriteEntry.mesh.indexCount, spriteInstanceCount, 0, 0, 0);
-    c.onRenderableDraw?.(spriteEntry);
+    c.onRenderableDraw?.(spriteEntry, 0);
   }
 }
 

package/src/record/main-pass.ts

@@ -3,6 +3,7 @@ import { probeVideoHighPerfUpload } from '@forgeax/engine-graphics-extras';
 import type { GraphResourceResolver } from '@forgeax/engine-render-graph';
 import {
   type BindGroup,
+  type Buffer,
   RhiError,
   type RhiRenderPassEncoder,
   type TextureView,
@@ -10,6 +11,7 @@ import {
 import type { PassKind, PassSelector } from '@forgeax/engine-types';
 import {
   createGpuDrivenLightingBindGroup,
+  createHdrpSkinUnifiedBindGroup,
   createHdrpUnifiedBindGroup,
   getOrCreateHdrpBuffers,
 } from '../hdrp-buffers';
@@ -21,6 +23,7 @@ import type { ReflectionProbeSelectionResult } from '../reflection/projection';
 import type { RenderRecordPhase } from '../render-contract';
 import type {
   GpuDrivenStandardPbrFrameResources,
+  RenderPipelineGpuDrivenFilter,
   RenderPipelineGpuDrivenProjection,
 } from '../render-pipeline';
 import type { MaterialSnapshot } from '../render-system-extract';
@@ -65,12 +68,28 @@ export type MainPassOptions = {
   readonly depthView?: TextureView | null;
   readonly passKind?: PassKind;
   readonly clearColor?: readonly [number, number, number, number];
-  readonly recordMode?: 'opaque' | 'transmission' | 'transparent';
+  readonly recordMode?:
+    | 'opaque'
+    | 'transmission'
+    | 'transparent'
+    | 'single-layer-medium-nearest-layer'
+    | 'single-layer-medium-color';
+  readonly gpuDrivenFilter?: RenderPipelineGpuDrivenFilter;
+  /** Write transparent fragment depth for depth-bounded medium transport. */
+  readonly transparentDepthWrite?: boolean;
   /** Exclude material/pass pairs already consumed by an earlier graph lane. */
   readonly excludeSelector?: PassSelector;
   /** Require the same material to contribute to another graph lane. */
   readonly includeSelector?: PassSelector;
   readonly transmissionBackdropView?: TextureView | null;
+  /** Independent sampled raw depth produced before the medium passes. */
+  readonly surfaceRawDepthView?: TextureView | null;
+  /** Nearest-layer color produced by the preceding medium pass. */
+  readonly surfaceNearestLayerView?: TextureView | null;
+  /** Nearest-layer depth produced by the preceding medium pass. */
+  readonly surfaceNearestDepthView?: TextureView | null;
+  /** Surface shader fragment entry selected by the typed pass owner. */
+  readonly fragmentEntryPoint?: string;
   /** Select the material temporal entry's binary coverage output. */
   readonly coverageOnly?: boolean;
   readonly gpuDriven?: {
@@ -89,29 +108,53 @@ function isTransmissionMaterial(material: MaterialSnapshot): boolean {
 
 function matchesRecordMode(
   material: MaterialSnapshot,
-  mode: 'opaque' | 'transmission' | 'transparent',
+  mode:
+    | 'opaque'
+    | 'transmission'
+    | 'transparent'
+    | 'single-layer-medium-nearest-layer'
+    | 'single-layer-medium-color',
 ): boolean {
+  const medium =
+    material.surfaceModel === 'single-layer-medium' ||
+    material.materialShaderId === 'forgeax::single-layer-medium';
+  if (mode === 'single-layer-medium-nearest-layer' || mode === 'single-layer-medium-color') {
+    return medium;
+  }
   const transmission = isTransmissionMaterial(material);
   if (mode === 'transmission') return transmission;
-  if (mode === 'transparent') return material.transparent === true && !transmission;
-  return !transmission && material.transparent !== true;
+  if (mode === 'transparent') return material.transparent === true && !transmission && !medium;
+  return !transmission && material.transparent !== true && !medium;
 }
 
 function matchedMaterialsForRecordMode(
   c: _InternalRenderPipelineContext,
   matchedMaterials: ReadonlyMap<number, ReadonlySet<number>> | null,
-  mode: 'opaque' | 'transmission' | 'transparent' | undefined,
+  mode:
+    | 'opaque'
+    | 'transmission'
+    | 'transparent'
+    | 'single-layer-medium-nearest-layer'
+    | 'single-layer-medium-color'
+    | undefined,
 ): ReadonlyMap<number, ReadonlySet<number>> | null {
   if (mode === undefined) return matchedMaterials;
+  const surfaceMode =
+    mode === 'single-layer-medium-nearest-layer' || mode === 'single-layer-medium-color';
   const filtered = new Map<number, ReadonlySet<number>>();
   for (const entry of c.validatedOrdered) {
     const dispatchHandles = matchedMaterials?.get(entry.renderableIndex);
-    if (matchedMaterials !== null && dispatchHandles === undefined) continue;
-    const candidateHandles =
-      dispatchHandles ??
-      (mode === 'transmission'
-        ? []
-        : entry.source.materials.map((material) => material.materialHandle ?? 0));
+    // Surface graph membership is owned by the resolved surface model. A
+    // Surface-authored pass does not need to duplicate the generic Forward
+    // LightMode tag: its prepared direct program already carries the pass
+    // specialization selected by the material producer.
+    if (!surfaceMode && matchedMaterials !== null && dispatchHandles === undefined) continue;
+    const candidateHandles = surfaceMode
+      ? entry.source.materials.map((material) => material.materialHandle ?? 0)
+      : (dispatchHandles ??
+        (mode === 'transmission'
+          ? []
+          : entry.source.materials.map((material) => material.materialHandle ?? 0)));
     const handles = new Set<number>();
     for (const handle of candidateHandles) {
       const material =
@@ -173,11 +216,19 @@ export function recordMainPass(
   const passKind = options?.passKind ?? 'forward';
   const recordMode = options?.recordMode;
   const transmissionBackdropView = options?.transmissionBackdropView;
-  if (recordMode === 'transmission' && transmissionBackdropView == null) {
+  const surfaceRawDepthView = options?.surfaceRawDepthView;
+  const surfaceNearestLayerView = options?.surfaceNearestLayerView;
+  const surfaceNearestDepthView = options?.surfaceNearestDepthView;
+  if (
+    (recordMode === 'transmission' ||
+      recordMode === 'single-layer-medium-nearest-layer' ||
+      recordMode === 'single-layer-medium-color') &&
+    transmissionBackdropView == null
+  ) {
     throw new RhiError({
       code: 'webgpu-runtime-error',
-      expected: 'transmissionBackdropView != null for transmission record mode',
-      hint: 'the typed Standard transmission pass must resolve its private backdrop view',
+      expected: 'transmissionBackdropView != null for a backdrop-consuming record mode',
+      hint: 'the typed Standard backdrop pass must resolve its graph-paired color view',
     });
   }
   const colorViews = options?.colorViews ?? [geometryColorView];
@@ -224,12 +275,11 @@ export function recordMainPass(
   // fallback because the transient SSAO texture does not exist that early.
   // Built per frame (the SSAO target is a graph transient, so no cross-frame
   // cache); HDRP-only and SSAO-only, so URP and SSAO-off paths are untouched.
+  const hdrpBuffers = clusteredLighting
+    ? getOrCreateHdrpBuffers(runtime, frameState.installedPipelineConfig?.clusterGrid)
+    : null;
   let hdrpSsaoBindGroup: BindGroup | null = null;
-  if (clusteredLighting && hdrpClusterBindGroup !== null && c.hdrpSsaoBlurredView !== undefined) {
-    const hdrpBuffers = getOrCreateHdrpBuffers(
-      runtime,
-      frameState.installedPipelineConfig?.clusterGrid,
-    );
+  if (hdrpClusterBindGroup !== null && c.hdrpSsaoBlurredView !== undefined) {
     if (hdrpBuffers !== null) {
       hdrpSsaoBindGroup = createHdrpUnifiedBindGroup(
         runtime,
@@ -242,6 +292,71 @@ export function recordMainPass(
   const meshGroup2: BindGroup | null = clusteredLighting
     ? (hdrpSsaoBindGroup ?? hdrpClusterBindGroup)
     : meshBindGroup;
+  if (gpuDrivenStandardPbrFrameResources !== undefined) {
+    // The GPU-driven owner prepares before transient graph resources exist;
+    // publish the actual Standard group(2) here, at the existing main-pass
+    // binding seam, immediately before indirect encoding.
+    gpuDrivenStandardPbrFrameResources.clusterBindGroup =
+      clusteredLighting && meshGroup2 !== null ? meshGroup2 : undefined;
+    if (hdrpBuffers === null) {
+      gpuDrivenStandardPbrFrameResources.clusterBindGroupForMesh = undefined;
+      gpuDrivenStandardPbrFrameResources.clusterBindGroupForSkin = undefined;
+    } else {
+      const projectedGroups = new Map<Buffer, BindGroup>();
+      gpuDrivenStandardPbrFrameResources.clusterBindGroupForMesh = (meshBuffer, bindingBytes) => {
+        const cached = projectedGroups.get(meshBuffer);
+        if (cached !== undefined) return cached;
+        const created = createHdrpUnifiedBindGroup(
+          runtime,
+          hdrpBuffers,
+          meshBuffer,
+          c.hdrpSsaoBlurredView === undefined
+            ? { enabled: false }
+            : { enabled: true, ssaoBlurredView: c.hdrpSsaoBlurredView },
+          bindingBytes,
+        );
+        if (created !== null) projectedGroups.set(meshBuffer, created);
+        return created ?? undefined;
+      };
+      const projectedSkinGroups = new Map<Buffer, Map<Buffer, Map<string, BindGroup>>>();
+      gpuDrivenStandardPbrFrameResources.clusterBindGroupForSkin = (
+        meshBuffer,
+        meshBindingBytes,
+        paletteBuffer,
+        paletteBindingWindowBytes,
+      ) => {
+        let meshGroups = projectedSkinGroups.get(meshBuffer);
+        if (meshGroups === undefined) {
+          meshGroups = new Map();
+          projectedSkinGroups.set(meshBuffer, meshGroups);
+        }
+        let paletteGroups = meshGroups.get(paletteBuffer);
+        if (paletteGroups === undefined) {
+          paletteGroups = new Map();
+          meshGroups.set(paletteBuffer, paletteGroups);
+        }
+        const bindingKey = `${meshBindingBytes}:${paletteBindingWindowBytes}`;
+        const cached = paletteGroups.get(bindingKey);
+        if (cached !== undefined) return cached;
+        const skinLayout = pipelineState.hdrpSkinMeshBindGroupLayout;
+        if (skinLayout === null) return undefined;
+        const created = createHdrpSkinUnifiedBindGroup(
+          runtime,
+          hdrpBuffers,
+          skinLayout,
+          meshBuffer,
+          paletteBuffer,
+          paletteBindingWindowBytes,
+          c.hdrpSsaoBlurredView === undefined
+            ? { enabled: false }
+            : { enabled: true, ssaoBlurredView: c.hdrpSsaoBlurredView },
+          meshBindingBytes,
+        );
+        if (created !== null) paletteGroups.set(bindingKey, created);
+        return created ?? undefined;
+      };
+    }
+  }
   // ── Geometry (main colour) pass ──────────────────────────────────
   // D-2: tracks whether the geometry pass was explicitly ended inside
   // the `if (validatedOrdered.length > 0)` block (sprite split path),
@@ -535,6 +650,9 @@ export function recordMainPass(
               gpuDrivenSceneMaterialBuffer,
           }),
       ...(transmissionBackdropView === undefined ? {} : { transmissionBackdropView }),
+      ...(surfaceRawDepthView === undefined ? {} : { surfaceRawDepthView }),
+      ...(surfaceNearestLayerView === undefined ? {} : { surfaceNearestLayerView }),
+      ...(surfaceNearestDepthView === undefined ? {} : { surfaceNearestDepthView }),
     };
     const buildPerSubmeshMaterialBg = (
       submeshMaterial: MaterialSnapshot,
@@ -558,6 +676,12 @@ export function recordMainPass(
     for (let materialSlot = 0; materialSlot < materialSlotCount; materialSlot += 1) {
       const material = materialSlots[materialSlot];
       if (material === undefined || (material.videoTextureFields?.size ?? 0) > 0) continue;
+      // A graph scene pass owns only the materials selected by its record
+      // mode. In particular, the opaque pass runs before the raw-depth
+      // producer and must not assemble medium bindings with resources that do
+      // not exist until the later nearest-layer/color passes. Keep holes for
+      // the other lanes; the GPU encoder validates the exact slot it consumes.
+      if (recordMode !== undefined && !matchesRecordMode(material, recordMode)) continue;
       const owner = materialSlotOwners[materialSlot];
       if (owner === undefined) continue;
       preparedMaterialBindGroups[materialSlot] = buildPerSubmeshMaterialBg(
@@ -656,6 +780,13 @@ export function recordMainPass(
         selectedDispatch,
         colorFormats,
         options?.coverageOnly ?? false,
+        options?.fragmentEntryPoint,
+        recordMode === 'single-layer-medium-nearest-layer'
+          ? 'nearest-layer'
+          : recordMode === 'single-layer-medium-color'
+            ? 'color'
+            : undefined,
+        options?.transparentDepthWrite ?? false,
       );
     };
     if (c.profilePhase === undefined) {
@@ -676,7 +807,10 @@ export function recordMainPass(
           hint: 'publish the current frame view/light/shadow bind group before GPU raster',
         });
       }
-      if (gpuDrivenStandardPbrFrameResources === undefined) {
+      if (
+        gpuDrivenStandardPbrFrameResources === undefined ||
+        gpuDrivenStandardPbrFrameResources.materialBindGroups.length === 0
+      ) {
         throw new RhiError({
           code: 'rhi-not-available',
           expected: 'complete main-pass Standard PBR material bind-group receipt',
@@ -688,6 +822,8 @@ export function recordMainPass(
         pass,
         options.gpuDriven.resources,
         gpuDrivenStandardPbrFrameResources,
+        options.gpuDrivenFilter,
+        options?.fragmentEntryPoint,
       );
     }
 

package/src/record/motion-blur-receipt.ts

@@ -0,0 +1,91 @@
+import { getRenderFeaturePlanExecutionProjection } from '../features/host';
+import type { RenderFeaturePlannedFrame } from '../features/plan';
+import type { MotionBlurExecutionPass, MotionBlurExecutionReceipt } from '../inspection-types';
+import type { RenderFrameState } from './frame-snapshot';
+import type { RenderSystemInternals } from './render-context';
+
+/**
+ * Project one accepted Motion Blur compute execution from the same graph and
+ * resolved dispatch objects used by the encoder. A plan/capability candidate
+ * without both executed passes deliberately returns no receipt.
+ */
+export function deriveMotionBlurExecutionReceipt(
+  internals: RenderSystemInternals,
+  frameState: RenderFrameState,
+  plans: readonly RenderFeaturePlannedFrame[],
+): MotionBlurExecutionReceipt | undefined {
+  const graph = frameState.compiledFrameGraph;
+  const deviceGeneration = internals.deviceScope?.generation;
+  if (graph === null || deviceGeneration === undefined) return undefined;
+  const info = graph.inspect();
+  const graphPasses = new Map(info.passes.map((pass) => [pass.name, pass]));
+  const summaryGraphPass = graphPasses.get('motion-blur-tile-summary');
+  const reconstructGraphPass = graphPasses.get('motion-blur');
+  if (summaryGraphPass?.kind !== 'compute' || reconstructGraphPass?.kind !== 'compute') {
+    return undefined;
+  }
+  const planned = plans.find((candidate) => candidate.featureIdentity === 'forgeax.motion-blur');
+  const execution =
+    planned === undefined ? undefined : getRenderFeaturePlanExecutionProjection(planned);
+  if (execution === undefined || execution.featureIdentity !== 'forgeax.motion-blur') {
+    return undefined;
+  }
+  const executionPass = (name: 'motion-blur-tile-summary' | 'motion-blur') =>
+    execution.passes.find((pass) => pass.name === name);
+  const summary = executionPass('motion-blur-tile-summary');
+  const reconstruct = executionPass('motion-blur');
+  if (
+    summary?.gpuCompute === undefined ||
+    reconstruct?.gpuCompute === undefined ||
+    summary.resolvedGpuCompute === undefined ||
+    reconstruct.resolvedGpuCompute === undefined
+  ) {
+    return undefined;
+  }
+  const directWorkgroups = (
+    pass: NonNullable<typeof summary.resolvedGpuCompute>,
+  ): readonly [number, number, number] | undefined => {
+    const dispatch = pass.dispatches[0];
+    if (dispatch === undefined || !('workgroups' in dispatch)) return undefined;
+    return dispatch.workgroups;
+  };
+  const summaryWorkgroups = directWorkgroups(summary.resolvedGpuCompute);
+  const reconstructWorkgroups = directWorkgroups(reconstruct.resolvedGpuCompute);
+  if (summaryWorkgroups === undefined || reconstructWorkgroups === undefined) return undefined;
+  const outputResource = info.resources.find(
+    (resource) =>
+      resource.label === 'motion-blurred-color' ||
+      reconstructGraphPass.accesses.some(
+        (access) => access.resource === resource.label && access.usage === 'storage-write',
+      ),
+  );
+  if (
+    outputResource?.descriptor.kind !== 'texture' ||
+    outputResource.descriptor.format !== 'rgba16float'
+  ) {
+    return undefined;
+  }
+  const summaryReceipt: MotionBlurExecutionPass = {
+    name: 'motion-blur-tile-summary',
+    kind: 'compute',
+    entryPoint: 'tile_summary',
+    workgroups: summaryWorkgroups,
+  };
+  const reconstructReceipt: MotionBlurExecutionPass = {
+    name: 'motion-blur',
+    kind: 'compute',
+    entryPoint: 'reconstruct',
+    workgroups: reconstructWorkgroups,
+  };
+  return Object.freeze({
+    frameId: frameState.frameNumber,
+    deviceGeneration,
+    // RenderGraphBuilder generations are process-global. The renderer's
+    // frame-state generation is the identity used by inspection and by the
+    // same-frame admission check below, so retain that owner-scoped value.
+    graphGeneration: frameState.graphGeneration,
+    program: 'motion-blur-compute' as const,
+    outputFormat: 'rgba16float' as const,
+    passes: [summaryReceipt, reconstructReceipt] as const,
+  });
+}