@forgeax/engine-render 0.1.27 → 0.1.29

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

@@ -23,6 +23,7 @@ import {
   DEFAULT_MSDF_TEXT_PARAM_SCHEMA,
   DEFAULT_SPRITE_PARAM_SCHEMA,
   DEFAULT_UNLIT_PARAM_SCHEMA,
+  STANDARD_PHYSICAL_TEXTURE_FIELDS,
   STANDARD_PIPELINE_PARAM_SCHEMA,
 } from '@forgeax/engine-shader';
 import type {
@@ -51,7 +52,7 @@ import {
   physicalTextureFields,
 } from '../pbr-pipeline';
 import { deriveTextureExtent } from '../render-data';
-import type { MaterialSnapshot } from '../render-system-extract';
+import type { MaterialSnapshot, SkylightSnapshot } from '../render-system-extract';
 import type { RenderTargetTextureSource } from '../targets/contracts';
 import {
   type RenderTargetMaterialSourceBinding,
@@ -548,6 +549,44 @@ function materialUboFloatView(payload: MaterialUboPayload): Float32Array {
     : new Float32Array(payload);
 }
 
+function materialUboDataView(payload: MaterialUboPayload): DataView {
+  if (payload instanceof Float32Array || payload instanceof Uint8Array) {
+    return new DataView(payload.buffer, payload.byteOffset, payload.byteLength);
+  }
+  return new DataView(payload);
+}
+
+/** Write one schema value with the scalar type's actual WGSL bit encoding. */
+function writeNumericParamValue(
+  view: DataView,
+  entry: { readonly offset: number; readonly size: number; readonly type: string },
+  value: number | readonly number[],
+): void {
+  const values = typeof value === 'number' ? [value] : value;
+  const width = entry.size / 4;
+  const writeCount = Math.min(values.length, width);
+  for (let index = 0; index < writeCount; index += 1) {
+    const component = values[index];
+    if (typeof component !== 'number') continue;
+    const byteOffset = entry.offset + index * 4;
+    switch (entry.type) {
+      case 'i32':
+        view.setInt32(byteOffset, component, true);
+        break;
+      case 'u32':
+        view.setUint32(byteOffset, component, true);
+        break;
+      case 'f32':
+      case 'vec2':
+      case 'vec3':
+      case 'vec4':
+      case 'color':
+        view.setFloat32(byteOffset, component, true);
+        break;
+    }
+  }
+}
+
 export function applyMaterialTextureUvScales(
   payload: MaterialUboPayload,
   material: MaterialSnapshot,
@@ -745,7 +784,7 @@ export function writePbrMaterialUboPayload(
     );
   }
   buf.fill(0);
-  const f32 = materialUboFloatView(buf);
+  const dataView = materialUboDataView(buf);
   const schema =
     material.materialParamSchema === undefined || material.materialParamSchema.length === 0
       ? STANDARD_PIPELINE_PARAM_SCHEMA
@@ -782,15 +821,10 @@ export function writePbrMaterialUboPayload(
     const value =
       snapshot?.[entry.name] ??
       fallback(entry.name, schema.find((item) => item.name === entry.name) ?? entry);
-    const offset = entry.offset / 4;
-    const width = entry.size / 4;
     if (typeof value === 'number') {
-      f32[offset] = value;
+      writeNumericParamValue(dataView, entry, value);
     } else if (Array.isArray(value)) {
-      for (let index = 0; index < Math.min(width, value.length); index += 1) {
-        const component = value[index];
-        if (typeof component === 'number') f32[offset + index] = component;
-      }
+      writeNumericParamValue(dataView, entry, value);
     }
   }
 }
@@ -839,28 +873,18 @@ export function applyParamSnapshotToUbo(
 ): void {
   if (paramSchema === undefined) return;
   if (paramSnapshot === undefined) return;
-  const f32 = materialUboFloatView(payload);
+  const dataView = materialUboDataView(payload);
   const { uboLayout } = derivedParamSchema(paramSchema);
   for (const entry of uboLayout.entries) {
     const value = paramSnapshot[entry.name];
     if (value === undefined) continue;
-    const f32Offset = entry.offset / 4;
-    const f32Width = entry.size / 4;
     if (typeof value === 'number') {
-      // Scalar f32 / i32 / u32 -- single-slot write. (i32 / u32 still arrive
-      // as a JS number; the GPU side reads the four bytes as the declared
-      // type, so an f32 write is the correct bit pattern when the caller
-      // already produced an integer value.)
-      if (f32Width >= 1) f32[f32Offset] = value;
+      writeNumericParamValue(dataView, entry, value);
       continue;
     }
     if (Array.isArray(value)) {
       const arr = value as readonly number[];
-      const writeCount = Math.min(arr.length, f32Width);
-      for (let i = 0; i < writeCount; i++) {
-        const v = arr[i];
-        if (typeof v === 'number') f32[f32Offset + i] = v;
-      }
+      writeNumericParamValue(dataView, entry, arr);
     }
     // string values (texture GUIDs) belong to texture bindings, not the
     // UBO; derive's uboLayout.entries already strips non-numeric schema
@@ -869,6 +893,31 @@ export function applyParamSnapshotToUbo(
   }
 }
 
+/**
+ * Seed a schema-driven UBO with the defaults declared by its numeric contract.
+ *
+ * Prepared graphics (VFX and other feature-owned materials) do not pass
+ * through the extracted `MaterialSnapshot` writer, so their payload starts as
+ * zeroed storage. Applying the schema defaults first keeps that path
+ * byte-compatible with the ordinary material writer while preserving the
+ * snapshot writer's intentional overlay semantics.
+ */
+export function applyParamSchemaDefaultsToUbo(
+  payload: MaterialUboPayload,
+  paramSchema: readonly ParamSchemaEntry[] | undefined,
+): void {
+  if (paramSchema === undefined) return;
+  const defaults: Record<string, number | readonly number[]> = {};
+  for (const entry of derivedParamSchema(paramSchema).uboLayout.entries) {
+    const schemaEntry = paramSchema.find((candidate) => candidate.name === entry.name);
+    const value = schemaEntry?.default;
+    if (typeof value === 'number' || Array.isArray(value)) {
+      defaults[entry.name] = value as number | readonly number[];
+    }
+  }
+  applyParamSnapshotToUbo(payload, paramSchema, defaults);
+}
+
 /**
  * feat-20260704 M3/w19: shared per-submesh material bind-group assembly, hoisted
  * from the `buildPerSubmeshMaterialBg` closure inside recordMainPass so both the
@@ -902,6 +951,8 @@ export interface PerSubmeshMaterialBgDeps {
   readonly materialBgShared: Map<string, WeakMap<object, unknown>>;
   /** Cross-frame final BG reuse keyed by the stable source material handle. */
   readonly materialBgAssemblyCache: Map<string, MaterialBgAssemblyCacheEntry>;
+  /** Producer-owned numeric scene rows consumed by scene-index PBR draws. */
+  readonly sceneMaterialBuffer?: Buffer;
   /** Active transmission backdrop; undefined/null means layout placeholder. */
   readonly transmissionBackdropView?: TextureView | null;
   readonly bindGroupCounts: BindGroupCounts;
@@ -1041,7 +1092,8 @@ export function buildPerSubmeshMaterialBg(
         effectiveSkylightResources,
         store.materialResourceEpoch,
         transmissionBackdropView,
-      )
+      ) &&
+      deps.sceneMaterialBuffer === undefined
     ) {
       if (diagnosticsEnabled) {
         recordIblMaterialBinding(
@@ -1194,7 +1246,9 @@ export function buildPerSubmeshMaterialBg(
       }
     }
     physicalTextureInjections.push({
-      slot,
+      slot: STANDARD_PHYSICAL_TEXTURE_FIELDS.indexOf(
+        field as (typeof STANDARD_PHYSICAL_TEXTURE_FIELDS)[number],
+      ),
       sampler: smSamplerForField(field),
       view,
     });
@@ -1216,6 +1270,23 @@ export function buildPerSubmeshMaterialBg(
     } satisfies TransmissionBindGroupResources,
     physicalTextureInjections,
   );
+  // Storage-capable devices share one Standard material BGL with the
+  // scene-index GPU lane. Even direct draws need a complete entry for
+  // binding(46), although their shader does not read the scene table. Reuse
+  // the storage-backed mesh table as a neutral placeholder until a
+  // producer-owned GPU scene table is available; GPU-driven draws replace it
+  // with `deps.sceneMaterialBuffer`.
+  if (runtime.device.caps.storageBuffer) {
+    smMergedEntries.push({
+      binding: 46,
+      resource: {
+        kind: 'buffer' as const,
+        value: {
+          buffer: deps.sceneMaterialBuffer ?? pipelineState.meshStorageBuffer.buffer,
+        },
+      },
+    });
+  }
   const createBindGroup = (): BindGroup => {
     const result = runtime.device.createBindGroup({
       label: 'pbr-material-skylight-bg',
@@ -1283,6 +1354,7 @@ export function buildPerSubmeshMaterialBg(
     smMaterialHandle !== undefined &&
     !smHasVideoFields &&
     materialResourcesResident &&
+    deps.sceneMaterialBuffer === undefined &&
     !hasActiveTransmissionBackdrop
   ) {
     if (materialCacheKey !== undefined) {
@@ -1302,8 +1374,20 @@ export function buildPerSubmeshMaterialBg(
 const ZERO_SKYLIGHT_PAYLOAD = new Float32Array([0, 0, 0, 0, 0, 0, 0, 1]);
 
 /** The same scene resources back material bindings in depth and color passes. */
-export function prepareMaterialSkylight(c: _InternalRenderPipelineContext) {
-  const { runtime, pipelineState, skylight, skylightCount } = c;
+/**
+ * Resolve the renderer-owned Skylight bundle for both ordinary geometry and
+ * prepared RenderFeature materials.  Feature preparation runs before the
+ * main pass is encoded, so it cannot rely on the geometry pass to initialize
+ * the intensity buffer or to select the current IBL views.  Keeping this
+ * small argument-based helper as the single resolver makes the two paths use
+ * identical resources while retaining the existing frame-local write.
+ */
+export function resolveMaterialSkylight(
+  runtime: Pick<RenderSystemRuntime, 'device' | 'deviceScope'>,
+  pipelineState: Pick<PipelineState, 'skylightFallback'>,
+  skylight: SkylightSnapshot | undefined,
+  skylightCount: number,
+) {
   const skylightFallback = pipelineState.skylightFallback;
   if (skylightFallback === null) {
     throw new RhiError({
@@ -1378,3 +1462,8 @@ export function prepareMaterialSkylight(c: _InternalRenderPipelineContext) {
         };
   return { skylightResources, activeViews };
 }
+
+/** The same scene resources back material bindings in depth and color passes. */
+export function prepareMaterialSkylight(c: _InternalRenderPipelineContext) {
+  return resolveMaterialSkylight(c.runtime, c.pipelineState, c.skylight, c.skylightCount);
+}

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

@@ -5,24 +5,18 @@
 import type { World } from '@forgeax/engine-ecs';
 import {
   type BindGroup,
-  type BindGroupEntry,
   type Buffer,
   type RenderPipeline,
   RhiError,
   type RhiRenderPassEncoder,
-  type TextureView,
 } from '@forgeax/engine-rhi';
-import type { Handle, MaterialRenderState } from '@forgeax/engine-types';
+import type { MaterialRenderState } from '@forgeax/engine-types';
 import { GpuBuffer } from '../gpu-resource';
 import {
   GPU_BUFFER_USAGE_COPY_DST,
   GPU_BUFFER_USAGE_STORAGE,
   GPU_BUFFER_USAGE_UNIFORM,
 } from '../gpu-usage';
-import {
-  assembleMaterialWithSkylightEntries,
-  type SkylightBindGroupResources,
-} from '../ibl/skylight-bind-group';
 import type { InstanceBufferCacheEntry } from '../instance-buffer-cache';
 import { SPRITE_PREMULTIPLIED_ALPHA_BLEND } from '../materials';
 import { SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET } from '../pbr-pipeline';
@@ -35,67 +29,15 @@ import type {
 import { worldEntityKey } from './frame-snapshot';
 import { recordGeometryDraws, resolveGeometryInstancesBindGroup } from './main-pass-geometry';
 import {
-  BUILTIN_USER_REGION_TEXTURE_FIELDS,
-  defaultViewForUserRegionField,
-  residentTextureView,
-} from './main-pass-material';
-import {
-  extractEntryResourceHandle,
-  getOrCreatePerEntity,
   MAX_UNIFORM_INSTANCES,
   MESH_PER_ENTITY_STRIDE,
   packInstanceStorageBuffer,
 } from './mesh-ssbo';
 import type { _InternalRenderPipelineContext } from './render-context';
-import { MATERIAL_PER_ENTITY_STRIDE, STANDARD_PBR_UBO_SIZE } from './render-context';
+import { MATERIAL_PER_ENTITY_STRIDE } from './render-context';
 
 export type { SpriteInstancesSnapshot };
 
-/**
- * Build the sprite material's Standard user-region from the shared field-order
- * owner. The sprite shader uses the same Standard material bind-group layout;
- * keeping this projection derived from the shared list prevents IBL injection
- * from moving ahead of newly added material texture pairs.
- */
-export function buildSpritePassBaseMaterialEntries(
-  pipelineState: _InternalRenderPipelineContext['pipelineState'],
-  spriteTexView: TextureView,
-): BindGroupEntry[] {
-  const entries: BindGroupEntry[] = [
-    {
-      binding: 0,
-      resource: {
-        kind: 'buffer' as const,
-        value: {
-          buffer: pipelineState.materialUniformBuffer.buffer,
-          offset: 0,
-          size: STANDARD_PBR_UBO_SIZE,
-        },
-      },
-    },
-  ];
-  for (const [index, field] of BUILTIN_USER_REGION_TEXTURE_FIELDS.entries()) {
-    const view =
-      field === 'baseColorTexture'
-        ? spriteTexView
-        : defaultViewForUserRegionField(field, pipelineState);
-    entries.push(
-      {
-        binding: 1 + index * 2,
-        resource: {
-          kind: 'sampler' as const,
-          value: index === 0 ? pipelineState.nearestSampler : pipelineState.defaultSampler,
-        },
-      },
-      {
-        binding: 2 + index * 2,
-        resource: { kind: 'textureView' as const, value: view },
-      },
-    );
-  }
-  return entries;
-}
-
 /**
  * Build the interleaved sprite instance payload consumed by this record owner.
  * The extract stage validates the two packed arrays before they reach this
@@ -204,7 +146,6 @@ export function recordSpritePass(
     materialWorld: World,
     materialShaderId?: string,
   ) => BindGroup,
-  skylightResources: SkylightBindGroupResources,
   graphPass?: RhiRenderPassEncoder,
   selectedDispatch?: readonly DispatchEntry[],
 ): boolean {
@@ -405,7 +346,7 @@ export function recordSpritePass(
       c,
       spritePass,
       matchedIndices,
-      skylightResources,
+      resolveMaterialBindGroup,
       spritePH,
       spritePH_withRegion,
       spriteLitPH,
@@ -509,7 +450,12 @@ function recordSpriteEntityDraws(
   c: _InternalRenderPipelineContext,
   spritePass: RhiRenderPassEncoder,
   matchedIndices: Set<number> | null,
-  skylightResources: SkylightBindGroupResources,
+  resolveMaterialBindGroup: (
+    materialSlot: number,
+    material: MaterialSnapshot,
+    entityKey: number,
+    materialWorld: World,
+  ) => BindGroup,
   spritePH: RenderPipeline | null,
   spritePH_withRegion: RenderPipeline | null,
   spriteLitPH: RenderPipeline | null,
@@ -518,10 +464,8 @@ function recordSpriteEntityDraws(
   const {
     runtime,
     world,
-    store,
     pipelineState,
     frameState,
-    bindGroupCounts,
     validatedOrdered,
     meshBindGroup,
     foldDispatchPlan,
@@ -737,6 +681,7 @@ function recordSpriteEntityDraws(
           );
           spritePass.setBindGroup(3, spriteInstBg);
           spritePass.drawIndexed(spriteEntry.mesh.indexCount, spriteInstanceCount, 0, 0, 0);
+          c.onRenderableDraw?.(spriteEntry);
           continue;
         }
         spriteBufUsage = GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST;
@@ -852,53 +797,19 @@ function recordSpriteEntityDraws(
 
     const materialSlot = materialSlotIndices[i]?.[0] ?? 0;
 
-    // Per-entity sprite material bind group: same standard PBR user-region
-    // layout as in the geometry pass sprite branch + Skylight merged entries
-    // the geometry pass sprite branch + Skylight merged entries (same
-    // skylightResources in scope from above). Texture view is resolved
-    // from the sprite material's baseColorTexture handle.
-    const spriteTexHandle = spriteEntry.source.material.baseColorTexture as
-      | Handle<'TextureAsset', 'shared'>
-      | undefined;
-    let spriteTexView = pipelineState.defaultWhiteTextureView;
-    if (spriteTexHandle !== undefined) {
-      const tv = residentTextureView(spriteEntry.world ?? world, store, runtime, spriteTexHandle);
-      if (tv !== undefined) spriteTexView = tv as never;
-    }
-    const spritePassBaseMaterialEntries = buildSpritePassBaseMaterialEntries(
-      pipelineState,
-      spriteTexView,
-    );
-    const spritePassMergedEntries = assembleMaterialWithSkylightEntries(
-      spritePassBaseMaterialEntries,
-      skylightResources,
-    );
-
-    // Sprite-pass material BG cache: keyed on shader id (shared across all
-    // sprite entities) so entities using the same atlas texture share one
-    // BindGroup instead of creating one per entity (O5 fix — inner WeakMap
-    // chain naturally deduplicates by GPU resource object identity, so two
-    // entities with different atlases still get distinct BGs).
-    const spritePassBg: BindGroup = getOrCreatePerEntity(
-      frameState.materialBgShared,
-      'forgeax::sprite',
-      spritePassMergedEntries.map((e) => extractEntryResourceHandle(e)),
-      'sprite-pass-material',
-      () => {
-        const result = runtime.device.createBindGroup({
-          label: 'sprite-pass-material-bg',
-          layout: pipelineState.materialBindGroupLayout,
-          entries: spritePassMergedEntries,
-        });
-        if (!result.ok) throw result.error;
-        return result.value;
-      },
-      bindGroupCounts,
+    // The same material owner serves HDR and linear-LDR draws. Do not
+    // replace authored samplers, texture sources or cooked layouts here.
+    const spritePassBg = resolveMaterialBindGroup(
+      materialSlot,
+      spriteEntry.source.material,
+      spriteEntry.source.entityKey,
+      spriteEntry.world ?? world,
     );
 
     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);
   }
 }
 

package/src/record/main-pass.ts

@@ -1,5 +1,6 @@
 import type { World } from '@forgeax/engine-ecs';
 import { probeVideoHighPerfUpload } from '@forgeax/engine-graphics-extras';
+import type { GraphResourceResolver } from '@forgeax/engine-render-graph';
 import {
   type BindGroup,
   RhiError,
@@ -14,9 +15,13 @@ import { buildBeginRenderPassDescriptor, standardTopologyBindGroupReady } from '
 import { POINTS_LINES_MATERIAL_SHADER_ID } from '../points-lines/record';
 import type { ReflectionProbeSelectionResult } from '../reflection/projection';
 import type { RenderRecordPhase } from '../render-contract';
+import type {
+  GpuDrivenStandardPbrFrameResources,
+  RenderPipelineGpuDrivenProjection,
+} from '../render-pipeline';
 import type { MaterialSnapshot } from '../render-system-extract';
 import { resolveReflectionProbeBinding } from './frame-lighting';
-import { getOpaqueResourceIdentity } from './frame-snapshot';
+import { getOpaqueResourceIdentity, worldEntityKey } from './frame-snapshot';
 import { recordGeometryDraws } from './main-pass-geometry';
 import {
   buildPerSubmeshMaterialBg as buildPerSubmeshMaterialBgImpl,
@@ -57,7 +62,15 @@ export type MainPassOptions = {
   readonly passKind?: PassKind;
   readonly clearColor?: readonly [number, number, number, number];
   readonly recordMode?: 'opaque' | 'transmission' | 'transparent';
+  /** 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;
+  readonly gpuDriven?: {
+    readonly projection: RenderPipelineGpuDrivenProjection;
+    readonly resources: GraphResourceResolver;
+  };
 };
 
 function isTransmissionMaterial(material: MaterialSnapshot): boolean {
@@ -117,7 +130,7 @@ export function recordMainPass(
   selector?: PassSelector,
   options?: MainPassOptions,
   graphPass?: RhiRenderPassEncoder,
-): void {
+): GpuDrivenStandardPbrFrameResources | undefined {
   const {
     runtime,
     world,
@@ -143,6 +156,8 @@ export function recordMainPass(
     materialSlots,
     materialSlotOwners,
     materialSlotCount,
+    gpuDrivenStandardPbrFrameResources,
+    gpuDrivenSceneMaterialBuffer,
   } = c;
   // bug-20260615 M3 / m3-1: sampleCount is threaded through every
   // getMaterialShaderPipeline call site so the cache key / builder
@@ -280,7 +295,14 @@ export function recordMainPass(
   const matchedIndices =
     selector !== undefined ? buildMatchedRenderableIndices(dispatch, selector) : null;
   const selectorMatchedMaterials =
-    selector !== undefined ? buildMatchedMaterialHandlesByRenderable(dispatch, selector) : null;
+    selector !== undefined
+      ? buildMatchedMaterialHandlesByRenderable(
+          dispatch,
+          selector,
+          options?.excludeSelector,
+          options?.includeSelector,
+        )
+      : null;
   const matchedMaterials = matchedMaterialsForRecordMode(c, selectorMatchedMaterials, recordMode);
   const selectedDispatch =
     dispatch.length === 0
@@ -488,6 +510,14 @@ export function recordMainPass(
       materialBgAssemblyCache: c.materialBgAssemblyCache,
       frameState,
       bindGroupCounts,
+      ...(gpuDrivenStandardPbrFrameResources?.sceneMaterialBuffer === undefined &&
+      gpuDrivenSceneMaterialBuffer === undefined
+        ? {}
+        : {
+            sceneMaterialBuffer:
+              gpuDrivenStandardPbrFrameResources?.sceneMaterialBuffer ??
+              gpuDrivenSceneMaterialBuffer,
+          }),
       ...(transmissionBackdropView === undefined ? {} : { transmissionBackdropView }),
     };
     const buildPerSubmeshMaterialBg = (
@@ -503,7 +533,6 @@ export function recordMainPass(
         materialWorld,
         materialShaderId,
       );
-
     // 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:
@@ -513,7 +542,7 @@ export function recordMainPass(
     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];
+      const owner = materialSlotOwners[materialSlot];
       if (owner === undefined) continue;
       preparedMaterialBindGroups[materialSlot] = buildPerSubmeshMaterialBg(
         material,
@@ -521,6 +550,19 @@ export function recordMainPass(
         owner.world ?? world,
       );
     }
+    if (gpuDrivenStandardPbrFrameResources !== undefined) {
+      gpuDrivenStandardPbrFrameResources.materialBindGroups.length = 0;
+      gpuDrivenStandardPbrFrameResources.materialBindGroups.push(...preparedMaterialBindGroups);
+      gpuDrivenStandardPbrFrameResources.materialSlotIndicesByEntity.clear();
+      for (let index = 0; index < validatedOrdered.length; index += 1) {
+        const entry = validatedOrdered[index];
+        if (entry === undefined) continue;
+        gpuDrivenStandardPbrFrameResources.materialSlotIndicesByEntity.set(
+          worldEntityKey(entry.source.worldId, entry.source.entityKey),
+          materialSlotIndices[index] ?? [],
+        );
+      }
+    }
     const resolveMaterialBindGroup = (
       materialSlot: number,
       material: MaterialSnapshot,
@@ -554,6 +596,7 @@ export function recordMainPass(
         resolveMaterialBindGroup,
         passKind,
         selectedDispatch,
+        colorFormats,
       );
     };
     if (c.profilePhase === undefined) {
@@ -566,6 +609,33 @@ export function recordMainPass(
       );
     }
 
+    if (options?.gpuDriven !== undefined) {
+      if (viewBindGroup === null) {
+        throw new RhiError({
+          code: 'rhi-not-available',
+          expected: 'main-pass Standard PBR view bind group for GPU-driven encode',
+          hint: 'publish the current frame view/light/shadow bind group before GPU raster',
+        });
+      }
+      if (
+        gpuDrivenStandardPbrFrameResources === undefined ||
+        gpuDrivenStandardPbrFrameResources.materialBindGroups.length === 0 ||
+        gpuDrivenStandardPbrFrameResources.materialBindGroups.some((group) => group === undefined)
+      ) {
+        throw new RhiError({
+          code: 'rhi-not-available',
+          expected: 'complete main-pass Standard PBR material bind-group receipt',
+          hint: 'finish frame material producer assembly before GPU-driven encode',
+        });
+      }
+      options.gpuDriven.projection.encode(
+        viewBindGroup,
+        pass,
+        options.gpuDriven.resources,
+        gpuDrivenStandardPbrFrameResources,
+      );
+    }
+
     // 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
@@ -583,7 +653,6 @@ export function recordMainPass(
         materialSlotIndices,
         sampleCount,
         resolveMaterialBindGroup,
-        skylightResources,
         graphPass,
         selectedDispatch,
       );
@@ -593,6 +662,7 @@ export function recordMainPass(
   if (!geometryPassEnded && graphPass === undefined) {
     pass.end();
   }
+  return gpuDrivenStandardPbrFrameResources;
 }
 
 export function encodeMainPass(
@@ -600,6 +670,6 @@ export function encodeMainPass(
   pass: RhiRenderPassEncoder,
   selector?: PassSelector,
   options?: MainPassOptions,
-): void {
-  recordMainPass(c, selector, options, pass);
+): GpuDrivenStandardPbrFrameResources | undefined {
+  return recordMainPass(c, selector, options, pass);
 }

package/src/record/material-uniforms.ts

@@ -41,7 +41,7 @@ export function uploadMaterialUniforms(c: _InternalRenderPipelineContext): void
     );
     for (let materialSlot = 0; materialSlot < materialSlots.length; materialSlot += 1) {
       const mat = materialSlots[materialSlot];
-      const entry = validatedOrdered[materialSlotOwners[materialSlot] ?? -1];
+      const entry = materialSlotOwners[materialSlot];
       if (mat === undefined || entry === undefined) continue;
 
       // feat-20260625-refactor-sprite-as-transparent-mesh M3 / w13 (D-2):