@forgeax/engine-render 0.1.32 → 0.1.34

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,
+  });
+}

package/src/record/probe-blend-buffer.ts

@@ -0,0 +1,180 @@
+import type { Buffer, RhiDevice } from '@forgeax/engine-rhi';
+import { GpuBuffer } from '../gpu-resource';
+import {
+  GPU_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_STORAGE,
+  GPU_BUFFER_USAGE_UNIFORM,
+} from '../gpu-usage';
+import type { ProbeBlendBufferProjection } from '../scene/probe-blend';
+import {
+  PROBE_BLEND_RECORD_STRIDE,
+  type ProbeBlendRecord,
+  probeBlendRecordOffset,
+} from '../scene/probe-blend-record';
+import type { RenderFrameState } from './frame-snapshot';
+
+export interface ProbeBlendBufferRecord {
+  readonly cacheKey: number;
+  readonly record: ProbeBlendRecord;
+}
+
+function isProbeBlendProjection(
+  input: ProbeBlendBufferProjection | readonly ProbeBlendBufferRecord[],
+): input is ProbeBlendBufferProjection {
+  return !Array.isArray(input);
+}
+
+function retireProbeBlendRecordBuffer(buffer: GpuBuffer): void {
+  const destroy = (): void => {
+    if (!buffer.isDestroyed) void buffer.destroy();
+  };
+  void buffer.device.queue.onSubmittedWorkDone().then(destroy, destroy);
+}
+
+function createCompleteProbeBlendBuffer(
+  device: RhiDevice,
+  requiredCapacity: number,
+  records: readonly ProbeBlendBufferRecord[],
+): {
+  readonly buffer: GpuBuffer;
+  readonly cache: ReadonlyMap<number, { readonly generation: number; readonly bytes: Uint8Array }>;
+} {
+  const created = device.createBuffer({
+    label: 'probe-blend-records',
+    size: requiredCapacity * PROBE_BLEND_RECORD_STRIDE,
+    usage:
+      (device.caps.storageBuffer ? GPU_BUFFER_USAGE_STORAGE : GPU_BUFFER_USAGE_UNIFORM) |
+      GPU_BUFFER_USAGE_COPY_DST,
+    mappedAtCreation: false,
+  });
+  if (!created.ok) throw created.error;
+  const candidate = new GpuBuffer(device, created.value);
+  const cache = new Map<number, { readonly generation: number; readonly bytes: Uint8Array }>();
+  try {
+    for (const { cacheKey, record } of records) {
+      const uploaded = device.queue.writeBuffer(
+        candidate.handle,
+        probeBlendRecordOffset(record.objectKey),
+        record.bytes,
+      );
+      if (!uploaded.ok) throw uploaded.error;
+      cache.set(cacheKey, {
+        generation: record.generation,
+        bytes: new Uint8Array(record.bytes),
+      });
+    }
+  } catch (cause) {
+    void candidate.destroy();
+    throw cause;
+  }
+  return { buffer: candidate, cache };
+}
+
+/**
+ * Retain one device buffer for direct and scene-index ProbeBlend consumers.
+ * Capacity is settled before any upload so a growth cannot erase records
+ * written earlier in the same frame. Slot zero remains the producer sentinel;
+ * RenderScene object slot N occupies aligned record N+1.
+ */
+export function ensureProbeBlendRecordBuffer(
+  device: RhiDevice,
+  frameState: Pick<
+    RenderFrameState,
+    | 'probeBlendRecordBuffer'
+    | 'probeBlendRecordBufferCapacity'
+    | 'probeBlendBuffers'
+    | 'probeBlendRecordProjection'
+  >,
+  input: ProbeBlendBufferProjection | readonly ProbeBlendBufferRecord[] | undefined,
+): Buffer | undefined {
+  const projection = input !== undefined && isProbeBlendProjection(input) ? input : undefined;
+  const records: readonly ProbeBlendBufferRecord[] =
+    input === undefined
+      ? []
+      : (projection?.records ?? (input as readonly ProbeBlendBufferRecord[]));
+  let buffer = frameState.probeBlendRecordBuffer;
+  const accepted = frameState.probeBlendRecordProjection;
+  if (
+    projection !== undefined &&
+    accepted?.projection === projection &&
+    accepted.device === device
+  ) {
+    if (records.length === 0) return undefined;
+    if (accepted.buffer === buffer && buffer !== undefined && !buffer.isDestroyed) {
+      return buffer.handle;
+    }
+  }
+  if (records.length === 0) {
+    if (projection !== undefined) {
+      frameState.probeBlendBuffers.clear();
+      frameState.probeBlendRecordProjection = {
+        projection,
+        device,
+        buffer: undefined,
+      };
+    }
+    return undefined;
+  }
+  const requiredCapacity =
+    projection?.capacity ??
+    records.reduce((capacity, { record }) => Math.max(capacity, record.objectKey + 2), 1);
+  const grows =
+    buffer === undefined ||
+    buffer.isDestroyed ||
+    buffer.device !== device ||
+    frameState.probeBlendRecordBufferCapacity < requiredCapacity;
+  const hasAcceptedBaseline =
+    projection !== undefined &&
+    accepted !== undefined &&
+    accepted.device === device &&
+    accepted.buffer === buffer &&
+    buffer !== undefined &&
+    !buffer.isDestroyed &&
+    accepted.projection.sourceIdentity === projection.sourceIdentity &&
+    accepted.projection.revision === projection.baseRevision;
+  const requiresCompletePublish =
+    grows ||
+    (projection !== undefined && (!hasAcceptedBaseline || projection.dirtyRecords.length > 1));
+  if (requiresCompletePublish) {
+    const candidate = createCompleteProbeBlendBuffer(device, requiredCapacity, records);
+    const previous = buffer;
+    buffer = candidate.buffer;
+    frameState.probeBlendRecordBuffer = candidate.buffer;
+    frameState.probeBlendRecordBufferCapacity = requiredCapacity;
+    frameState.probeBlendBuffers.clear();
+    for (const [key, value] of candidate.cache) frameState.probeBlendBuffers.set(key, value);
+    if (projection === undefined) delete frameState.probeBlendRecordProjection;
+    else frameState.probeBlendRecordProjection = { projection, device, buffer: candidate.buffer };
+    if (previous !== undefined) retireProbeBlendRecordBuffer(previous);
+    return candidate.buffer.handle;
+  }
+  if (buffer === undefined) return undefined;
+  const changed = projection?.dirtyRecords ?? records;
+  const cacheUpdates: [number, { readonly generation: number; readonly bytes: Uint8Array }][] = [];
+  for (const { cacheKey, record } of changed) {
+    const cached = frameState.probeBlendBuffers.get(cacheKey);
+    const unchanged =
+      cached !== undefined &&
+      cached.generation === record.generation &&
+      cached.bytes.length === record.bytes.length &&
+      cached.bytes.every((value, index) => value === record.bytes[index]);
+    if (unchanged) continue;
+    const uploaded = device.queue.writeBuffer(
+      buffer.handle,
+      probeBlendRecordOffset(record.objectKey),
+      record.bytes,
+    );
+    if (!uploaded.ok) throw uploaded.error;
+    cacheUpdates.push([
+      cacheKey,
+      { generation: record.generation, bytes: new Uint8Array(record.bytes) },
+    ]);
+  }
+  for (const [cacheKey, value] of cacheUpdates) frameState.probeBlendBuffers.set(cacheKey, value);
+  for (const cacheKey of projection?.removedCacheKeys ?? []) {
+    frameState.probeBlendBuffers.delete(cacheKey);
+  }
+  if (projection === undefined) delete frameState.probeBlendRecordProjection;
+  else frameState.probeBlendRecordProjection = { projection, device, buffer };
+  return buffer.handle;
+}

package/src/record/recovery-pipeline.ts

@@ -173,7 +173,11 @@ function addRequest(input: {
   readonly vertexLayoutProjection?: VertexLayoutProjection;
   readonly vertexEntry?: string;
   readonly fragmentEntry?: string;
-  readonly layoutKindOverride?: 'pbr' | 'pbr-skin';
+  readonly layoutKindOverride?:
+    | 'pbr'
+    | 'pbr-skin'
+    | 'surface-direct-pbr'
+    | 'surface-direct-cluster-pbr';
   readonly preserveUndefinedVariant?: boolean;
   readonly variantAlreadyResolved?: boolean;
 }): void {
@@ -244,7 +248,7 @@ function addRequest(input: {
       undefined,
       undefined,
       projection,
-      undefined,
+      'immediate',
       input.layoutKindOverride,
       undefined,
       input.additionalColorFormats,
@@ -260,6 +264,7 @@ function addStandardMaterialRequests(input: {
   readonly internals: RenderSystemInternals;
   readonly pipelineState: PipelineState;
   readonly validated: readonly ValidatedRenderable[];
+  readonly dispatch: readonly DispatchEntry[];
   readonly standardLighting: StandardTopologyInputValue | undefined;
   readonly sampleCount: number;
   readonly isHdrTarget: boolean;
@@ -267,6 +272,13 @@ function addStandardMaterialRequests(input: {
   readonly reflectionFallbackAvailable: boolean;
 }): void {
   const pointsLinesProjection = deriveVertexLayoutProjection(DEFAULT_VERTEX_ATTRIBUTE_MAP);
+  const forwardPrograms = new Map<string, DispatchEntry>();
+  for (const candidate of input.dispatch) {
+    if (candidate.tags.LightMode !== 'Forward' || candidate.materialShaderId === undefined)
+      continue;
+    const key = `${candidate.renderableIndex}:${candidate.materialHandle}`;
+    if (!forwardPrograms.has(key)) forwardPrograms.set(key, candidate);
+  }
   for (const entry of input.validated) {
     if (entry.source.pointsLines !== undefined) {
       const pointsLinesMaterial = entry.source.material;
@@ -312,9 +324,14 @@ function addStandardMaterialRequests(input: {
     const unlitHasColor = unlitProjection === 'VERTEX_COLOR_AVAILABLE=true';
     for (const submesh of entry.mesh.submeshes) {
       const material = entry.source.materials[submesh.materialSlot] ?? entry.source.material;
+      const forwardProgram = forwardPrograms.get(
+        `${entry.renderableIndex}:${material.materialHandle ?? -1}`,
+      );
       const materialShaderId =
         entry.source.skin === undefined
-          ? (material.materialShaderId ?? 'forgeax::default-unlit')
+          ? (forwardProgram?.materialShaderId ??
+            material.materialShaderId ??
+            'forgeax::default-unlit')
           : SKIN_MATERIAL_SHADER_ID;
       const renderState = geometryRenderStateForPass(
         recoveryRenderState(materialShaderId, material, submesh.topology) as ReturnType<
@@ -370,6 +387,13 @@ function addStandardMaterialRequests(input: {
       const materialCapabilityVariantSet = isStandardPbrMaterialShader(materialShaderId)
         ? standardPbrCapabilityVariantSet
         : capabilityVariantSet;
+      const surfaceLayoutKind =
+        material.surfaceModel === 'single-layer-medium'
+          ? input.standardLighting?.kind === 'clustered' &&
+            input.internals.device.caps.storageBuffer
+            ? ('surface-direct-cluster-pbr' as const)
+            : ('surface-direct-pbr' as const)
+          : undefined;
       const requestedVariant = isSprite
         ? materialShaderId === 'forgeax::sprite' && entry.source.spriteInstances !== undefined
           ? SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET
@@ -398,6 +422,12 @@ function addStandardMaterialRequests(input: {
         indexFormat: entry.mesh.indexFormat,
         ...optionalVariant(reflectionFallbackVariant),
         passKind: 'forward',
+        ...(forwardProgram?.vertexEntry === undefined
+          ? {}
+          : { vertexEntry: forwardProgram.vertexEntry }),
+        ...(forwardProgram?.fragmentEntry === undefined
+          ? {}
+          : { fragmentEntry: forwardProgram.fragmentEntry }),
         sampleCount: input.sampleCount,
         ...optionalColorFormat(input.colorFormatOverride),
         ...(input.reflectionFallbackAvailable &&
@@ -405,6 +435,7 @@ function addStandardMaterialRequests(input: {
           ? { additionalColorFormats: ['rgba16float'] as const }
           : {}),
         vertexLayoutProjection: meshProjection,
+        ...(surfaceLayoutKind === undefined ? {} : { layoutKindOverride: surfaceLayoutKind }),
         preserveUndefinedVariant: isSprite && requestedVariant === undefined,
         variantAlreadyResolved:
           isSprite ||
@@ -610,6 +641,7 @@ export function prepareRecoveryPipelineReadiness(input: {
     internals: input.internals,
     pipelineState: input.pipelineState,
     validated: input.validated,
+    dispatch: input.dispatch,
     standardLighting: input.standardLighting,
     sampleCount,
     isHdrTarget,

package/src/record/render-context.ts

@@ -113,6 +113,11 @@ export interface ReflectionProbeRecordState {
 export interface MaterialShaderPipelineEntry {
   readonly pipeline: RhiRenderPipeline;
   readonly group2Contract: PipelineGroup2Contract;
+  /** Producer receipt for the exact artifact selected with this pipeline. */
+  readonly receipt?: {
+    readonly identity: string;
+    readonly generation: number;
+  };
 }
 
 import type {
@@ -198,6 +203,7 @@ export interface RenderSystemRuntime {
       | {
           readonly vertexColorAvailable?: boolean;
           readonly deformation?: 'rigid' | 'skin';
+          readonly variantSet?: string;
           readonly clustered?: boolean;
           readonly reflectionFallback?: boolean;
           readonly pass?: 'forward' | 'shadow' | 'depth';
@@ -221,7 +227,15 @@ export interface RenderSystemRuntime {
     vertexLayout?: string,
     vertexLayoutProjection?: VertexLayoutProjection,
     shaderModuleMode?: RenderFeatureShaderModuleMode,
-    layoutKindOverride?: 'pbr' | 'pbr-skin' | 'gpu-driven-pbr' | 'gpu-driven-skin',
+    layoutKindOverride?:
+      | 'pbr'
+      | 'pbr-skin'
+      | 'gpu-driven-pbr'
+      | 'gpu-driven-skin'
+      | 'gpu-driven-cluster-pbr'
+      | 'gpu-driven-cluster-skin'
+      | 'surface-direct-pbr'
+      | 'surface-direct-cluster-pbr',
     /** Optional vertex entry override for receipt-owned scene-index passes. */
     vertexEntryPoint?: string,
     additionalColorFormats?: readonly GPUTextureFormat[],
@@ -246,7 +260,15 @@ export interface RenderSystemRuntime {
     vertexLayout?: string,
     vertexLayoutProjection?: VertexLayoutProjection,
     shaderModuleMode?: RenderFeatureShaderModuleMode,
-    layoutKindOverride?: 'pbr' | 'pbr-skin' | 'gpu-driven-pbr' | 'gpu-driven-skin',
+    layoutKindOverride?:
+      | 'pbr'
+      | 'pbr-skin'
+      | 'gpu-driven-pbr'
+      | 'gpu-driven-skin'
+      | 'gpu-driven-cluster-pbr'
+      | 'gpu-driven-cluster-skin'
+      | 'surface-direct-pbr'
+      | 'surface-direct-cluster-pbr',
     /** Optional vertex entry override for receipt-owned scene-index passes. */
     vertexEntryPoint?: string,
     additionalColorFormats?: readonly GPUTextureFormat[],
@@ -337,17 +359,15 @@ export interface PerPassResources {
   readonly skyboxBindGroupLayout: BindGroupLayout | null;
   readonly skyboxSampler: Sampler | null;
   readonly skyboxRotationBuffer: Buffer | null;
-  bloomBrightPipeline: RhiRenderPipeline | null;
-  bloomBlurHPipeline: RhiRenderPipeline | null;
-  bloomBlurVPipeline: RhiRenderPipeline | null;
+  bloomDownsamplePipeline: RhiRenderPipeline | null;
+  bloomUpsamplePipeline: RhiRenderPipeline | null;
   bloomCompositePipeline: RhiRenderPipeline | null;
-  bloomBrightBindGroupLayout: BindGroupLayout | null;
-  bloomBlurBindGroupLayout: BindGroupLayout | null;
+  bloomDownsampleBindGroupLayout: BindGroupLayout | null;
+  bloomUpsampleBindGroupLayout: BindGroupLayout | null;
   bloomCompositeBindGroupLayout: BindGroupLayout | null;
   bloomSampler: Sampler | null;
-  bloomBrightParamsBuffer: Buffer | null;
-  bloomBlurHParamsBuffer: Buffer | null;
-  bloomBlurVParamsBuffer: Buffer | null;
+  bloomDownsampleParamsBuffer: Buffer | null;
+  bloomUpsampleParamsBuffer: Buffer | null;
   bloomCompositeParamsBuffer: Buffer | null;
   ensureBloomResources?: () => void;
   getBloomResources?: () => BloomPersistentBundle | null;
@@ -358,18 +378,6 @@ export interface PerPassResources {
   /** Drain candidate, active, and fence-retiring Bloom generations. */
   drainBloomResources?: () => void;
   inspectBloomResources?: (graph?: CompiledRenderGraphInfo) => BloomInspection;
-  bloomBrightTexture: Texture | null;
-  bloomBrightView: TextureView | null;
-  bloomBrightWidth: number;
-  bloomBrightHeight: number;
-  bloomBlurHTexture: Texture | null;
-  bloomBlurHView: TextureView | null;
-  bloomBlurHWidth: number;
-  bloomBlurHHeight: number;
-  bloomBlurVTexture: Texture | null;
-  bloomBlurVView: TextureView | null;
-  bloomBlurVWidth: number;
-  bloomBlurVHeight: number;
   ssaoCalcPipeline: RhiRenderPipeline | null;
   ssaoBlurPipeline: RhiRenderPipeline | null;
   ssaoBgl: BindGroupLayout | null;
@@ -392,17 +400,15 @@ export interface PerPassResources {
 export interface BloomPersistentBundle {
   readonly scope: DeviceScope;
   readonly generation: number;
-  readonly bloomBrightPipeline: RhiRenderPipeline | null;
-  readonly bloomBlurHPipeline: RhiRenderPipeline | null;
-  readonly bloomBlurVPipeline: RhiRenderPipeline | null;
+  readonly bloomDownsamplePipeline: RhiRenderPipeline | null;
+  readonly bloomUpsamplePipeline: RhiRenderPipeline | null;
   readonly bloomCompositePipeline: RhiRenderPipeline | null;
-  readonly bloomBrightBindGroupLayout: BindGroupLayout | null;
-  readonly bloomBlurBindGroupLayout: BindGroupLayout | null;
+  readonly bloomDownsampleBindGroupLayout: BindGroupLayout | null;
+  readonly bloomUpsampleBindGroupLayout: BindGroupLayout | null;
   readonly bloomCompositeBindGroupLayout: BindGroupLayout | null;
   readonly bloomSampler: Sampler | null;
-  readonly bloomBrightParamsBuffer: Buffer | null;
-  readonly bloomBlurHParamsBuffer: Buffer | null;
-  readonly bloomBlurVParamsBuffer: Buffer | null;
+  readonly bloomDownsampleParamsBuffer: Buffer | null;
+  readonly bloomUpsampleParamsBuffer: Buffer | null;
   readonly bloomCompositeParamsBuffer: Buffer | null;
 }
 
@@ -429,6 +435,8 @@ export interface PipelineState {
   readonly probeInstancesBindGroupLayout?: BindGroupLayout;
   readonly identityInstanceBuffer: Buffer;
   readonly defaultSampler: Sampler;
+  /** Nearest/clamp sampler required by r32float Surface depth input. */
+  readonly surfaceMediumDepthSampler?: Sampler;
   readonly fallbackTextureView: TextureView;
   readonly unlitPipeline: RhiRenderPipeline | null;
   readonly standardPipeline: RhiRenderPipeline | null;
@@ -443,10 +451,16 @@ export interface PipelineState {
   readonly pbrPipelineLayout: PipelineLayout | null;
   /** Dedicated slot-3 layout for scene-index GPU-driven Standard PBR draws. */
   readonly gpuDrivenInstancesBindGroupLayout?: BindGroupLayout | null;
+  /** Direct Surface slot-3 ABI: instances + retained medium frame resources. */
+  readonly surfaceDirectInstancesBindGroupLayout?: BindGroupLayout | null;
   readonly gpuDrivenPbrPipelineLayout?: PipelineLayout | null;
   /** Device-owned shader modules paired with their exact Standard PBR receipts. */
   readonly gpuDrivenPbrPrograms?: ReadonlyMap<string, GpuDrivenPbrProgram>;
   readonly gpuDrivenPbrSkinPipelineLayout?: PipelineLayout | null;
+  /** Clustered group(2) layouts paired with the scene-index slot(3). */
+  readonly gpuDrivenClusterPbrPipelineLayout?: PipelineLayout | null;
+  readonly gpuDrivenClusterPbrSkinPipelineLayout?: PipelineLayout | null;
+  readonly gpuDrivenClusterMeshBindGroupLayout?: BindGroupLayout | null;
   readonly pbrProbePipelineLayout?: PipelineLayout | null;
   readonly hdrpPbrPipelineLayout: PipelineLayout | null;
   readonly hdrpMeshBindGroupLayout?: BindGroupLayout | null;
@@ -595,6 +609,8 @@ export interface _StandardForwardSceneView {
   readonly gpuDrivenSceneMaterialBuffer?: Buffer;
   /** Concrete main-pass draw identities already claimed by the capable GPU lane. */
   readonly gpuDrivenDrawKeys?: ReadonlySet<string>;
+  /** Stable world identities used to construct the claimed draw keys. */
+  readonly gpuDrivenWorldKeys?: readonly number[];
   readonly gpuDrivenShadowViews?: ShadowViewStatePool;
   readonly gpuDrivenShadowBatchProjections?: ReadonlyMap<
     string,
@@ -617,7 +633,11 @@ export interface _StandardForwardSceneView {
   readonly pointsLines: PointsLinesRecordOwner | undefined;
   readonly materialBgAssemblyCache: Map<string, MaterialBgAssemblyCacheEntry>;
   /** Record-stage proof callback; invoked only after a real draw command is encoded. */
-  readonly onRenderableDraw?: (entry: ValidatedRenderable) => void;
+  readonly onRenderableDraw?: (
+    entry: ValidatedRenderable,
+    submeshIndex?: number,
+    receipt?: { readonly lane: 'cpu' | 'gpu'; readonly ready: boolean },
+  ) => void;
   readonly reflectionProbes?: ReflectionProbeRecordState;
   materialUboPayloadCache?: {
     readonly materialSlots: readonly MaterialSnapshot[];

package/src/record/shadow-pass.ts

@@ -82,6 +82,8 @@ export interface GpuDrivenShadowBatch {
   readonly deformation: 'rigid' | 'skin';
   /** Complete binding for this batch, including opaque batches after custom casters. */
   readonly materialGroup: BindGroup;
+  /** Receipt-derived material BG for alpha-mask batches; opaque uses the pass singleton. */
+  readonly alphaMaskMaterialGroup?: BindGroup | undefined;
   readonly vertexBuffer: Buffer;
   readonly indexBuffer?: Buffer | undefined;
   readonly indexFormat?: 'uint16' | 'uint32' | undefined;
@@ -192,6 +194,7 @@ function ensureTypedShadowViewBg(
     );
   }
   const projectorAvailable = pipelineState.projectorAvailable !== false;
+  const lowLimitCloudBindings = !extendedLighting && !projectorAvailable;
   try {
     return getOrCreateFromChain(
       frameState.viewBindGroupCache,
@@ -209,6 +212,9 @@ function ensureTypedShadowViewBg(
             ? [pipelineState.defaultWhiteTextureView, pipelineState.defaultSampler]
             : []),
         pipelineState.pointsLinesViewBuffer ?? pipelineState.viewUniformBuffer,
+        ...(lowLimitCloudBindings
+          ? []
+          : [pipelineState.defaultWhiteTextureView, pipelineState.defaultSampler]),
       ],
       variant,
       () => {
@@ -287,6 +293,24 @@ function ensureTypedShadowViewBg(
                   },
                 ]
               : []),
+            ...(lowLimitCloudBindings
+              ? []
+              : [
+                  {
+                    binding: 16,
+                    resource: {
+                      kind: 'textureView' as const,
+                      value: pipelineState.defaultWhiteTextureView,
+                    },
+                  },
+                  {
+                    binding: 17,
+                    resource: {
+                      kind: 'sampler' as const,
+                      value: pipelineState.defaultSampler,
+                    },
+                  },
+                ]),
           ],
         });
         if (!created.ok) throw created.error;
@@ -786,6 +810,7 @@ function recordGpuDrivenShadowIfPublished(
       visibleBindGroup: projection.visibleBindGroup,
       deformation: projection.deformation,
       materialGroup,
+      ...(batch.key.admission === 'alpha-mask' ? { alphaMaskMaterialGroup: materialGroup } : {}),
       vertexBuffer: projection.mesh.vertexBuffer.handle,
       ...(batch.key.drawKind === 'indexed' && projection.mesh.indexBuffer !== null
         ? {
@@ -1503,7 +1528,12 @@ export function recordShadowCasterDraws(
           : GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST;
         const instancePayload = uniformFallback
           ? shadowInst.transforms
-          : packInstanceStorageBuffer(shadowInst.transforms);
+          : packInstanceStorageBuffer(
+              shadowInst.transforms,
+              entry.source.temporal?.previousInstances?.transforms,
+              shadowInst.generations,
+              entry.source.temporal?.previousInstances?.generations,
+            );
         const requestedBytes = instancePayload.byteLength;
         const cap = runtime.device.limits.maxStorageBufferBindingSize;
         if (!uniformFallback && typeof cap === 'number' && cap > 0 && requestedBytes > cap) {
@@ -1965,7 +1995,11 @@ function ensureGpuDrivenCustomShadowMaterialBg(
   c: _InternalRenderPipelineContext,
   projection: GpuDrivenShadowBatchProjection,
 ): BindGroup {
-  const shaderId = projection.shadowArtifact.material;
+  const shaderId =
+    projection.shadowArtifact.specializationKey ?? projection.shadowArtifact.material;
+  const materialKey = `shadow-material-custom:${shaderId}:${projection.materialEntityKey}:${projection.material.materialHandle ?? -1}:${c.store.materialResourceEpoch}`;
+  const cached = c.materialBgAssemblyCache.get(materialKey);
+  if (cached !== undefined) return cached.bindGroup;
   const fallback = c.pipelineState.skylightFallback;
   if (fallback === null) {
     throw new RhiError({