@forgeax/engine-render 0.1.32 → 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;
@@ -690,7 +632,12 @@ function recordSpriteEntityDraws(
       {
         const instancePayload = uniformFallback
           ? spriteInst.transforms
-          : packInstanceStorageBuffer(spriteInst.transforms);
+          : packInstanceStorageBuffer(
+              spriteInst.transforms,
+              spriteEntry.source.temporal?.previousInstances?.transforms,
+              spriteInst.generations,
+              spriteEntry.source.temporal?.previousInstances?.generations,
+            );
         const requestedBytes = instancePayload.byteLength;
         const cap = runtime.device.limits.maxStorageBufferBindingSize;
         if (typeof cap === 'number' && requestedBytes > cap) {
@@ -809,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/mesh-ssbo.ts

@@ -43,23 +43,58 @@ export const MAX_UNIFORM_INSTANCES = 128;
 /** The storage-backed InstanceData layout is current + previous mat4. */
 export const INSTANCE_STORAGE_STRIDE_FLOATS = 32;
 
+function hasStableGenerationColumn(generations: Uint32Array | undefined, count: number): boolean {
+  if (generations === undefined || generations.length !== count) return false;
+  const seen = new Set<number>();
+  for (const generation of generations) {
+    if (generation === 0 || seen.has(generation)) return false;
+    seen.add(generation);
+  }
+  return true;
+}
+
 /**
  * Project the ECS transform snapshot into the storage-backed InstanceData
- * layout. The extract contract carries one current mat4 per instance; until
- * the ECS snapshot owns a previous-instance column, current is the honest
- * previous value as well. Uniform-backed variants keep the compact 16-float
- * payload and do not use this projection.
+ * layout. Unique identity generations select the previous matrix only when
+ * the producer proves that the instance survived. Replaced slots seed
+ * previous=current; reordered slots map back to the real prior ordinal so a
+ * compaction cannot exchange velocities. Uniform-backed variants keep the
+ * compact 16-float payload and do not use this projection.
  */
-export function packInstanceStorageBuffer(transforms: Float32Array): Float32Array {
+export function packInstanceStorageBuffer(
+  transforms: Float32Array,
+  previousTransforms: Float32Array = transforms,
+  generations?: Uint32Array,
+  previousGenerations?: Uint32Array,
+): Float32Array {
   const count = Math.floor(transforms.length / 16);
   const out = new Float32Array(count * INSTANCE_STORAGE_STRIDE_FLOATS);
+  const previousCount = Math.floor(previousTransforms.length / 16);
+  const generationInput = generations !== undefined || previousGenerations !== undefined;
+  const identityProof =
+    hasStableGenerationColumn(generations, count) &&
+    hasStableGenerationColumn(previousGenerations, previousCount);
+  const previousIndexByGeneration = identityProof
+    ? new Map(
+        Array.from(previousGenerations ?? [], (generation, index) => [generation, index] as const),
+      )
+    : undefined;
   for (let i = 0; i < count; i++) {
     const sourceBase = i * 16;
     const targetBase = i * INSTANCE_STORAGE_STRIDE_FLOATS;
+    const previousIndex = identityProof
+      ? previousIndexByGeneration?.get(generations?.[i] ?? 0)
+      : !generationInput && previousCount === count
+        ? i
+        : undefined;
+    const sameIdentity = previousIndex !== undefined && previousIndex < previousCount;
+    const previousBase = (previousIndex ?? i) * 16;
     for (let k = 0; k < 16; k++) {
       const value = transforms[sourceBase + k] ?? 0;
       out[targetBase + k] = value;
-      out[targetBase + 16 + k] = value;
+      out[targetBase + 16 + k] = sameIdentity
+        ? (previousTransforms[previousBase + k] ?? value)
+        : value;
     }
   }
   return out;
@@ -451,6 +486,7 @@ export function uploadMeshSsboBatch(
       _meshSsboScratchFloats[slot + 38] = 1;
       _meshSsboScratchFloats[slot + 43] = 1;
       _meshSsboScratchFloats[slot + 44] = 1;
+      _meshSsboScratchFloats[slot + 45] = 1;
     } else {
       const worldFromLocal = entry.source.transform.world;
       for (let k = 0; k < 16; k++) _meshSsboScratchFloats[slot + k] = worldFromLocal[k] ?? 0;
@@ -483,6 +519,7 @@ export function uploadMeshSsboBatch(
       }
       _meshSsboScratchFloats[slot + 44] =
         entry.source.temporal?.reactive === true || reactiveMaterial ? 1 : 0;
+      _meshSsboScratchFloats[slot + 45] = entry.source.temporal?.motionValid === false ? 0 : 1;
     }
   }
   if (neededBytes > 0) {