@forgeax/engine-render 0.1.20 → 0.1.21

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

@@ -28,6 +28,7 @@ import { SPRITE_PREMULTIPLIED_ALPHA_BLEND } from '../materials';
 import { SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET } from '../pbr-pipeline';
 import {
   buildBeginRenderPassDescriptor,
+  standardTopologyVariantSet,
   variantSetFromVertexLayoutProjection,
 } from '../pipeline-spec';
 import type { MaterialSnapshot, SpriteInstancesSnapshot } from '../render-system-extract';
@@ -37,6 +38,7 @@ import {
   defaultViewForUserRegionField,
   entityHasTransparentSubmesh,
   residentTextureView,
+  selectMaterialGroup2,
 } from './main-pass-material';
 import {
   extractEntryResourceHandle,
@@ -208,8 +210,13 @@ export function recordSpritePass(
     ldrSpriteColorView,
     geometryDepthView,
     viewBindGroup,
+    meshBindGroup,
+    hdrpClusterBindGroup,
+    viewBindGroupDynamicOffset = 0,
     splitLdrSprite,
   } = c;
+  const clusteredLighting = c.standardLighting?.kind === 'clustered';
+  const meshGroup2 = clusteredLighting ? hdrpClusterBindGroup : meshBindGroup;
   // The split pass is also used by the no-tone linear-LDR route. That route
   // keeps transparent draws in the graph-owned rgba16float attachment, so
   // sprite shaders must use their linear/HDR fragment entry point even though
@@ -260,7 +267,7 @@ export function recordSpritePass(
         ) as never,
       );
 
-    spritePass.setBindGroup(0, viewBindGroup as BindGroup, [0]);
+    spritePass.setBindGroup(0, viewBindGroup as BindGroup, [viewBindGroupDynamicOffset, 0]);
 
     // feat-20260625-refactor-sprite-as-transparent-mesh M3 / w14 (D-7):
     // sprite PSO resolution migrated from the dedicated boot-time PSO
@@ -376,7 +383,12 @@ export function recordSpritePass(
         spritePremulBlend,
         'triangle-list',
         undefined,
-        undefined,
+        // sprite-lit declares the same Standard capability axes as PBR. The
+        // boot artifact is intentionally the direct compatibility variant,
+        // so a clustered frame must request its explicit Cluster artifact;
+        // otherwise the host binds the unified group(2) while the shader
+        // still reads the now-cleared direct-light headers.
+        standardTopologyVariantSet(c.standardLighting, runtime.device.caps.storageBuffer, false),
         'forward',
         undefined,
         msaaActive ? 4 : 1,
@@ -416,6 +428,7 @@ export function recordSpritePass(
       materialSlotIndices,
       sampleCount,
       resolveMaterialBindGroup,
+      meshGroup2,
     );
 
     if (graphPass === undefined) spritePass.end();
@@ -448,9 +461,9 @@ function recordSpriteTransparentPbrDraws(
     entityKey: number,
     materialWorld: World,
   ) => BindGroup,
+  meshGroup2: BindGroup | null,
 ): void {
-  const { runtime, pipelineState, frameState, bindGroupCounts, validatedOrdered, meshBindGroup } =
-    c;
+  const { runtime, pipelineState, frameState, bindGroupCounts, validatedOrdered } = c;
   const isHdrTarget =
     c.tonemapActive || transparentPassColorFormat(c, pipelineState) === 'rgba16float';
   let lastPbrSubPipelineHandle: typeof pipelineState.unlitPipeline = null;
@@ -484,7 +497,6 @@ function recordSpriteTransparentPbrDraws(
       spritePass.setIndexBuffer(entry.mesh.indexBuffer.handle, entry.mesh.indexFormat);
       lastPbrSubIndexBuffer = entry.mesh.indexBuffer;
     }
-    spritePass.setBindGroup(2, meshBindGroup as BindGroup, [i * MESH_PER_ENTITY_STRIDE]);
     // Identity instance BG (instanceCount=1); reuse the per-entity cache.
     const identityInstBg: BindGroup = getOrCreatePerEntity(
       frameState.instancesBgPerEntity,
@@ -512,9 +524,11 @@ function recordSpriteTransparentPbrDraws(
     );
     spritePass.setBindGroup(3, identityInstBg);
 
-    const subVariantSet = frameState.isHdrpActive
-      ? ''
-      : 'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true';
+    const subVariantSet = standardTopologyVariantSet(
+      c.standardLighting,
+      runtime.device.caps.storageBuffer,
+      entry.mesh.layoutProjection.attributes.some((attribute) => attribute.key === 'color'),
+    );
     const projectionVariantSetResult = variantSetFromVertexLayoutProjection(
       entry.mesh.layoutProjection,
       subVariantSet,
@@ -535,21 +549,8 @@ function recordSpriteTransparentPbrDraws(
       if (submeshMaterial.transparent !== true) continue;
       const smShaderId = submeshMaterial.materialShaderId;
       if (smShaderId === undefined) continue;
-
-      // Bind the per-submesh material BG first (mirrors the geometry pass
-      // order), then resolve the PSO; a first-frame async-compile miss skips
-      // only the draw, not the BG (one transient frame, PSO flows in next).
-      const materialSlot = materialSlotIndices[i]?.[matSlotIdx] ?? materialSlotIndices[i]?.[0] ?? 0;
-      const subBg = resolveMaterialBindGroup(
-        materialSlot,
-        submeshMaterial,
-        entry.source.entityKey,
-        entry.world ?? c.world,
-      );
-      spritePass.setBindGroup(1, subBg, [materialSlot * MATERIAL_PER_ENTITY_STRIDE]);
-
-      const subPipeline =
-        runtime.getMaterialShaderPipeline?.(
+      const subPipelineEntry =
+        c.runtime.getMaterialShaderPipelineEntry?.(
           smShaderId,
           isHdrTarget,
           submeshMaterial.renderState,
@@ -566,7 +567,25 @@ function recordSpriteTransparentPbrDraws(
           undefined,
           entry.mesh.layoutProjection,
         ) ?? null;
-      if (subPipeline === null) continue;
+      if (subPipelineEntry === null) continue;
+      const submeshContract = subPipelineEntry.group2Contract;
+      const submeshGroup2 = selectMaterialGroup2(meshGroup2, c.meshBindGroup, submeshContract);
+      if (submeshGroup2 === null) continue;
+      spritePass.setBindGroup(2, submeshGroup2, [i * MESH_PER_ENTITY_STRIDE]);
+
+      // Bind the per-submesh material BG first (mirrors the geometry pass
+      // order), then resolve the PSO; a first-frame async-compile miss skips
+      // only the draw, not the BG (one transient frame, PSO flows in next).
+      const materialSlot = materialSlotIndices[i]?.[matSlotIdx] ?? materialSlotIndices[i]?.[0] ?? 0;
+      const subBg = resolveMaterialBindGroup(
+        materialSlot,
+        submeshMaterial,
+        entry.source.entityKey,
+        entry.world ?? c.world,
+      );
+      spritePass.setBindGroup(1, subBg, [materialSlot * MATERIAL_PER_ENTITY_STRIDE]);
+
+      const subPipeline = subPipelineEntry.pipeline;
 
       if (lastPbrSubPipelineHandle !== subPipeline) {
         spritePass.setPipeline(subPipeline);
@@ -930,6 +949,16 @@ function recordSpriteEntityDraws(
     spriteInstanceBuffer = _si.buffer;
     spriteInstanceCount = _si.count;
 
+    // sprite-lit's clustered variant declares the unified Standard group(2)
+    // contract, while the regular sprite variants keep the direct mesh
+    // contract. Select the resource from the same capability axis used to
+    // request the pipeline; binding the ordinary mesh group to the clustered
+    // sprite-lit pipeline is rejected by WebGPU before the draw is recorded.
+    const spriteGroup2 =
+      entityShaderId === 'forgeax::sprite-lit' && c.standardLighting?.kind === 'clustered'
+        ? c.hdrpClusterBindGroup
+        : meshBindGroup;
+
     // M3 / w12: LDR sprite split pass per-entity instances BG cache.
     // Same pattern as #7.
     const spriteInstancesBg: BindGroup = getOrCreatePerEntity(
@@ -957,7 +986,7 @@ function recordSpriteEntityDraws(
       bindGroupCounts,
     );
 
-    spritePass.setBindGroup(2, meshBindGroup as BindGroup, [i * MESH_PER_ENTITY_STRIDE]);
+    spritePass.setBindGroup(2, spriteGroup2 as BindGroup, [i * MESH_PER_ENTITY_STRIDE]);
 
     // Per-entity sprite material bind group: same standard PBR user-region
     // layout as in the geometry pass sprite branch + Skylight merged entries

package/src/record/main-pass.ts

@@ -9,10 +9,13 @@ import {
 import type { Handle, PassKind, PassSelector } from '@forgeax/engine-types';
 import { createHdrpUnifiedBindGroup, getOrCreateHdrpBuffers } from '../hdrp-buffers';
 import { getOrCreateIblCache } from '../ibl/IblPipelineCache';
-import { buildBeginRenderPassDescriptor } from '../pipeline-spec';
+import type { SkylightBindGroupResources } from '../ibl/skylight-bind-group';
+import { buildBeginRenderPassDescriptor, standardTopologyBindGroupReady } from '../pipeline-spec';
 import { POINTS_LINES_MATERIAL_SHADER_ID } from '../points-lines/record';
+import type { ReflectionProbeSelectionResult } from '../reflection/projection';
 import type { RenderRecordPhase } from '../render-contract';
 import type { MaterialSnapshot } from '../render-system-extract';
+import { resolveReflectionProbeBinding } from './frame-lighting';
 import { recordGeometryDraws } from './main-pass-geometry';
 import {
   applyMaterialTextureUvScales,
@@ -31,6 +34,12 @@ import {
   buildMatchedRenderableIndices,
 } from './shadow-pass';
 
+export function standardReflectionProbeIndex(
+  selection: ReflectionProbeSelectionResult,
+): number | undefined {
+  return resolveReflectionProbeBinding(selection).probeIndex;
+}
+
 const ZERO_SKYLIGHT_PAYLOAD = new Float32Array([0, 0, 0, 0, 0, 0, 0, 1]);
 
 export type MainPassOptions = {
@@ -114,6 +123,7 @@ export function recordMainPass(
     geometryDepthView,
     validatedOrdered,
     viewBindGroup,
+    viewBindGroupDynamicOffset = 0,
     meshBindGroup,
     frameState,
     bindGroupCounts,
@@ -161,14 +171,26 @@ export function recordMainPass(
   // copyExternalImageToTexture path (w16) is the sole route. The branch exists
   // so the AC-09 two-path reserved hook is code-review-verifiable, not a TODO.
   const videoHighPerfAvailable = probeVideoHighPerfUpload(runtime.device);
-  // feat-20260609-hdrp-cluster-fragment-ggx M4 / w16: HDRP active swaps the
+  // The prepared Standard topology is the frame authority. Do not infer the
+  // shader lane from a resource that may be absent after a failed rebuild: a
+  // clustered frame with no unified group must fail closed, never fall back to
+  // a direct-lighting shader with an incompatible group(2) contract.
+  const clusteredLighting = c.standardLighting?.kind === 'clustered';
+  // A clustered topology still needs the unified group for every actual
+  // material draw.  A camera-only/clear frame has no group(2) consumer yet;
+  // treating that harmless absence as a frame error would make the full
+  // clustered ABI incompatible with valid zero-renderable frames.
+  const clusteredBindGroupMissing =
+    validatedOrdered.length > 0 &&
+    !standardTopologyBindGroupReady(c.standardLighting, hdrpClusterBindGroup);
+  // Standard clustered lighting swaps the
   // group(2) bindGroup for the unified 7-entry layout (mesh SSBO at binding 0
   // + cluster 4 buffer at bindings 3..6). The dynamic offset
   // (`i * MESH_PER_ENTITY_STRIDE`) stays valid because the unified BGL binds
   // the SAME mesh SSBO at binding 0; the cluster-forward shader reads the
   // cluster bindings off the rest of the layout. Plan D-1 (URP path zero
-  // change) is preserved — when `!isHdrpActive` the URP `meshBindGroup`
-  // path runs verbatim.
+  // change) is preserved — when clustered lighting is not selected the
+  // ordinary mesh bind group path runs verbatim.
   // feat-20260612-hdrp-ssao wiring fix: when the HDRP forward pass resolved a
   // real `ssaoBlurred` view (stashed on ctx by the pass execute closure), build
   // the unified group(2) bind group with that view at binding 7 so fs_main reads
@@ -178,11 +200,7 @@ export function recordMainPass(
   // 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.
   let hdrpSsaoBindGroup: BindGroup | null = null;
-  if (
-    frameState.isHdrpActive &&
-    hdrpClusterBindGroup !== null &&
-    c.hdrpSsaoBlurredView !== undefined
-  ) {
+  if (clusteredLighting && hdrpClusterBindGroup !== null && c.hdrpSsaoBlurredView !== undefined) {
     const hdrpBuffers = getOrCreateHdrpBuffers(
       runtime,
       frameState.installedPipelineConfig?.clusterGrid,
@@ -196,10 +214,9 @@ export function recordMainPass(
       );
     }
   }
-  const meshGroup2: BindGroup | null =
-    frameState.isHdrpActive && hdrpClusterBindGroup !== null
-      ? (hdrpSsaoBindGroup ?? hdrpClusterBindGroup)
-      : meshBindGroup;
+  const meshGroup2: BindGroup | null = clusteredLighting
+    ? (hdrpSsaoBindGroup ?? hdrpClusterBindGroup)
+    : meshBindGroup;
   // ── Geometry (main colour) pass ──────────────────────────────────
   // D-2: tracks whether the geometry pass was explicitly ended inside
   // the `if (validatedOrdered.length > 0)` block (sprite split path),
@@ -273,7 +290,17 @@ export function recordMainPass(
           })),
         };
 
-  if (validatedOrdered.length > 0) {
+  if (clusteredBindGroupMissing) {
+    runtime.errorRegistry.fire(
+      new RhiError({
+        code: 'webgpu-runtime-error',
+        expected: 'clustered Standard frame has a unified group(2) BindGroup',
+        hint: 'repair the clustered buffer/layout admission before retrying the frame; direct URP fallback is unsafe',
+      }),
+    );
+  }
+
+  if (validatedOrdered.length > 0 && !clusteredBindGroupMissing) {
     // feat-20260518-pbr-direct-lighting-mvp M5 / w22.10 (D-4 + D-9 +
     // AC-07 std140): per-entity material slice grew from 32 B (legacy
     // baseColor:vec4 + metallic + roughness + 8B padding) to 48 B
@@ -432,6 +459,35 @@ export function recordMainPass(
       materialSlice: MATERIAL_SLICE,
       videoHighPerfAvailable,
       skylightResources,
+      resolveRenderTargetTextureSource: runtime.resolveRenderTargetTextureSource,
+      resolveReflectionProbeResources: (materialWorld, entityKey) => {
+        const reflectionProbes = c.reflectionProbes;
+        if (reflectionProbes === undefined) return undefined;
+        const selection = reflectionProbes.selections.get(`${materialWorld.identity}:${entityKey}`);
+        if (selection === undefined) return undefined;
+        const binding = resolveReflectionProbeBinding(selection, reflectionProbes.table);
+        if (binding.useSkylight || binding.probeIndex === undefined) return undefined;
+        const row = reflectionProbes.table.rows.find(
+          (candidate) => candidate.index === binding.probeIndex,
+        );
+        if (
+          row?.filteredView === undefined ||
+          row.sampler === undefined ||
+          row.uniformBuffer === undefined
+        ) {
+          return undefined;
+        }
+        const probeResources: SkylightBindGroupResources = {
+          irradianceView: skylightResources.irradianceView,
+          irradianceSampler: skylightResources.irradianceSampler,
+          prefilterView: row.filteredView,
+          prefilterSampler: row.sampler,
+          brdfLutView: skylightResources.brdfLutView,
+          brdfLutSampler: skylightResources.brdfLutSampler,
+          intensityBuffer: row.uniformBuffer,
+        };
+        return probeResources;
+      },
       materialBgShared: frameState.materialBgShared,
       materialBgAssemblyCache: c.materialBgAssemblyCache,
       bindGroupCounts,
@@ -614,7 +670,7 @@ export function recordMainPass(
           buildPerSubmeshMaterialBg(material, entityKey, materialWorld))
         : buildPerSubmeshMaterialBg(material, entityKey, materialWorld);
 
-    pass.setBindGroup(0, viewBindGroup as BindGroup, [0]);
+    pass.setBindGroup(0, viewBindGroup as BindGroup, [viewBindGroupDynamicOffset, 0]);
 
     // Track which (mesh-vertex-buffer, mesh-index-buffer, pipeline) combo
     // was last bound so consecutive entities sharing the same combo skip

package/src/record/render-context.ts

@@ -11,6 +11,7 @@ import type {
   PipelineLayout,
   Result,
   RhiCanvasContext,
+  RhiCommandEncoder,
   RhiDevice,
   RenderPipeline as RhiRenderPipeline,
   Sampler,
@@ -41,10 +42,20 @@ import {
 import type { SkylightFallback } from '../ibl/skylight-bind-group';
 import type { BloomInspection } from '../inspection-types';
 import type { HealthListenerRegistry, RhiErrorListenerRegistry } from '../lifecycle';
+import type { PipelineGroup2Contract } from '../pbr-pipeline';
+import type { StandardTopologyInputValue } from '../pipeline/standard-lighting/topology';
 import type { StandardProfile } from '../pipeline/standard-profile';
 import type { PipelineBuilderShaderModuleFactory } from '../pipeline-builder';
 import type { PointsLinesInspection } from '../points-lines/inspection';
 import type { PointsLinesRecordPlan } from '../points-lines/record';
+import type { ReflectionProbeTable } from '../reflection/gpu-table';
+import type { ReflectionProbeSelectionResult } from '../reflection/projection';
+import type { GpuPassTimingReason } from './gpu-pass-timing/errors';
+import type {
+  GpuPassTimingCapture,
+  GpuPassTimingFrameIdentity,
+  GpuPassTimingSession,
+} from './gpu-pass-timing/session';
 
 export interface PointsLinesRecordSubmission {
   readonly plan: PointsLinesRecordPlan;
@@ -53,6 +64,18 @@ export interface PointsLinesRecordSubmission {
   readonly layoutProjection: VertexLayoutProjection;
 }
 
+export interface ReflectionProbeRecordState {
+  readonly table: ReflectionProbeTable;
+  readonly selections: ReadonlyMap<string, ReflectionProbeSelectionResult>;
+  readonly graph: import('./typed-frame-graph').ReflectionProbeGraphState;
+  readonly completeSubmission: (submitted: boolean, completed?: Promise<unknown>) => void;
+}
+
+export interface MaterialShaderPipelineEntry {
+  readonly pipeline: RhiRenderPipeline;
+  readonly group2Contract: PipelineGroup2Contract;
+}
+
 import type {
   RenderDebugOverlay,
   RenderPipelineContext,
@@ -66,6 +89,8 @@ import type {
   SkylightSnapshot,
 } from '../render-system-extract';
 import type { SkinPaletteAllocator } from '../systems/skin-palette-allocator';
+import type { RenderTarget } from '../targets/contracts';
+import type { RenderTargetPhysical } from '../targets/physical';
 import type {
   BindGroupCounts,
   BloomFrameReceipts,
@@ -102,6 +127,23 @@ export interface RenderSystemRuntime {
     shaderModuleMode?: RenderFeatureShaderModuleMode,
     layoutKindOverride?: 'pbr' | 'pbr-skin',
   ) => RhiRenderPipeline | null;
+  readonly getMaterialShaderPipelineEntry?: (
+    materialShaderId: string,
+    isHdr: boolean,
+    renderState?: MaterialRenderState,
+    topology?: PrimitiveTopology,
+    indexFormat?: 'uint16' | 'uint32',
+    variantSet?: string,
+    passKind?: PassKind,
+    meshAttributes?: VertexAttributeMap,
+    sampleCount?: number,
+    colorFormatOverride?: GPUTextureFormat,
+    shaderUvSetCount?: number,
+    depthFormatOverride?: GPUTextureFormat | null,
+    vertexLayout?: string,
+    vertexLayoutProjection?: VertexLayoutProjection,
+    shaderModuleMode?: RenderFeatureShaderModuleMode,
+  ) => MaterialShaderPipelineEntry | null;
   readonly getMaterialShaderBindingContract?: (
     materialShaderId: string,
   ) => 'group-0' | 'group-0-resource' | 'view-only' | 'view-and-scene-depth' | 'render-material';
@@ -116,10 +158,15 @@ export interface RenderSystemRuntime {
     id: string,
     bgl: BindGroupLayout,
     colorFormat: GPUTextureFormat,
+    entry?: import('../fullscreen-post-process-pass').PostProcessShaderEntry,
   ) => RhiRenderPipeline | null;
   readonly clearPostProcessPipelineCache?: (id: string) => void;
   readonly invalidateShaderModule?: (label: string) => void;
   readonly dynamicTextureStore?: DynamicTextureStore | undefined;
+  /** Resolves a render-target source to the active generation-owned GPU view. */
+  readonly resolveRenderTargetTextureSource?: (
+    source: import('../targets/contracts').RenderTargetTextureSource,
+  ) => import('../targets/material-source').RenderTargetMaterialSourceBinding | undefined;
 }
 
 /** Renderer-owned bridge from retained Points/Lines facts into main geometry. */
@@ -231,6 +278,8 @@ export interface BloomPersistentBundle {
 }
 
 export interface PipelineState {
+  /** Device that owns every opaque handle in this pipeline state. */
+  readonly device: RhiDevice;
   readonly meshes: ReadonlyMap<number, MeshGpuHandles>;
   readonly format: TextureFormat;
   readonly colorAttachmentFormat: TextureFormat;
@@ -263,6 +312,8 @@ export interface PipelineState {
   readonly hdrpClusterMembershipBindGroupLayout: BindGroupLayout | null;
   readonly pbrSkinPipelineLayout: PipelineLayout | null;
   readonly pbrSkinMeshBindGroupLayout: BindGroupLayout | null;
+  readonly hdrpSkinPipelineLayout: PipelineLayout | null;
+  readonly hdrpSkinMeshBindGroupLayout: BindGroupLayout | null;
   readonly skinPaletteAllocator: SkinPaletteAllocator | null;
   readonly defaultWhiteTextureView: TextureView;
   readonly defaultNormalTextureView: TextureView;
@@ -280,6 +331,12 @@ export interface RenderSystemInternals extends RenderSystemRuntime {
   readonly standardPipeline: RenderFrameState['activePipeline'];
   readonly featureHost?: RenderFeatureHost | undefined;
   readonly shaderModuleFactory?: PipelineBuilderShaderModuleFactory;
+  readonly createShaderModule?: (
+    device: import('@forgeax/engine-rhi').RhiDevice,
+    descriptor: { readonly code: string; readonly label?: string },
+  ) => Promise<
+    Result<import('@forgeax/engine-rhi').ShaderModule, import('@forgeax/engine-rhi').RhiError>
+  >;
   /** Optional handle-first factory for feature-owned generated shader programs. */
   readonly immediateShaderModuleFactory?: PipelineBuilderShaderModuleFactory;
   readonly profiler?: Profiler | undefined;
@@ -305,6 +362,16 @@ export interface RenderSystemInternals extends RenderSystemRuntime {
         label: string,
       ) => RhiRenderPipeline | null)
     | undefined;
+  gpuPassTimingSession?: GpuPassTimingSession | undefined;
+  gpuPassTimingCapture?: GpuPassTimingCapture | undefined;
+  gpuPassTimingSubmittedWork?: Promise<void> | undefined;
+  gpuPassTimingFrameIdentity?: GpuPassTimingFrameIdentity | undefined;
+  gpuPassTimingBeginReason?: GpuPassTimingReason | undefined;
+  readonly getRenderTargetPhysical?: (target: RenderTarget) => RenderTargetPhysical | undefined;
+  readonly encodeRenderTargetReadbacks?: (
+    encoder: RhiCommandEncoder,
+    faces?: readonly number[],
+  ) => void;
   /** Composed renderer utility sources installed atomically at build-ready. */
   volumetricFogShaders?: VolumetricFogShaderSources | undefined;
 }
@@ -318,6 +385,8 @@ export interface _StandardForwardSceneView {
   readonly validated: readonly ValidatedRenderable[];
   readonly validatedOrdered: readonly ValidatedRenderable[];
   readonly viewBindGroup: BindGroup | null;
+  /** Dynamic View-UBO slot used by auxiliary cube/probe face cameras. */
+  readonly viewBindGroupDynamicOffset?: number;
   readonly meshBindGroup: BindGroup | null;
   readonly frameState: RenderFrameState;
   readonly dispatchCounts: DispatchCounts;
@@ -340,6 +409,8 @@ export interface _StandardForwardSceneView {
   readonly dispatch: readonly DispatchEntry[];
   readonly hdrpClusterBindGroup: BindGroup | null;
   readonly hdrpClusterMembershipBindGroup: BindGroup | null;
+  /** Prepared Standard lighting declaration accepted by this graph frame. */
+  readonly standardLighting?: StandardTopologyInputValue;
   readonly foldDispatchPlan: FoldDispatchPlan | null;
   readonly materialSlotIndices: readonly (readonly number[])[];
   readonly materialSlots: readonly MaterialSnapshot[];
@@ -347,6 +418,7 @@ export interface _StandardForwardSceneView {
   readonly materialSlotCount: number;
   readonly pointsLines: PointsLinesRecordOwner | undefined;
   readonly materialBgAssemblyCache: Map<string, MaterialBgAssemblyCacheEntry>;
+  readonly reflectionProbes?: ReflectionProbeRecordState;
   materialUboPayloadCache?: {
     readonly materialSlots: readonly MaterialSnapshot[];
     readonly materialSlotCount: number;

package/src/record/shadow-pass.ts

@@ -18,6 +18,8 @@ import { assembleMaterialWithSkylightEntries } from '../ibl/skylight-bind-group'
 import type { InstanceBufferCacheEntry } from '../instance-buffer-cache';
 import {
   buildPbrMaterialUserRegionEntries,
+  createPbrSkinMeshBindGroupEntries,
+  pbrSkinMeshDynamicOffsets,
   SHADOW_CASTER_SHADER_ID,
   shadowCasterVariantSet,
 } from '../pbr-pipeline';
@@ -290,27 +292,12 @@ function skinnedShadowMeshBindGroup(
       const created = c.runtime.device.createBindGroup({
         label: 'shadow-pbr-skin-mesh-bg',
         layout,
-        entries: [
-          {
-            binding: 0,
-            resource: {
-              kind: 'buffer',
-              value: {
-                buffer: c.pipelineState.meshStorageBuffer.buffer,
-                size: c.runtime.device.caps.storageBuffer
-                  ? MESH_SSBO_BYTES
-                  : MESH_UBO_FULL_ARRAY_BYTES,
-              },
-            },
-          },
-          {
-            binding: 1,
-            resource: {
-              kind: 'buffer',
-              value: { buffer: skin.buffer, size: allocator.bindingWindowBytes },
-            },
-          },
-        ],
+        entries: createPbrSkinMeshBindGroupEntries(
+          c.pipelineState.meshStorageBuffer.buffer,
+          c.runtime.device.caps.storageBuffer ? MESH_SSBO_BYTES : MESH_UBO_FULL_ARRAY_BYTES,
+          skin.buffer,
+          allocator.bindingWindowBytes,
+        ),
       });
       if (!created.ok) throw created.error;
       return created.value;
@@ -338,7 +325,7 @@ export function encodeDirectionalShadowPass(
   c.frameState.directionalShadowCacheRecorded = true;
   pass.setViewport(viewport.x, viewport.y, viewport.w, viewport.h, 0, 1);
   pass.setPipeline(pipeline);
-  pass.setBindGroup(0, viewBg, [0]);
+  pass.setBindGroup(0, viewBg, [0, 0]);
   pass.setBindGroup(1, materialBg, [0]);
   recordShadowCasterDraws(
     c,
@@ -368,7 +355,7 @@ export function encodePointShadowPass(
   const materialBg = ensureSpotShadowMaterialBg(c);
   if (pipeline === null || viewBg === null || materialBg === null) return;
   pass.setPipeline(pipeline);
-  pass.setBindGroup(0, viewBg, [0]);
+  pass.setBindGroup(0, viewBg, [0, 0]);
   pass.setBindGroup(1, materialBg, [0]);
   recordShadowCasterDraws(
     c,
@@ -416,7 +403,7 @@ export function encodeSpotShadowPass(
     1,
   );
   pass.setPipeline(pipeline);
-  pass.setBindGroup(0, viewBg, [0]);
+  pass.setBindGroup(0, viewBg, [0, 0]);
   pass.setBindGroup(1, materialBg, [0]);
   // Reuse the shared caster recorder. The compact spot-only loop used to
   // depend on instance bindings created by a directional pass, so a scene
@@ -594,10 +581,11 @@ function recordShadowCasterDraws(
     if (entry.source.skin !== undefined) {
       const skinMeshBindGroup = skinnedShadowMeshBindGroup(c, entry);
       if (skinMeshBindGroup === null) continue;
-      shadowPass.setBindGroup(2, skinMeshBindGroup, [
-        i * MESH_PER_ENTITY_STRIDE,
-        entry.source.skin.byteOffset,
-      ]);
+      shadowPass.setBindGroup(
+        2,
+        skinMeshBindGroup,
+        pbrSkinMeshDynamicOffsets(i * MESH_PER_ENTITY_STRIDE, entry.source.skin.byteOffset),
+      );
     } else {
       shadowPass.setBindGroup(2, shadowMeshBindGroup, [i * MESH_PER_ENTITY_STRIDE]);
     }
@@ -606,6 +594,7 @@ function recordShadowCasterDraws(
     let shadowInstanceBuffer: Buffer = pipelineState.identityInstanceBuffer;
     let shadowInstanceCount = 1;
     const shadowInst = entry.source.instances;
+    if (shadowInst?.instanceCount === 0) continue;
     if (shadowInst !== undefined) {
       const uniformFallback = runtime.device.caps.storageBuffer === false;
       // Over-cap uniform fallback can't fit the per-instance window — bind

package/src/record/skybox-post-pass.ts

@@ -2,6 +2,8 @@ import type { ResolveContext } from '@forgeax/engine-render-graph';
 import { RhiError, type RhiRenderPassEncoder, type TextureView } from '@forgeax/engine-rhi';
 import { toShared } from '@forgeax/engine-types';
 import { buildBeginRenderPassDescriptor } from '../pipeline-spec';
+import { FXAA_POST_PROCESS_ID } from '../render-contract';
+import { resolveOutputDither } from '../render-pipeline';
 import type { BloomFrameReceipts } from './frame-snapshot';
 import { getOrCreateFromChain } from './mesh-ssbo';
 import type { _InternalRenderPipelineContext } from './render-context';
@@ -579,19 +581,29 @@ export function recordFxaaPass(
     fxaaActive &&
     pipelineState.perPassResources.fxaaPipeline !== null &&
     pipelineState.perPassResources.fxaaBindGroupLayout !== null &&
-    pipelineState.perPassResources.fxaaSampler !== null
+    pipelineState.perPassResources.fxaaSampler !== null &&
+    runtime.getPostProcessParamsBuffer !== undefined
   ) {
     const inputView = resolve.resolve('ldrColor') as TextureView | undefined;
     if (inputView === undefined) return;
 
-    // Compose the 2-entry FXAA BindGroup (input texture + sampler). The
+    const fxaaParams = runtime.getPostProcessParamsBuffer(FXAA_POST_PROCESS_ID);
+    if (fxaaParams === undefined) return;
+    const params = new Float32Array(4);
+    params[0] = resolveOutputDither(c.frameState.installedPipelineConfig) ? 1 : 0;
+    const paramsWrite = runtime.device.queue.writeBuffer(fxaaParams, 0, params);
+    if (!paramsWrite.ok) throw paramsWrite.error;
+
+    // Compose the 3-entry FXAA BindGroup (input texture + sampler + params).
     // graph view identity changes when the graph reallocates on resize, so
-    // the identity-keyed cache rebuilds against the live target.
+    // the identity-keyed cache rebuilds against the live target. The params
+    // buffer is also a key so a device recovery cannot retain a bind group
+    // pointing at the retired resource.
     const fxaaBglLayout = pipelineState.perPassResources.fxaaBindGroupLayout;
     const fxaaSampler = pipelineState.perPassResources.fxaaSampler;
     const fxaaBg = getOrCreateFromChain(
       c.frameState.postProcessBgCache,
-      [inputView],
+      [inputView, fxaaParams],
       'fxaa',
       () => {
         const fxaaBgRes = runtime.device.createBindGroup({
@@ -609,6 +621,10 @@ export function recordFxaaPass(
               binding: 1,
               resource: { kind: 'sampler', value: fxaaSampler },
             },
+            {
+              binding: 2,
+              resource: { kind: 'buffer', value: { buffer: fxaaParams } },
+            },
           ],
         });
         if (!fxaaBgRes.ok) throw fxaaBgRes.error;