@forgeax/engine-render 0.1.2

package/src/record/main-pass.ts

@@ -0,0 +1,588 @@
+import { probeVideoHighPerfUpload } from '@forgeax/engine-graphics-extras';
+import {
+  type BindGroup,
+  RhiError,
+  type RhiRenderPassEncoder,
+  type TextureView,
+} from '@forgeax/engine-rhi';
+import type { Handle, PassKind, PassSelector } from '@forgeax/engine-types';
+import { environmentConsumerSnapshot } from '../environment/generation';
+import { isEnvironmentGpuBundle } from '../environment/gpu-bundle';
+import { createHdrpUnifiedBindGroup, getOrCreateHdrpBuffers } from '../hdrp-buffers';
+import { getOrCreateIblCache } from '../ibl/IblPipelineCache';
+import { buildBeginRenderPassDescriptor } from '../pipeline-spec';
+import type { _InternalRenderPipelineContext } from '../render-pipeline-context';
+import { MATERIAL_PER_ENTITY_STRIDE } from '../render-system';
+import type { MaterialSnapshot } from '../render-system-extract';
+import type { RenderRecordPhase } from '../renderer';
+import { recordGeometryDraws } from './main-pass-geometry';
+import {
+  buildPerSubmeshMaterialBg as buildPerSubmeshMaterialBgImpl,
+  detectNineSliceScaleTooSmall,
+  type PerSubmeshMaterialBgDeps,
+  residentTextureView,
+  writeMaterialSnapshotPayload,
+} from './main-pass-material';
+import { recordSpritePass } from './main-pass-sprite-draws';
+import { buildMatchedRenderableIndices } from './shadow-pass';
+
+const ZERO_SKYLIGHT_PAYLOAD = new Float32Array([0, 0, 0, 0, 0, 0, 0, 1]);
+
+export type MainPassOptions = {
+  readonly colorViews?: readonly (TextureView | null)[];
+  readonly colorFormats?: readonly GPUTextureFormat[];
+  readonly depthView?: TextureView | null;
+  readonly passKind?: PassKind;
+  readonly clearColor?: readonly [number, number, number, number];
+};
+
+/**
+ * feat-20260529-rendergraph-pass-abstraction M4 / w13b: main forward
+ * (geometry) pass recording, extracted verbatim from recordFrame. Uses the
+ * SHARED frame encoder (c.encoder); the geometry + optional LDR sprite-split
+ * sub-pass write into geometryColorView (HDR target or swap-chain view).
+ * Driven by the render-graph 'main' pass execute closure.
+ */
+export function recordMainPass(
+  c: _InternalRenderPipelineContext,
+  selector?: PassSelector,
+  options?: MainPassOptions,
+  graphPass?: RhiRenderPassEncoder,
+): void {
+  const {
+    runtime,
+    world,
+    store,
+    pipelineState,
+    encoder,
+    clear,
+    geometryColorView,
+    geometryDepthView,
+    validatedOrdered,
+    viewBindGroup,
+    meshBindGroup,
+    frameState,
+    bindGroupCounts,
+    skylight,
+    skylightCount,
+    skyboxActive,
+    splitLdrSprite,
+    msaaActive,
+    geometryColorResolveView,
+    dispatch,
+    hdrpClusterBindGroup,
+    materialSlotIndices,
+    materialSlots,
+    materialSlotOwners,
+    materialSlotCount,
+  } = c;
+  // bug-20260615 M3 / m3-1: sampleCount is threaded through every
+  // getMaterialShaderPipeline call site so the cache key / builder
+  // disambiguate count=1 vs count=4 PSOs. Derived from the per-camera
+  // msaaActive boolean (already on the context).
+  const sampleCount = msaaActive ? 4 : 1;
+  const passKind = options?.passKind ?? 'forward';
+  const colorViews = options?.colorViews ?? [geometryColorView];
+  const colorFormats = options?.colorFormats ?? [
+    (c.tonemapActive ? 'rgba16float' : pipelineState.colorAttachmentFormat) as GPUTextureFormat,
+  ];
+  const targetDepthView = options?.depthView ?? geometryDepthView;
+  const clearColor = options?.clearColor ?? clear;
+  // feat-20260623-world-space-video-asset M4 / w17 (D-2 / AC-09): high-perf
+  // GPUExternalTexture upload availability for video sources, resolved by the
+  // explicit RhiCaps-based capability probe. The probe checks
+  // backendKind==='webgpu' AND `importExternalTexture` method presence; the
+  // latter is absent today (OOS-5), so this is false and the general
+  // 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
+  // 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.
+  // 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
+  // the actual occlusion factor instead of the 1x1 white fallback. The default
+  // `hdrpClusterBindGroup` (built ahead of graph.execute) always carries the
+  // 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.
+  let hdrpSsaoBindGroup: BindGroup | null = null;
+  if (
+    frameState.isHdrpActive &&
+    hdrpClusterBindGroup !== null &&
+    c.hdrpSsaoBlurredView !== undefined
+  ) {
+    const hdrpBuffers = getOrCreateHdrpBuffers(
+      runtime,
+      frameState.installedPipelineConfig?.clusterGrid,
+    );
+    if (hdrpBuffers !== null) {
+      hdrpSsaoBindGroup = createHdrpUnifiedBindGroup(
+        runtime,
+        hdrpBuffers,
+        pipelineState.meshStorageBuffer.buffer,
+        { enabled: true, ssaoBlurredView: c.hdrpSsaoBlurredView },
+      );
+    }
+  }
+  const meshGroup2: BindGroup | null =
+    frameState.isHdrpActive && hdrpClusterBindGroup !== null
+      ? (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),
+  // to avoid a double-end at the unconditional `pass.end()` below.
+  let geometryPassEnded = false;
+  // feat-20260531-skybox-env-background M2 / w8: condition main colour
+  // loadOp on skyboxActive (AC-05). When skybox is active, the skybox
+  // pass writes the far plane + cubemap colour to hdrColor before main;
+  // main must load (not clear) to composite geometry on top. Depth
+  // loadOp stays 'clear' -- skybox does not write depth, so main's
+  // depth test naturally covers skybox pixels with foreground geometry.
+  const mainColorLoadOp = skyboxActive ? 'load' : 'clear';
+  // feat-20260604 M2 / w9-w10: MSAA resolve placement. When MSAA is active the
+  // geometry pass writes a count=4 multisample target. The resolve to the
+  // single-sample output (LDR swap-chain view / HDR hdrColor) happens at the
+  // LAST pass that writes that multisample target: the main pass itself when
+  // there is no LDR sprite split, or the sprite sub-pass end when there is
+  // (F-1 -- geometry + sprites share one multisample texture; resolving at the
+  // main pass would drop the sprites drawn after). The sprite sub-pass is
+  // LDR-only, so under HDR the main pass always resolves.
+  const mainPassResolves =
+    passKind === 'forward' && msaaActive && geometryColorResolveView !== null && !splitLdrSprite;
+  // forward main pass: depth24plus-stencil8 auto-emits stencil ops via the
+  // helper's stencil-op gate (plan-strategy M4 R3/R5 stencil-op SSOT).
+  // mainColorLoadOp toggles between 'clear' and 'load' (skyboxActive case).
+  const pass: RhiRenderPassEncoder =
+    graphPass ??
+    encoder.beginRenderPass(
+      buildBeginRenderPassDescriptor(
+        {
+          colorFormats,
+          depthFormat: 'depth24plus-stencil8',
+          sampleCount: msaaActive ? 4 : 1,
+        },
+        {
+          colorViews,
+          depthView: targetDepthView,
+          ...(mainPassResolves ? { resolveTargets: [geometryColorResolveView] } : {}),
+        },
+        passKind,
+        {
+          colorLoadOp: mainColorLoadOp,
+          clearColor: {
+            r: clearColor[0] ?? 0,
+            g: clearColor[1] ?? 0,
+            b: clearColor[2] ?? 0,
+            a: clearColor[3] ?? 1,
+          },
+        },
+      ) as never,
+    );
+
+  // Geometry submission block: setPipeline + 4 bind groups + per-entity
+  // material uploads + drawIndexed.
+
+  // feat-20260609 M2: filter entities by pass selector.
+  let matchedIndices =
+    selector !== undefined ? buildMatchedRenderableIndices(dispatch, selector) : null;
+
+  if (validatedOrdered.length > 0) {
+    // The dynamic-offset stride is an engine buffer-alignment constraint. The
+    // bind-group range and written bytes below are owned by the derived
+    // material interface and may be smaller than that stride.
+    const MATERIAL_SLICE = MATERIAL_PER_ENTITY_STRIDE;
+    // feat-20260515 M3 / T-M3-05 (research F-6 fix): materialBindGroup now
+    // carries 3 entries -- the per-entity material UBO (binding 0,
+    // dynamic-offset retained from D-P9), the default sampler (binding 1,
+    // pipelineState.defaultSampler from createRenderer; research F-5
+    // linear min/mag/mipmap + repeat addressMode), and the texture-view
+    // (binding 2, resolved from MaterialSnapshot.baseColorTexture via
+    // AssetRegistry.getTextureGpuView when present, falling back to the
+    // pipelineState.fallbackTextureView 1x1 white pixel).
+    //
+    // The first validated renderable's material is sampled to choose the
+    // texture-view (M3 milestone simplification; M5 lifts this to
+    // per-entity slot writes once UV-driven sampling lands).
+    //
+    // feat-20260517-merge-mesh-renderer-material-renderer M3 / w10
+    // (this commit): the prior structural cast over `firstMaterial`
+    // (used to reach `baseColorTexture` before the snapshot carried
+    // it as a first-class field) is removed in favour of direct
+    // snapshot field access. `MaterialSnapshot` (extract-stage SSOT)
+    // already declares `baseColorTexture` (M2 / w6); record reads it
+    // directly with no asset registry round-trip and no cast --
+    // Pipeline Isolation: extract owns the asset to snapshot
+    // translation; record consumes the snapshot POD only (charter
+    // proposition 5 consistent abstraction; AC-07 reverse-grep gate
+    // `scripts/forgeax/check-render-record-no-material-asset-get.mjs`
+    // forbids both the cast pattern and any direct material asset
+    // typed-lookup regrowth in this file).
+    // bug-20260522-per-entity-material-texture-binding D-1/D-2:
+    // the pre-loop `firstMaterial` / `materialTextureView` / `
+    // baseMaterialEntries` / single shared `materialBindGroup` are
+    // removed. Each entity now creates its own per-entity material BG
+    // inside the draw loop, resolving binding=2 from its own
+    // `entry.source.material.baseColorTexture` (mirroring sprite path).
+    //
+    // feat-20260520-skylight-ibl-cubemap M3 round-4 / t48 amend: the
+    // 14-entry merged BG (7 material + 7 Skylight) is now assembled per
+    // entity inside the draw loop. The Skylight part stays scene-level
+    // (single `skylightResources` resolved once below); only the first 7
+    // material entries are rebuilt per-entity with the correct
+    // per-entity textureView at binding=2.
+    const skylightFallback = pipelineState.skylightFallback;
+    if (skylightFallback === null) {
+      throw new RhiError({
+        code: 'webgpu-runtime-error',
+        expected: 'pipelineState.skylightFallback != null when PBR pipeline is active',
+        hint: 'createRenderer must allocate skylightFallback alongside the PBR pipeline (D-5 round-4)',
+      });
+    }
+    // feat-20260520-skylight-ibl-cubemap M4 round-4 / t60 (D-5 round-4):
+    // select active vs fallback Skylight resources by `skylightCount` from
+    // the extract stage. Active path reaches into the per-device
+    // `IblPipelineCache` slots (irradianceView / prefilterView / brdfLutView)
+    // populated by the internal equirect-to-cubemap projection; fallback uses the
+    // 1x1-zero identity bundle that converges ambient to 0 (D-4 physical
+    // convergence -- no `if (hasSkylight)` shader branch).
+    // The samplers are reused from `skylightFallback.sampler` for both
+    // paths (linear / clamp-to-edge is correct for IBL cube + 2D LUT
+    // sampling either way). The intensity uniform is rewritten per-frame
+    // when active so `sampleIblSpecular * intensity` carries the user's
+    // Skylight.intensity value; fallback keeps intensity=0 (createSkylightFallback
+    // seed) so ambient = 0 even when the same buffer is shared.
+    let activeViews: { irr: unknown; pref: unknown; brdf: unknown } | undefined;
+    // Per-frame Skylight uniform: std140 32 B = [intensity, colorR, colorG,
+    // colorB, rotation quaternion]. Default to all-zero so a transition from "has Skylight" ->
+    // "no Skylight" does not leak the prior frame's ambient (intensity 0
+    // muzzles everything, including the white fallback irradiance cube).
+    runtime.device.queue.writeBuffer(
+      // biome-ignore lint/suspicious/noExplicitAny: opaque Buffer handle
+      skylightFallback.intensityBuffer as any,
+      0,
+      ZERO_SKYLIGHT_PAYLOAD,
+    );
+    const activeEnvironmentRecord =
+      frameState.environmentGeneration.candidate ?? frameState.environmentGeneration.active;
+    const activeEnvironmentBundle =
+      activeEnvironmentRecord !== undefined &&
+      isEnvironmentGpuBundle(activeEnvironmentRecord.handle)
+        ? activeEnvironmentRecord.handle
+        : undefined;
+    const environmentSunSnapshot = environmentConsumerSnapshot(frameState.environmentGeneration);
+    if (environmentSunSnapshot !== undefined && activeEnvironmentBundle !== undefined) {
+      const sun = environmentSunSnapshot.direct;
+      runtime.device.queue.writeBuffer(
+        // biome-ignore lint/suspicious/noExplicitAny: opaque Buffer handle
+        skylightFallback.intensityBuffer as any,
+        0,
+        new Float32Array([1, sun.color[0] ?? 1, sun.color[1] ?? 1, sun.color[2] ?? 1, 0, 0, 0, 1]),
+      );
+      activeViews = {
+        irr: activeEnvironmentBundle.irradianceView,
+        pref: activeEnvironmentBundle.prefilterView,
+        brdf: skylightFallback.brdfLutView,
+      };
+    } else if (skylight !== undefined && skylightCount >= 1) {
+      // A Skylight exists. Write its intensity + color regardless of whether
+      // a cubemap is bound: with a cubemap the IBL views below light the
+      // ambient; WITHOUT one, the white fallback irradiance cube + this color
+      // give an instant solid-color ambient (downstream integration #4) with
+      // no async precompute. The white fallback only contributes when a
+      // Skylight is present because the zero-payload above sets intensity 0
+      // when no Skylight exists.
+      const [cr, cg, cb] = skylight.color;
+      const [qx, qy, qz, qw] = skylight.rotation;
+      const uniformPayload = new Float32Array([skylight.intensity, cr, cg, cb, qx, qy, qz, qw]);
+      runtime.device.queue.writeBuffer(
+        // biome-ignore lint/suspicious/noExplicitAny: opaque Buffer handle
+        skylightFallback.intensityBuffer as any,
+        0,
+        uniformPayload,
+      );
+      // biome-ignore lint/suspicious/noExplicitAny: device is the opaque RhiDevice
+      const cache = getOrCreateIblCache(runtime.device as any);
+      if (
+        cache.irradianceView !== undefined &&
+        cache.prefilterView !== undefined &&
+        cache.brdfLutView !== undefined
+      ) {
+        activeViews = {
+          irr: cache.irradianceView,
+          pref: cache.prefilterView,
+          brdf: cache.brdfLutView,
+        };
+      }
+    }
+    const skylightResources =
+      activeViews !== undefined
+        ? {
+            irradianceView: activeViews.irr as never,
+            irradianceSampler: skylightFallback.sampler,
+            prefilterView: activeViews.pref as never,
+            prefilterSampler: skylightFallback.sampler,
+            brdfLutView: activeViews.brdf as never,
+            brdfLutSampler: skylightFallback.sampler,
+            intensityBuffer: skylightFallback.intensityBuffer,
+          }
+        : {
+            irradianceView: skylightFallback.irradianceView,
+            irradianceSampler: skylightFallback.sampler,
+            prefilterView: skylightFallback.prefilterView,
+            prefilterSampler: skylightFallback.sampler,
+            brdfLutView: skylightFallback.brdfLutView,
+            brdfLutSampler: skylightFallback.sampler,
+            intensityBuffer: skylightFallback.intensityBuffer,
+          };
+    // Per-entity material uploads (D-P9 retained path). The payload is derived
+    // from each material's effective paramSchema; engine-owned resources bind
+    // separately and never add a second layout owner here.
+    //
+    // Material snapshots are interned by extract-owned identity before this
+    // pass. Repeated scene instances therefore share one 256-byte UBO slot;
+    // materialSlotIndices maps each authored submesh material to that slot.
+    // feat-city-glb Bug 5 (per-submesh transparency): shared per-submesh
+    // material bind-group assembly, called by BOTH the geometry pass and the
+    // LDR blend sub-pass so a transparent PBR submesh binds the identical
+    // metallic/roughness/normal/emissive/occlusion + Skylight layout
+    // the geometry pass uses (the sub-pass previously bound a sprite-only BG,
+    // which cannot render a PBR decal). Captures only frame-stable closure
+    // state; the caller passes the per-submesh material snapshot + entityKey
+    // (for video texture routing) and sets the dynamic UBO offset itself.
+    const perSubmeshMaterialBgDeps: PerSubmeshMaterialBgDeps = {
+      runtime,
+      pipelineState,
+      world,
+      store,
+      materialSlice: MATERIAL_SLICE,
+      videoHighPerfAvailable,
+      skylightResources,
+      materialBgShared: frameState.materialBgShared,
+      materialBgAssemblyCache: c.materialBgAssemblyCache,
+      bindGroupCounts,
+    };
+    const buildPerSubmeshMaterialBg = (
+      submeshMaterial: MaterialSnapshot,
+      entityKey: number,
+    ): BindGroup =>
+      buildPerSubmeshMaterialBgImpl(perSubmeshMaterialBgDeps, submeshMaterial, entityKey);
+
+    const cachedMaterialUboPayload = c.materialUboPayloadCache;
+    let materialUboPayload: Uint8Array;
+    if (
+      cachedMaterialUboPayload?.materialSlots === materialSlots &&
+      cachedMaterialUboPayload.materialSlotCount === materialSlotCount &&
+      cachedMaterialUboPayload.materialResourceEpoch === store.materialResourceEpoch
+    ) {
+      materialUboPayload = cachedMaterialUboPayload.payload;
+    } else {
+      materialUboPayload = new Uint8Array(materialSlotCount * MATERIAL_PER_ENTITY_STRIDE);
+      const invalidMaterialSlots = new Set<number>();
+      for (let materialSlot = 0; materialSlot < materialSlots.length; materialSlot += 1) {
+        const mat = materialSlots[materialSlot];
+        const entry = validatedOrdered[materialSlotOwners[materialSlot] ?? -1];
+        if (mat === undefined || entry === undefined) continue;
+        const payload = writeMaterialSnapshotPayload(
+          mat,
+          MATERIAL_PER_ENTITY_STRIDE,
+          runtime.paramSchemaProjectionCensus,
+        );
+        if (!payload.ok) {
+          invalidMaterialSlots.add(materialSlot);
+          runtime.errorRegistry.fire(payload.error as never);
+          continue;
+        }
+        const materialShaderId = mat.materialShaderId;
+        const baseColorTextureHandle = mat.baseColorTexture as
+          | Handle<'TextureAsset', 'shared'>
+          | undefined;
+        if (baseColorTextureHandle !== undefined) {
+          const baseColorView = residentTextureView(world, store, runtime, baseColorTextureHandle);
+          if (baseColorView === undefined) {
+            const rawId = baseColorTextureHandle as unknown as number;
+            if (!frameState.warnedMissingBaseColorTextureHandles.has(rawId)) {
+              frameState.warnedMissingBaseColorTextureHandles.add(rawId);
+              console.warn(
+                `[forgeax] baseColor texture ${rawId} missing GPU view, skipping draw (shader=${materialShaderId ?? '<none>'} entityIndex=${entry.renderableIndex})`,
+              );
+            }
+            runtime.errorRegistry.fire(
+              new RhiError({
+                code: 'asset-not-registered',
+                expected: 'material baseColor TextureAsset uploaded to GPU',
+                hint: 'register + uploadTexture the baseColor texture before draw([world], { cameraOwner: 0, resourceOwner: 0 }); the affected material draw is skipped until then',
+                detail: { assetHandle: rawId },
+              }),
+            );
+            invalidMaterialSlots.add(materialSlot);
+            continue;
+          }
+        }
+        materialUboPayload.set(payload.value, materialSlot * MATERIAL_PER_ENTITY_STRIDE);
+      }
+
+      // Material UBO slots can share one snapshot identity, but nine-slice
+      // validity depends on each entity's transform. Preserve diagnostics per
+      // renderable instead of inheriting the first owner of a shared slot.
+      for (const entry of validatedOrdered) {
+        const mat = entry.source.material;
+        const materialShaderId = mat.materialShaderId;
+        if (materialShaderId !== 'forgeax::sprite' && materialShaderId !== 'forgeax::sprite-lit')
+          continue;
+        const slicesAndMode = mat.paramSnapshot?.slicesAndMode as readonly number[] | undefined;
+        if (slicesAndMode === undefined || slicesAndMode.length < 4) continue;
+        const slicesArr: readonly [number, number, number, number] = [
+          slicesAndMode[0] ?? 0,
+          slicesAndMode[1] ?? 0,
+          slicesAndMode[2] ?? 0,
+          slicesAndMode[3] ?? 0,
+        ];
+        if (slicesArr[0] === 0 && slicesArr[1] === 0 && slicesArr[2] === 0 && slicesArr[3] === 0)
+          continue;
+        detectNineSliceScaleTooSmall(
+          entry.source.transform.world,
+          slicesArr,
+          entry.renderableIndex,
+          frameState.warnedNineSliceScaleEntities,
+          runtime.metrics,
+        );
+      }
+      if (invalidMaterialSlots.size === 0) {
+        c.materialUboPayloadCache = {
+          materialSlots,
+          materialSlotCount,
+          materialResourceEpoch: store.materialResourceEpoch,
+          payload: materialUboPayload,
+        };
+      }
+
+      const recordableIndices = new Set<number>();
+      for (let index = 0; index < validatedOrdered.length; index += 1) {
+        const entry = validatedOrdered[index];
+        if (entry === undefined) continue;
+        const slots = materialSlotIndices[index] ?? [];
+        if (slots.some((slot) => invalidMaterialSlots.has(slot))) continue;
+        if (matchedIndices === null || matchedIndices.has(entry.renderableIndex)) {
+          recordableIndices.add(entry.renderableIndex);
+        }
+      }
+      if (invalidMaterialSlots.size > 0 || matchedIndices !== null) {
+        matchedIndices = recordableIndices;
+      }
+    }
+
+    // All material slots are staged before the first geometry draw. One
+    // stride-shaped upload preserves every dynamic offset while avoiding one
+    // queue call per material; the RHI still validates alignment and bounds at
+    // this single owner-level write boundary.
+    const materialUboUpload = runtime.device.queue.writeBuffer(
+      pipelineState.materialUniformBuffer.buffer,
+      0,
+      materialUboPayload,
+    );
+    if (!materialUboUpload.ok) throw materialUboUpload.error;
+
+    // Static material resources are a property of the frame-local material
+    // slot, not of each submesh draw. Resolve them once here so the geometry
+    // loop only selects a prepared binding. Video fields remain entity-bound:
+    // their current frame view is keyed by entityKey and must be resolved at
+    // the draw site.
+    const preparedMaterialBindGroups = new Array<BindGroup | undefined>(materialSlotCount);
+    for (let materialSlot = 0; materialSlot < materialSlotCount; materialSlot += 1) {
+      const material = materialSlots[materialSlot];
+      if (material === undefined || (material.videoTextureFields?.size ?? 0) > 0) continue;
+      const owner = validatedOrdered[materialSlotOwners[materialSlot] ?? -1];
+      if (owner === undefined) continue;
+      preparedMaterialBindGroups[materialSlot] = buildPerSubmeshMaterialBg(
+        material,
+        owner.source.entityKey,
+      );
+    }
+    const resolveMaterialBindGroup = (
+      materialSlot: number,
+      material: MaterialSnapshot,
+      entityKey: number,
+    ): BindGroup =>
+      preparedMaterialBindGroups[materialSlot] ?? buildPerSubmeshMaterialBg(material, entityKey);
+
+    pass.setBindGroup(0, viewBindGroup as BindGroup);
+
+    // Track which (mesh-vertex-buffer, mesh-index-buffer, pipeline) combo
+    // was last bound so consecutive entities sharing the same combo skip
+    // the redundant rebinds (cheap GPU cost; net wins on workloads where
+    // most entities share BUILTIN_CUBE + unlit). Initial nulls force the
+    // first iteration to bind unconditionally.
+    // M-3 / w12: vertexBuffer/indexBuffer state locals migrate to GpuBuffer.
+    if (passKind !== 'forward' || !c.gpuDrivenOwnsAllForwardItems) {
+      const recordGeometry = (): void => {
+        recordGeometryDraws(
+          c,
+          pass,
+          matchedIndices,
+          materialSlotIndices,
+          sampleCount,
+          meshGroup2,
+          resolveMaterialBindGroup,
+          passKind,
+        );
+      };
+      if (c.profilePhase === undefined) {
+        recordGeometry();
+      } else {
+        const passName =
+          passKind === 'deferred'
+            ? 'g-buffer'
+            : passKind === 'temporal'
+              ? 'scene-temporal'
+              : 'forward';
+        c.profilePhase(
+          `record/graph-execute/${passName}/geometry-loop` as RenderRecordPhase,
+          recordGeometry,
+        );
+      }
+    }
+
+    // D-2: LDR sprite pass. Runs after the geometry pass when there are
+    // sprite entities in the draw list and the LDR path is active.
+    // The geometry pass used the bgra8unorm-srgb sRGB view (hardware sRGB
+    // encoding for unlit/standard/pbr output). The sprite pass uses the
+    // bgra8unorm storage view (loadOp=load) so the sprite LDR pipeline
+    // (target=bgra8unorm, blend=premultiplied-alpha) can write over the
+    // already-encoded geometry pixels. Depth is loaded from the geometry
+    // pass so sprite-vs-mesh occlusion (depthCompare=less-equal) is
+    // preserved (plan-strategy §2 D-2 + §4 R-4).
+    if (passKind === 'forward') {
+      geometryPassEnded = recordSpritePass(
+        c,
+        pass,
+        matchedIndices,
+        materialSlotIndices,
+        sampleCount,
+        resolveMaterialBindGroup,
+        skylightResources,
+        graphPass,
+      );
+    }
+  } // end if (validatedOrdered.length > 0) -- Case E falls through to pass.end()
+
+  if (!geometryPassEnded && graphPass === undefined) {
+    pass.end();
+  }
+}
+
+export function encodeMainPass(
+  c: _InternalRenderPipelineContext,
+  pass: RhiRenderPassEncoder,
+  selector?: PassSelector,
+  options?: MainPassOptions,
+): void {
+  recordMainPass(c, selector, options, pass);
+}