@forgeax/engine-render 0.1.28 → 0.1.30

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,
@@ -7,16 +8,24 @@ import {
   type TextureView,
 } from '@forgeax/engine-rhi';
 import type { PassKind, PassSelector } from '@forgeax/engine-types';
-import { createHdrpUnifiedBindGroup, getOrCreateHdrpBuffers } from '../hdrp-buffers';
+import {
+  createGpuDrivenLightingBindGroup,
+  createHdrpUnifiedBindGroup,
+  getOrCreateHdrpBuffers,
+} from '../hdrp-buffers';
 import { getOrCreateIblCache } from '../ibl/IblPipelineCache';
 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 {
+  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 +66,17 @@ 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;
+  /** Select the material temporal entry's binary coverage output. */
+  readonly coverageOnly?: boolean;
+  readonly gpuDriven?: {
+    readonly projection: RenderPipelineGpuDrivenProjection;
+    readonly resources: GraphResourceResolver;
+  };
 };
 
 function isTransmissionMaterial(material: MaterialSnapshot): boolean {
@@ -117,7 +136,7 @@ export function recordMainPass(
   selector?: PassSelector,
   options?: MainPassOptions,
   graphPass?: RhiRenderPassEncoder,
-): void {
+): GpuDrivenStandardPbrFrameResources | undefined {
   const {
     runtime,
     world,
@@ -143,6 +162,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 +301,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
@@ -447,6 +475,13 @@ export function recordMainPass(
     // 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.
+    // Selection keys use the extracted frame index, never World.identity.
+    const hasProbeBindings = (c.reflectionProbes?.table.rows.length ?? 0) > 0;
+    const worldIndices = hasProbeBindings
+      ? new Map(
+          validatedOrdered.map((entry) => [entry.world ?? world, entry.source.worldId] as const),
+        )
+      : undefined;
     const perSubmeshMaterialBgDeps: PerSubmeshMaterialBgDeps = {
       runtime,
       pipelineState,
@@ -458,8 +493,10 @@ export function recordMainPass(
       resolveRenderTargetTextureSource: runtime.resolveRenderTargetTextureSource,
       resolveReflectionProbeResources: (materialWorld, entityKey) => {
         const reflectionProbes = c.reflectionProbes;
-        if (reflectionProbes === undefined) return undefined;
-        const selection = reflectionProbes.selections.get(`${materialWorld.identity}:${entityKey}`);
+        if (reflectionProbes === undefined || !hasProbeBindings) return undefined;
+        const selection = reflectionProbes.selections.get(
+          `${worldIndices?.get(materialWorld)}:${entityKey}`,
+        );
         if (selection === undefined) return undefined;
         const binding = resolveReflectionProbeBinding(selection, reflectionProbes.table);
         if (binding.useSkylight || binding.probeIndex === undefined) return undefined;
@@ -477,17 +514,26 @@ export function recordMainPass(
           irradianceView: skylightResources.irradianceView,
           irradianceSampler: skylightResources.irradianceSampler,
           prefilterView: row.filteredView,
+          skylightPrefilterView: skylightResources.prefilterView,
           prefilterSampler: row.sampler,
           brdfLutView: skylightResources.brdfLutView,
           brdfLutSampler: skylightResources.brdfLutSampler,
           intensityBuffer: row.uniformBuffer,
         };
-        return probeResources;
+        return { resources: probeResources, probeIndex: row.index };
       },
       materialBgShared: frameState.materialBgShared,
       materialBgAssemblyCache: c.materialBgAssemblyCache,
       frameState,
       bindGroupCounts,
+      ...(gpuDrivenStandardPbrFrameResources?.sceneMaterialBuffer === undefined &&
+      gpuDrivenSceneMaterialBuffer === undefined
+        ? {}
+        : {
+            sceneMaterialBuffer:
+              gpuDrivenStandardPbrFrameResources?.sceneMaterialBuffer ??
+              gpuDrivenSceneMaterialBuffer,
+          }),
       ...(transmissionBackdropView === undefined ? {} : { transmissionBackdropView }),
     };
     const buildPerSubmeshMaterialBg = (
@@ -503,7 +549,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 +558,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 +566,60 @@ export function recordMainPass(
         owner.world ?? world,
       );
     }
+    if (gpuDrivenStandardPbrFrameResources !== undefined) {
+      gpuDrivenStandardPbrFrameResources.resolveClusteredMeshBindGroup = (binding) => {
+        const buffers = getOrCreateHdrpBuffers(
+          runtime,
+          frameState.installedPipelineConfig?.clusterGrid,
+        );
+        const layout =
+          binding.paletteBuffer === undefined
+            ? pipelineState.hdrpMeshBindGroupLayout
+            : pipelineState.hdrpSkinMeshBindGroupLayout;
+        const group =
+          buffers === null || layout == null
+            ? null
+            : createGpuDrivenLightingBindGroup(
+                runtime,
+                buffers,
+                layout,
+                binding,
+                c.hdrpSsaoBlurredView,
+              );
+        if (group === null)
+          throw new RhiError({
+            code: 'rhi-not-available',
+            expected: 'scene-index clustered lighting binding',
+            hint: 'publish scene rows and the current lighting/AO resources before indirect drawing',
+          });
+        return group;
+      };
+      gpuDrivenStandardPbrFrameResources.materialBindGroups.length = 0;
+      gpuDrivenStandardPbrFrameResources.materialBindGroups.push(...preparedMaterialBindGroups);
+      gpuDrivenStandardPbrFrameResources.colorFormats = colorFormats;
+      const selectedMaterialSlots = new Set<number>();
+      if (matchedMaterials === null)
+        delete gpuDrivenStandardPbrFrameResources.selectedMaterialSlots;
+      else gpuDrivenStandardPbrFrameResources.selectedMaterialSlots = selectedMaterialSlots;
+      gpuDrivenStandardPbrFrameResources.materialSlotIndicesByEntity.clear();
+      for (let index = 0; index < validatedOrdered.length; index += 1) {
+        const entry = validatedOrdered[index];
+        if (entry === undefined) continue;
+        const selected = matchedMaterials?.get(entry.renderableIndex);
+        const materials =
+          entry.source.materials.length > 0 ? entry.source.materials : [entry.source.material];
+        for (let slot = 0; slot < materials.length; slot += 1) {
+          const handle = materials[slot]?.materialHandle ?? -1;
+          const globalSlot = materialSlotIndices[index]?.[slot];
+          if (globalSlot !== undefined && selected?.has(handle))
+            selectedMaterialSlots.add(globalSlot);
+        }
+        gpuDrivenStandardPbrFrameResources.materialSlotIndicesByEntity.set(
+          worldEntityKey(entry.source.worldId, entry.source.entityKey),
+          materialSlotIndices[index] ?? [],
+        );
+      }
+    }
     const resolveMaterialBindGroup = (
       materialSlot: number,
       material: MaterialSnapshot,
@@ -528,6 +627,7 @@ export function recordMainPass(
       materialWorld: World = world,
       materialShaderId: string | undefined = material.materialShaderId,
     ): BindGroup =>
+      !hasProbeBindings &&
       materialShaderId === material.materialShaderId &&
       materialShaderId !== POINTS_LINES_MATERIAL_SHADER_ID
         ? (preparedMaterialBindGroups[materialSlot] ??
@@ -554,6 +654,8 @@ export function recordMainPass(
         resolveMaterialBindGroup,
         passKind,
         selectedDispatch,
+        colorFormats,
+        options?.coverageOnly ?? false,
       );
     };
     if (c.profilePhase === undefined) {
@@ -566,6 +668,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 +712,6 @@ export function recordMainPass(
         materialSlotIndices,
         sampleCount,
         resolveMaterialBindGroup,
-        skylightResources,
         graphPass,
         selectedDispatch,
       );
@@ -593,6 +721,7 @@ export function recordMainPass(
   if (!geometryPassEnded && graphPass === undefined) {
     pass.end();
   }
+  return gpuDrivenStandardPbrFrameResources;
 }
 
 export function encodeMainPass(
@@ -600,6 +729,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):

package/src/record/mesh-ssbo.ts

@@ -1,5 +1,6 @@
 import { mat3 } from '@forgeax/engine-math';
 import { type BindGroup, type Buffer, RhiError, type RhiQueue } from '@forgeax/engine-rhi';
+import { ok, type Result } from '@forgeax/engine-types';
 import type { DispatchEntry } from '../render-system-extract';
 import {
   TRANSPARENT_SORT_MODE_LAYER_Y,
@@ -127,6 +128,42 @@ export function getOrCreateFromChain(
   return bg;
 }
 
+/**
+ * Result-preserving sibling of `getOrCreateFromChain`.  RHI creation can fail
+ * transiently during recovery or capability probing; a failed attempt must
+ * not enter the cache and must remain a structured Result for the caller.
+ */
+export function getOrCreateFromChainResult<E>(
+  root: WeakMap<object, unknown>,
+  handles: readonly object[],
+  variant: string,
+  factory: () => Result<BindGroup, E>,
+  counts: { createBindGroup: number; keys: string[] },
+): Result<BindGroup, E> {
+  let node = root;
+  for (const h of handles) {
+    let next = node.get(h) as WeakMap<object, unknown> | undefined;
+    if (next === undefined) {
+      next = new WeakMap();
+      node.set(h, next);
+    }
+    node = next;
+  }
+  let leaf = node.get(BIND_GROUP_CHAIN_LEAF_KEY) as Map<string, BindGroup> | undefined;
+  if (leaf === undefined) {
+    leaf = new Map();
+    node.set(BIND_GROUP_CHAIN_LEAF_KEY, leaf);
+  }
+  const hit = leaf.get(variant);
+  if (hit !== undefined) return ok(hit);
+  const created = factory();
+  if (!created.ok) return created;
+  counts.createBindGroup += 1;
+  counts.keys.push(variant);
+  leaf.set(variant, created.value);
+  return created;
+}
+
 /**
  * Read a cached bind group using the same variable-depth chain contract as
  * `getOrCreateFromChain`. Readers must traverse the terminal marker instead
@@ -376,6 +413,7 @@ export function uploadMeshSsboBatch(
   meshStorageBuffer: { readonly buffer: Buffer },
   validatedOrdered: readonly ValidatedRenderable[],
   foldDispatchPlan: FoldDispatchPlan | null,
+  startSlot = 0,
 ): void {
   const slotCount = validatedOrdered.length;
   const neededBytes = slotCount * MESH_PER_ENTITY_STRIDE;
@@ -450,7 +488,7 @@ export function uploadMeshSsboBatch(
   if (neededBytes > 0) {
     const meshUpload = queue.writeBuffer(
       meshStorageBuffer.buffer,
-      0,
+      startSlot * MESH_PER_ENTITY_STRIDE,
       _meshSsboScratch,
       0,
       neededBytes,
@@ -511,17 +549,26 @@ export interface FoldBucket {
  * minimal shape. The gate read inside the helper uses `=== true` /
  * `!== true` so both `false` and `undefined` enter the singleton branch.
  *
- * feat-20260625-refactor-sprite-as-transparent-mesh R2 fix-up: gate
- * migrated from `shadingModel === 'sprite'` (the union member was
- * removed in M3 / w15) to `transparent === true` (the new SSOT for
- * "routes through the LDR split sub-pass" — same predicate the
- * `splitLdrSprite` filter at render-system-record.ts:4826/5612 uses).
+ * feat-20260625-refactor-sprite-as-transparent-mesh R2 fix-up: the
+ * transparent flag identifies the LDR split sub-pass, while the shader id
+ * identifies the sprite owner that is safe to fold. Standard PBR Alpha Blend
+ * remains singleton so its geometry pass keeps one projection row per draw.
  */
 export interface FoldRenderableLike {
   readonly transform: { readonly world: Float32Array };
   readonly material: { readonly transparent?: boolean | undefined };
 }
 
+const FOLDABLE_TRANSPARENT_SHADER_IDS = new Set(['forgeax::sprite', 'forgeax::sprite-lit']);
+
+function isFoldEligible(entry: DispatchEntry, renderables: readonly FoldRenderableLike[]): boolean {
+  return (
+    renderables[entry.renderableIndex]?.material.transparent === true &&
+    entry.materialShaderId !== undefined &&
+    FOLDABLE_TRANSPARENT_SHADER_IDS.has(entry.materialShaderId)
+  );
+}
+
 /**
  * Linear-scan fold operator (plan-strategy D-1).
  *
@@ -588,7 +635,7 @@ export function foldDispatchBuckets(
   // identity and renders the 3D geometry at the origin — collapsing the
   // frame to black (hello-room CI regression).
   //
-  // Concept-count fix: encode "fold is transparent-sub-pass-only" at the
+  // Concept-count fix: encode "fold is transparent-sprite-sub-pass-only" at the
   // head selection point — the gate is the single bucket-key invariant
   // that makes both dispatch sites correct without coupling identity-
   // overwrite logic to a separate check (avoiding the D-9 shared-exit
@@ -603,10 +650,9 @@ export function foldDispatchBuckets(
   //
   // feat-20260625 R2 fix-up: pre-feat the gate was `shadingModel ===
   // 'sprite'`; M3 / w15 narrowed the shadingModel union to
-  // `'unlit' | undefined` (the `'sprite'` discriminator was the design
-  // ablation target), so the gate now reads `material.transparent` —
-  // the new SSOT for "routes through the LDR split sub-pass" mirrored
-  // on `computeSplitLdrSprite` + the `splitLdrSprite` skip filter.
+  // `'unlit' | undefined`. The current gate retains the transparent SSOT
+  // and adds the explicit sprite shader identity so Standard PBR Alpha Blend
+  // cannot enter this fold path.
   const buckets: FoldBucket[] = [];
   let runStart = 0;
   while (runStart < orderedEntries.length) {
@@ -621,8 +667,7 @@ export function foldDispatchBuckets(
     // carrier (extract stage derives it from the first pass's
     // `renderState.blend !== undefined`, post-feat-20260626-collapse;
     // see `MaterialSnapshot.transparent`).
-    const headTransparent = renderables[head.renderableIndex]?.material.transparent;
-    if (headTransparent !== true) {
+    if (!isFoldEligible(head, renderables)) {
       buckets.push(makeSingletonBucket(head, renderables, mode));
       runStart += 1;
       continue;
@@ -638,8 +683,7 @@ export function foldDispatchBuckets(
       // Same materialHandle implies same transparent flag in production
       // (material asset identity), but the check costs O(1) per cand and
       // makes the bucket invariant locally readable.
-      const candTransparent = renderables[cand.renderableIndex]?.material.transparent;
-      if (candTransparent !== true) break;
+      if (!isFoldEligible(cand, renderables)) break;
       const candSortKey = readSortKey(mode, cand.renderableIndex, renderables);
       if (candSortKey !== headSortKey) break;
       runEnd += 1;

package/src/record/prepared-material-bindings.ts

@@ -0,0 +1,238 @@
+import { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
+import type { World } from '@forgeax/engine-ecs';
+import type { BindGroupEntry, BindGroupLayout, Buffer } from '@forgeax/engine-rhi';
+import { err, ok } from '@forgeax/engine-rhi';
+import {
+  derive,
+  type Handle,
+  type MaterialAsset,
+  type MaterialTextureValue,
+  materialValuesToLinearRuntime,
+  type SamplerAsset,
+} from '@forgeax/engine-types';
+import { transmissionBackdropAvailable } from '../assembly/device-feature-admission';
+import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_UNIFORM } from '../gpu-usage';
+import type { SkylightBindGroupResources } from '../ibl/skylight-bind-group';
+import { assembleMaterialWithSkylightEntries } from '../ibl/skylight-bind-group';
+import {
+  applyParamSchemaDefaultsToUbo,
+  applyParamSnapshotToUbo,
+  defaultViewForUserRegionField,
+  residentTextureView,
+} from './main-pass-material';
+import type { RenderSystemInternals } from './render-context';
+
+export type PreparedResolverCaches = {
+  readonly preparedPipelineIds: WeakMap<object, string>;
+  readonly preparedMaterialPipelineShaders: WeakMap<object, string>;
+  readonly preparedGroup0Pipelines: WeakSet<object>;
+  readonly preparedViewOnlyPipelines: WeakSet<object>;
+  readonly preparedRenderMaterialPipelines: WeakSet<object>;
+  readonly preparedAssetHandles: WeakMap<World, Map<string, number>>;
+};
+
+export function createPreparedResolverCaches(): PreparedResolverCaches {
+  return {
+    preparedPipelineIds: new WeakMap(),
+    preparedMaterialPipelineShaders: new WeakMap(),
+    preparedGroup0Pipelines: new WeakSet(),
+    preparedViewOnlyPipelines: new WeakSet(),
+    preparedRenderMaterialPipelines: new WeakSet(),
+    preparedAssetHandles: new WeakMap(),
+  };
+}
+
+function preparedHandle<Brand extends string>(
+  runtime: RenderSystemInternals,
+  caches: PreparedResolverCaches,
+  world: World,
+  guid: string,
+  brand: Brand,
+): Handle<Brand, 'shared'> | undefined {
+  let handles = caches.preparedAssetHandles.get(world);
+  if (handles === undefined) {
+    handles = new Map();
+    caches.preparedAssetHandles.set(world, handles);
+  }
+  const key = `${brand}:${guid.toLowerCase()}`;
+  const cached = handles.get(key);
+  if (cached !== undefined) return cached as Handle<Brand, 'shared'>;
+  const asset = runtime.assets.lookup(guid);
+  if (asset === undefined) return undefined;
+  const handle = world.allocSharedRef(brand, asset);
+  handles.set(key, handle as number);
+  return handle;
+}
+
+export function preparedMaterialBindings(
+  runtime: RenderSystemInternals,
+  caches: PreparedResolverCaches,
+  worlds: readonly World[],
+  materialShaderId: string,
+  worldIndex: number,
+  materialGuid: string,
+  layout: BindGroupLayout,
+  skylightResources?: SkylightBindGroupResources,
+) {
+  const world = worlds[worldIndex];
+  const material = runtime.assets.lookup(materialGuid) as MaterialAsset | undefined;
+  const pipelineState = runtime.getPipelineState();
+  if (world === undefined || material?.kind !== 'material' || pipelineState === null) {
+    return err(new Error('prepared material asset is unavailable'));
+  }
+  const schema = runtime.getParamSchema?.(materialShaderId) ?? [];
+  // Feature materials share the ordinary linear parameter domain and semantic texture defaults.
+  const values = materialValuesToLinearRuntime(
+    material.values,
+    [...schema, ...(material.parameters ?? [])],
+    material.colorSpace,
+  );
+  const derived = derive(schema);
+  const fields = [...derived.textureFieldNames];
+  let buffer: Buffer | undefined;
+  let payloadByteLength = 0;
+  if (derived.uboLayout.totalBytes > 0) {
+    const payload = new Uint8Array(Math.max(16, derived.uboLayout.totalBytes));
+    applyParamSchemaDefaultsToUbo(payload, schema);
+    applyParamSnapshotToUbo(
+      payload,
+      schema,
+      values as Readonly<Record<string, number | readonly number[]>>,
+    );
+    const created = runtime.device.createBuffer({
+      label: `prepared-material:${materialGuid}`,
+      size: payload.byteLength,
+      usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+    });
+    if (!created.ok) return created;
+    buffer = created.value;
+    payloadByteLength = payload.byteLength;
+    const written = runtime.device.queue.writeBuffer(buffer, 0, payload);
+    if (!written.ok) {
+      runtime.device.destroyBuffer(buffer);
+      return written;
+    }
+  }
+  const textureResources: Array<{
+    sampler: import('@forgeax/engine-rhi').Sampler;
+    view: import('@forgeax/engine-rhi').TextureView;
+  }> = [];
+  for (const field of fields) {
+    if (field === undefined) continue;
+    const value = values[field];
+    const textureValue =
+      typeof value === 'object' && value !== null && 'texture' in value
+        ? (value as MaterialTextureValue)
+        : undefined;
+    let sampler = pipelineState.defaultSampler;
+    if (textureValue?.sampler !== undefined) {
+      const handle = preparedHandle(
+        runtime,
+        caches,
+        world,
+        String(textureValue.sampler),
+        'SamplerAsset',
+      );
+      if (handle !== undefined) {
+        const asset = resolveAssetHandle<SamplerAsset>(world, handle);
+        if (asset.ok) {
+          const resident = runtime.gpuStore.ensureSamplerResident(handle, asset.value, world);
+          if (resident.ok) sampler = resident.value;
+        }
+      }
+    }
+    let view = defaultViewForUserRegionField(field, pipelineState, schema);
+    if (textureValue !== undefined) {
+      const handle = preparedHandle(
+        runtime,
+        caches,
+        world,
+        String(textureValue.texture),
+        'TextureAsset',
+      );
+      if (handle !== undefined) {
+        view = residentTextureView(world, runtime.gpuStore, runtime, handle) ?? view;
+      }
+    }
+    textureResources.push({ sampler, view });
+  }
+  const entries: BindGroupEntry[] = [];
+  let textureIndex = 0;
+  for (let index = 0; index < derived.bglEntries.length; index += 1) {
+    const expected = derived.bglEntries[index];
+    if (expected?.buffer?.type === 'uniform' && buffer !== undefined) {
+      entries.push({
+        binding: expected.binding,
+        resource: { kind: 'buffer', value: { buffer, size: payloadByteLength } },
+      });
+      continue;
+    }
+    const textureResource = textureResources[textureIndex];
+    if (
+      expected?.sampler?.type === 'filtering' &&
+      derived.bglEntries[index + 1]?.texture !== undefined &&
+      textureResource !== undefined
+    ) {
+      entries.push({
+        binding: expected.binding,
+        resource: { kind: 'sampler', value: textureResource.sampler },
+      });
+      continue;
+    }
+    if (expected?.texture !== undefined && textureResource !== undefined) {
+      entries.push({
+        binding: expected.binding,
+        resource: { kind: 'textureView', value: textureResource.view },
+      });
+      textureIndex += 1;
+      continue;
+    }
+    if (buffer !== undefined) runtime.device.destroyBuffer(buffer);
+    return err(new Error('prepared material schema contains unsupported binding kinds'));
+  }
+  const fallback = pipelineState.skylightFallback;
+  if (fallback === null) {
+    if (buffer !== undefined) runtime.device.destroyBuffer(buffer);
+    return err(new Error('prepared material skylight fallback is unavailable'));
+  }
+  const completeEntries = assembleMaterialWithSkylightEntries(
+    entries,
+    skylightResources ?? {
+      irradianceView: fallback.irradianceView,
+      irradianceSampler: fallback.sampler,
+      prefilterView: fallback.prefilterView,
+      prefilterSampler: fallback.sampler,
+      brdfLutView: fallback.brdfLutView,
+      brdfLutSampler: fallback.sampler,
+      intensityBuffer: fallback.intensityBuffer,
+    },
+    transmissionBackdropAvailable(runtime.device.limits.maxSampledTexturesPerShaderStage)
+      ? undefined
+      : null,
+  );
+  // Per-shader PBR layouts reserve the scene-material SSBO at binding 46 on
+  // storage-capable devices. Prepared feature materials use this same layout,
+  // so they must provide the neutral producer-owned table even when their
+  // authored shader does not read it. Omitting the entry makes Dawn reject the
+  // bind group before submission.
+  if (runtime.device.caps.storageBuffer) {
+    completeEntries.push({
+      binding: 46,
+      resource: {
+        kind: 'buffer',
+        value: { buffer: pipelineState.meshStorageBuffer.buffer },
+      },
+    });
+  }
+  const group = runtime.device.createBindGroup({ layout, entries: completeEntries });
+  if (!group.ok) {
+    if (buffer !== undefined) runtime.device.destroyBuffer(buffer);
+    return group;
+  }
+  if (buffer === undefined) return group;
+  return ok({
+    handle: group.value,
+    dynamicOffsets: [0],
+    release: () => runtime.device.destroyBuffer(buffer),
+  });
+}