@forgeax/engine-render 0.1.27 → 0.1.29

package/src/gpu-scene.ts

@@ -1,5 +1,6 @@
 import type { Buffer, Result, RhiDevice } from '@forgeax/engine-rhi';
 import { err, ok, RhiError } from '@forgeax/engine-rhi';
+import { createStandardPbrArtifactReceipt } from '@forgeax/engine-shader';
 import {
   GPU_SCENE_LAYOUTS,
   type GpuSceneTableLayout,
@@ -11,6 +12,7 @@ import {
   GPU_BUFFER_USAGE_STORAGE,
 } from './gpu-usage';
 import type { GpuSceneInspection } from './inspection-types';
+import { packStandardPbrMaterialRow } from './material-row';
 import type { RenderSceneApplyResult, RenderSceneSlot } from './scene/render-scene-types';
 
 export type { GpuSceneInspection } from './inspection-types';
@@ -20,6 +22,7 @@ const INSTANCE = GPU_SCENE_LAYOUTS.instance;
 const TRANSFORM = GPU_SCENE_LAYOUTS.transform;
 const DRAW_TEMPLATE = GPU_SCENE_LAYOUTS.drawTemplate;
 const MATERIAL = GPU_SCENE_LAYOUTS.material;
+const STANDARD_PBR_RECEIPT = createStandardPbrArtifactReceipt();
 const PRIMITIVE_ACTIVE = 1;
 const PRIMITIVE_HAS_BOUNDS = 2;
 const PRIMITIVE_GPU_DRIVEN = 4;
@@ -50,6 +53,7 @@ class StableRangeAllocator {
   private readonly free: Array<{ start: number; count: number }> = [];
 
   allocate(count: number): number {
+    if (count <= 0) return 0;
     const freeIndex = this.free.findIndex((range) => range.count >= count);
     if (freeIndex >= 0) {
       const range = this.free[freeIndex];
@@ -157,6 +161,29 @@ function writeMat4(view: DataView, byteOffset: number, value: Float32Array): voi
   }
 }
 
+function writeChangedMat4(
+  view: DataView,
+  byteOffset: number,
+  matrix: Float32Array,
+  sourceOffset = 0,
+): boolean {
+  let changed = false;
+  for (let lane = 0; lane < 16; lane += 1) {
+    const at = byteOffset + lane * 4;
+    const value = matrix[sourceOffset + lane] ?? 0;
+    if (Object.is(view.getFloat32(at, true), value)) continue;
+    view.setFloat32(at, value, true);
+    changed = true;
+  }
+  return changed;
+}
+
+function writeChangedU32(view: DataView, byteOffset: number, value: number): boolean {
+  if (view.getUint32(byteOffset, true) === value) return false;
+  view.setUint32(byteOffset, value, true);
+  return true;
+}
+
 function writeVec4(view: DataView, byteOffset: number, values: readonly number[]): void {
   for (let lane = 0; lane < 4; lane += 1) {
     view.setFloat32(byteOffset + lane * 4, values[lane] ?? 0, true);
@@ -179,14 +206,7 @@ function stableU32(value: string): number {
 function coalesceSlots(
   slots: readonly number[],
 ): readonly { readonly start: number; readonly end: number }[] {
-  let alreadyOrdered = true;
-  for (let index = 1; index < slots.length; index += 1) {
-    if ((slots[index] ?? 0) <= (slots[index - 1] ?? 0)) {
-      alreadyOrdered = false;
-      break;
-    }
-  }
-  const ordered = alreadyOrdered ? slots : [...new Set(slots)].sort((a, b) => a - b);
+  const ordered = [...new Set(slots)].sort((a, b) => a - b);
   const ranges: Array<{ start: number; end: number }> = [];
   for (const slot of ordered) {
     const previous = ranges.at(-1);
@@ -206,14 +226,18 @@ export class GpuScene {
   private transformBytes: Uint8Array;
   private transformView: DataView;
   private buffers: GpuSceneBuffers;
+  /** Table buffers replaced by capacity growth stay alive until the scene is retired. */
+  private readonly retiredBuffers: Buffer[] = [];
   private uploadRanges = 0;
   private uploadBytes = 0;
   private capacityGrows = 0;
   private fullRebuilds = 0;
   private clearedSlots = 0;
   private noChangeFrames = 0;
+  /** Monotonic content identity consumed by shadow-cache invalidation. */
+  private sceneContentRevision = 0;
   private identityUploaded = false;
-  private readonly allocations: Array<PrimitiveAllocation | undefined> = [];
+  private readonly allocations = new Map<number, PrimitiveAllocation>();
   private readonly instances = new StableRangeAllocator();
   private readonly transforms = new StableRangeAllocator();
   private readonly draws = new StableRangeAllocator();
@@ -276,16 +300,42 @@ export class GpuScene {
     return this.buffers.material;
   }
 
+  get contentRevision(): number {
+    return this.sceneContentRevision;
+  }
+
+  /**
+   * Resolve the stable scene-material row for one retained render slot. The
+   * GPU-driven shadow projection uses this producer-owned index instead of
+   * reconstructing material identity from a batch position.
+   */
+  materialIndexForSlot(slot: number, materialSlot: number): number | undefined {
+    const allocation = this.allocations.get(slot);
+    if (
+      allocation === undefined ||
+      !Number.isInteger(materialSlot) ||
+      materialSlot < 0 ||
+      materialSlot >= allocation.materialCount
+    ) {
+      return undefined;
+    }
+    return allocation.materialStart + materialSlot;
+  }
+
   sync(delta: RenderSceneApplyResult): Result<GpuSceneSyncResult, RhiError> {
     for (const transformIndex of this.pendingTemporalUploads) {
       this.writesByTable.transform.push(transformIndex);
     }
     const pendingWrites = TABLE_NAMES.some((name) => this.writesByTable[name].length > 0);
+    const contentUpdatedSlots = delta.contentUpdatedSlots;
+    const instanceUpdatedSlots = delta.instanceUpdatedSlots;
     if (
       delta.createdSlots.length === 0 &&
       delta.updatedSlots.length === 0 &&
       delta.recreatedSlots.length === 0 &&
       delta.removedSlots.length === 0 &&
+      contentUpdatedSlots.length === 0 &&
+      instanceUpdatedSlots.length === 0 &&
       !pendingWrites
     ) {
       this.noChangeFrames += 1;
@@ -296,8 +346,8 @@ export class GpuScene {
       writesByTable.transform.push(0);
     }
     let highestChangedSlot = -1;
-    const contentUpdatedSlots = delta.contentUpdatedSlots ?? [];
     const contentUpdatedSlotIds = new Set(contentUpdatedSlots.map((record) => record.slot));
+    const instanceUpdatedSlotIds = new Set(instanceUpdatedSlots.map((record) => record.slot));
     const allocationResets = new Set<number>();
     // RenderScene may recycle a released CPU slot for a different identity in
     // the same delta. Clear the old GPU allocation before ensuring the new
@@ -307,11 +357,16 @@ export class GpuScene {
       if (record.slot > highestChangedSlot) highestChangedSlot = record.slot;
       this.clearSlot(record.slot, writesByTable);
     }
-    for (const records of [delta.createdSlots, contentUpdatedSlots, delta.recreatedSlots]) {
+    for (const records of [
+      delta.createdSlots,
+      contentUpdatedSlots,
+      instanceUpdatedSlots,
+      delta.recreatedSlots,
+    ]) {
       for (const record of records) {
-        const previous = this.allocations[record.slot];
+        const previous = this.allocations.get(record.slot);
         this.ensureAllocation(record, writesByTable);
-        if (previous !== this.allocations[record.slot]) allocationResets.add(record.slot);
+        if (previous !== this.allocations.get(record.slot)) allocationResets.add(record.slot);
         if (record.slot > highestChangedSlot) highestChangedSlot = record.slot;
       }
     }
@@ -331,21 +386,27 @@ export class GpuScene {
       if (!grown.ok) return grown;
     }
 
-    for (const record of delta.createdSlots) this.writeSlot(record, true, writesByTable);
-    for (const record of contentUpdatedSlots) {
-      this.writeSlot(record, allocationResets.has(record.slot), writesByTable);
-    }
-    for (const record of delta.updatedSlots) {
-      if (contentUpdatedSlotIds.has(record.slot)) continue;
+    const publications = [...delta.createdSlots, ...delta.updatedSlots, ...delta.recreatedSlots];
+    const newSlots = new Set(
+      [...delta.createdSlots, ...delta.recreatedSlots].map((record) => record.slot),
+    );
+    for (const record of publications) {
+      const reset = newSlots.has(record.slot) || allocationResets.has(record.slot);
+      if (reset || contentUpdatedSlotIds.has(record.slot)) {
+        this.writeSlot(record, reset, writesByTable);
+        continue;
+      }
+      if (instanceUpdatedSlotIds.has(record.slot))
+        this.writeInstanceTransforms(record, writesByTable);
       this.writeRootTransform(record, false, writesByTable);
     }
-    for (const record of delta.recreatedSlots) this.writeSlot(record, true, writesByTable);
     const uploaded = this.uploadRows(writesByTable);
     if (!uploaded.ok) return uploaded;
     this.pendingTemporalUploads.clear();
     for (const name of TABLE_NAMES) writesByTable[name].length = 0;
     this.identityUploaded = true;
     this.clearedSlots += delta.removedSlots.length;
+    this.sceneContentRevision += 1;
     return ok({
       ranges: uploaded.value.ranges,
       bytes: uploaded.value.bytes,
@@ -368,10 +429,6 @@ export class GpuScene {
     for (const range of ranges) {
       for (let index = range.start; index < range.end; index += 1) {
         this.pendingTemporalUploads.add(index);
-      }
-    }
-    for (const range of ranges) {
-      for (let index = range.start; index < range.end; index += 1) {
         this.transformBytes.copyWithin(
           index * TRANSFORM.stride + previousOffset,
           index * TRANSFORM.stride + currentOffset,
@@ -401,7 +458,7 @@ export class GpuScene {
   }
 
   rebuild(slots: readonly RenderSceneSlot[]): Result<GpuSceneSyncResult, RhiError> {
-    this.allocations.length = 0;
+    this.allocations.clear();
     this.instances.reset();
     this.transforms.reset(1);
     this.draws.reset();
@@ -444,6 +501,7 @@ export class GpuScene {
     this.uploadRanges += TABLE_NAMES.length;
     this.uploadBytes += bytes;
     this.fullRebuilds += 1;
+    this.sceneContentRevision += 1;
     this.identityUploaded = true;
     return ok({ ranges: TABLE_NAMES.length, bytes, grew, cleared: 0 });
   }
@@ -485,6 +543,7 @@ export class GpuScene {
   dispose(): void {
     if (this.disposed) return;
     this.disposed = true;
+    for (const buffer of this.retiredBuffers) this.device.destroyBuffer(buffer);
     for (const buffer of Object.values(this.buffers)) this.device.destroyBuffer(buffer);
   }
 
@@ -493,7 +552,7 @@ export class GpuScene {
     resetPrevious: boolean,
     writes: Record<GpuSceneTableName, number[]>,
   ): void {
-    const allocation = this.allocations[record.slot];
+    const allocation = this.allocations.get(record.slot);
     if (allocation === undefined) throw new RangeError('GPU Scene allocation unavailable');
     const primitiveOffset = record.slot * PRIMITIVE.stride;
     const primitive = new DataView(this.tableBytes.primitive);
@@ -556,25 +615,49 @@ export class GpuScene {
       const instanceOffset = instanceIndex * INSTANCE.stride;
       const transformIndex =
         allocation.instanceTransformCount === 0 ? 0 : allocation.instanceTransformStart + ordinal;
-      instance.setUint32(instanceOffset + offset(INSTANCE, 'primitiveIndex'), record.slot, true);
-      instance.setUint32(instanceOffset + offset(INSTANCE, 'transformIndex'), transformIndex, true);
-      instance.setUint32(instanceOffset + offset(INSTANCE, 'customDataStart'), 0, true);
-      instance.setUint32(instanceOffset + offset(INSTANCE, 'flags'), PRIMITIVE_ACTIVE, true);
+      let metadataChanged = writeChangedU32(
+        instance,
+        instanceOffset + offset(INSTANCE, 'primitiveIndex'),
+        record.slot,
+      );
+      metadataChanged =
+        writeChangedU32(
+          instance,
+          instanceOffset + offset(INSTANCE, 'transformIndex'),
+          transformIndex,
+        ) || metadataChanged;
+      metadataChanged =
+        writeChangedU32(
+          instance,
+          instanceOffset + offset(INSTANCE, 'customDataStart'),
+          record.snapshot.skin?.customDataStart ?? 0,
+        ) || metadataChanged;
+      metadataChanged =
+        writeChangedU32(instance, instanceOffset + offset(INSTANCE, 'flags'), PRIMITIVE_ACTIVE) ||
+        metadataChanged;
       if (allocation.instanceTransformCount > 0) {
-        const local = record.snapshot.instances?.transforms.subarray(
-          ordinal * 16,
-          ordinal * 16 + 16,
-        );
-        const localWorld = local?.length === 16 ? local : IDENTITY_MATRIX;
+        const transforms = record.snapshot.instances?.transforms;
+        const hasLocal = transforms !== undefined && transforms.length >= (ordinal + 1) * 16;
+        const local = hasLocal ? transforms : IDENTITY_MATRIX;
+        const sourceOffset = hasLocal ? ordinal * 16 : 0;
         const localOffset = transformIndex * TRANSFORM.stride;
-        const localCurrentOffset = localOffset + offset(TRANSFORM, 'currentWorld');
-        const localPreviousOffset = localOffset + offset(TRANSFORM, 'previousWorld');
-        writeMat4(transform, localCurrentOffset, localWorld);
-        if (resetPrevious) writeMat4(transform, localPreviousOffset, localWorld);
-        else this.pendingTemporalTransforms.add(transformIndex);
-        writes.transform.push(transformIndex);
+        const changed = writeChangedMat4(
+          transform,
+          localOffset + offset(TRANSFORM, 'currentWorld'),
+          local,
+          sourceOffset,
+        );
+        if (resetPrevious)
+          writeChangedMat4(
+            transform,
+            localOffset + offset(TRANSFORM, 'previousWorld'),
+            local,
+            sourceOffset,
+          );
+        else if (changed) this.pendingTemporalTransforms.add(transformIndex);
+        if (changed || resetPrevious) writes.transform.push(transformIndex);
       }
-      writes.instance.push(instanceIndex);
+      if (metadataChanged || resetPrevious) writes.instance.push(instanceIndex);
     }
 
     this.writeRootTransform(record, resetPrevious, writes);
@@ -623,76 +706,74 @@ export class GpuScene {
       writes.drawTemplate.push(drawIndex);
     }
 
-    const material = new DataView(this.tableBytes.material);
+    this.writeMaterialSlot(record, writes);
+  }
+
+  private writeMaterialSlot(
+    record: RenderSceneSlot,
+    writes: Record<GpuSceneTableName, number[]>,
+  ): void {
+    const allocation = this.allocations.get(record.slot);
+    if (allocation === undefined) throw new RangeError('GPU Scene allocation unavailable');
     for (let ordinal = 0; ordinal < allocation.materialCount; ordinal += 1) {
       const materialIndex = allocation.materialStart + ordinal;
       const materialOffset = materialIndex * MATERIAL.stride;
       const snapshot = record.snapshot.materials[ordinal] ?? record.snapshot.material;
-      writeVec4(material, materialOffset + offset(MATERIAL, 'params0'), [
-        snapshot.baseColor?.[0] ?? 0,
-        snapshot.baseColor?.[1] ?? 0,
-        snapshot.baseColor?.[2] ?? 0,
-        1,
-      ]);
-      writeVec4(material, materialOffset + offset(MATERIAL, 'params1'), [
-        snapshot.metallic ?? 0,
-        snapshot.roughness ?? 1,
-      ]);
-      writeVec4(material, materialOffset + offset(MATERIAL, 'params2'), [
-        snapshot.emissive?.[0] ?? 0,
-        snapshot.emissive?.[1] ?? 0,
-        snapshot.emissive?.[2] ?? 0,
-        snapshot.emissiveIntensity ?? 0,
-      ]);
-      writeVec4(material, materialOffset + offset(MATERIAL, 'params3'), [
-        snapshot.normalScale ?? 1,
-        snapshot.occlusionStrength ?? 1,
-        0,
-        0,
-      ]);
-      material.setUint32(
-        materialOffset + offset(MATERIAL, 'resource0'),
-        snapshot.baseColorTexture ?? 0,
-        true,
-      );
-      material.setUint32(
-        materialOffset + offset(MATERIAL, 'resource1'),
-        snapshot.metallicRoughnessTexture ?? 0,
-        true,
-      );
-      material.setUint32(
-        materialOffset + offset(MATERIAL, 'resource2'),
-        snapshot.normalTexture ?? 0,
-        true,
-      );
-      material.setUint32(
-        materialOffset + offset(MATERIAL, 'resource3'),
-        snapshot.emissiveTexture ?? 0,
-        true,
-      );
+      const row = packStandardPbrMaterialRow(STANDARD_PBR_RECEIPT, snapshot);
+      new Uint8Array(this.tableBytes.material, materialOffset, MATERIAL.stride).set(row);
       writes.material.push(materialIndex);
     }
   }
 
+  /** Consume changed instance fields independently of root or material changes. */
+  private writeInstanceTransforms(
+    record: RenderSceneSlot,
+    writes: Record<GpuSceneTableName, number[]>,
+  ): void {
+    const allocation = this.allocations.get(record.slot);
+    const instances = record.snapshot.instances;
+    if (allocation === undefined || instances === undefined) {
+      throw new RangeError('GPU Scene instance update has no explicit allocation');
+    }
+    if (allocation.instanceTransformCount !== instances.instanceCount) {
+      throw new RangeError('GPU Scene instance update changed instance count');
+    }
+    for (let ordinal = 0; ordinal < allocation.instanceTransformCount; ordinal += 1) {
+      const transformIndex = allocation.instanceTransformStart + ordinal;
+      const transformOffset = transformIndex * TRANSFORM.stride;
+      if (
+        writeChangedMat4(
+          this.transformView,
+          transformOffset + offset(TRANSFORM, 'currentWorld'),
+          instances.transforms,
+          ordinal * 16,
+        )
+      ) {
+        this.pendingTemporalTransforms.add(transformIndex);
+        writes.transform.push(transformIndex);
+      }
+    }
+  }
+
   private writeRootTransform(
     record: RenderSceneSlot,
     resetPrevious: boolean,
     writes: Record<GpuSceneTableName, number[]>,
   ): void {
-    const allocation = this.allocations[record.slot];
+    const allocation = this.allocations.get(record.slot);
     if (allocation === undefined) throw new RangeError('GPU Scene allocation unavailable');
     const transformOffset = allocation.transformStart * TRANSFORM.stride;
     const previousOffset = transformOffset + offset(TRANSFORM, 'previousWorld');
     if (resetPrevious) {
       writeMat4(this.transformView, previousOffset, record.snapshot.transform.world);
     }
-    writeMat4(
+    const changed = writeChangedMat4(
       this.transformView,
       transformOffset + offset(TRANSFORM, 'currentWorld'),
       record.snapshot.transform.world,
     );
-    if (!resetPrevious) this.pendingTemporalTransforms.add(allocation.transformStart);
-    writes.transform.push(allocation.transformStart);
+    if (changed && !resetPrevious) this.pendingTemporalTransforms.add(allocation.transformStart);
+    if (changed || resetPrevious) writes.transform.push(allocation.transformStart);
   }
 
   private clearSlot(slot: number, writes: Record<GpuSceneTableName, number[]>): void {
@@ -701,10 +782,10 @@ export class GpuScene {
       new Uint8Array(this.tableBytes[name], slot * layout.stride, layout.stride).fill(0);
       writes[name].push(slot);
     }
-    const allocation = this.allocations[slot];
+    const allocation = this.allocations.get(slot);
     if (allocation === undefined) return;
     this.clearAllocation(allocation, writes);
-    this.allocations[slot] = undefined;
+    this.allocations.delete(slot);
   }
 
   private uploadRows(
@@ -749,7 +830,7 @@ export class GpuScene {
     const instanceTransformCount = explicitInstances === undefined ? 0 : instanceCount;
     const drawCount = Math.max(1, record.snapshot.gpuDrivenDraws?.length ?? 0);
     const materialCount = Math.max(1, record.snapshot.materials.length);
-    const existing = this.allocations[record.slot];
+    const existing = this.allocations.get(record.slot);
     if (
       existing?.instanceCount === instanceCount &&
       existing.instanceTransformCount === instanceTransformCount &&
@@ -771,7 +852,7 @@ export class GpuScene {
       materialStart: this.materials.allocate(materialCount),
       materialCount,
     };
-    this.allocations[record.slot] = allocation;
+    this.allocations.set(record.slot, allocation);
   }
 
   private clearAllocation(
@@ -787,17 +868,20 @@ export class GpuScene {
       ).fill(0);
       writes.instance.push(instanceIndex);
     }
-    for (let ordinal = -1; ordinal < allocation.instanceTransformCount; ordinal += 1) {
-      const transformIndex =
-        ordinal < 0 ? allocation.transformStart : allocation.instanceTransformStart + ordinal;
+    new Uint8Array(
+      this.tableBytes.transform,
+      allocation.transformStart * TRANSFORM.stride,
+      TRANSFORM.stride,
+    ).fill(0);
+    writes.transform.push(allocation.transformStart);
+    for (let ordinal = 0; ordinal < allocation.instanceTransformCount; ordinal += 1) {
+      const transformIndex = allocation.instanceTransformStart + ordinal;
       new Uint8Array(
         this.tableBytes.transform,
         transformIndex * TRANSFORM.stride,
         TRANSFORM.stride,
       ).fill(0);
       writes.transform.push(transformIndex);
-      this.pendingTemporalTransforms.delete(transformIndex);
-      this.pendingTemporalUploads.delete(transformIndex);
     }
     for (let ordinal = 0; ordinal < allocation.drawCount; ordinal += 1) {
       const drawIndex = allocation.drawStart + ordinal;
@@ -842,7 +926,10 @@ export class GpuScene {
         return write;
       }
     }
-    for (const buffer of Object.values(this.buffers)) this.device.destroyBuffer(buffer);
+    // A submitted frame may still reference the previous table set. Keep it
+    // owned by this scene until the scene itself is retired after the queue
+    // fence; destroying it here causes validation errors during growth.
+    this.retiredBuffers.push(...Object.values(this.buffers));
     this.buffers = nextBuffers.value;
     this.tableBytes = nextTables;
     this.refreshTransformViews();

package/src/gpu-texture-usage.ts

@@ -7,6 +7,7 @@
 export const GPU_TEXTURE_USAGE_COPY_SRC = 0x01;
 export const GPU_TEXTURE_USAGE_COPY_DST = 0x02;
 export const GPU_TEXTURE_USAGE_TEXTURE_BINDING = 0x04;
+export const GPU_TEXTURE_USAGE_STORAGE_BINDING = 0x08;
 export const GPU_TEXTURE_USAGE_RENDER_ATTACHMENT = 0x10;
 export const GPU_TEXTURE_USAGE_RENDER_ATTACHMENT_AND_TEXTURE_BINDING =
   GPU_TEXTURE_USAGE_RENDER_ATTACHMENT | GPU_TEXTURE_USAGE_TEXTURE_BINDING;

package/src/hdrp-buffers.ts

@@ -414,6 +414,77 @@ export type SsaoBindOptions =
     }
   | { readonly enabled: false };
 
+function standardLightingEntries(
+  hdrpBuffers: HdrpBuffers,
+  ssaoTexView: TextureView,
+  ssaoSampler: Sampler,
+): import('@forgeax/engine-rhi').BindGroupEntry[] {
+  return [
+    {
+      binding: 3,
+      resource: {
+        kind: 'buffer',
+        value: { buffer: hdrpBuffers.lightDataBuffer },
+      },
+    },
+    {
+      binding: 4,
+      resource: {
+        kind: 'buffer',
+        value: { buffer: hdrpBuffers.clusterGridBuffer },
+      },
+    },
+    {
+      binding: 5,
+      resource: {
+        kind: 'buffer',
+        value: { buffer: hdrpBuffers.lightIndexListBuffer },
+      },
+    },
+    {
+      binding: 6,
+      resource: {
+        kind: 'buffer',
+        value: { buffer: hdrpBuffers.clusterUniformBuffer },
+      },
+    },
+    {
+      binding: 7,
+      resource: { kind: 'textureView', value: ssaoTexView },
+    },
+    {
+      binding: 8,
+      resource: { kind: 'sampler', value: ssaoSampler },
+    },
+  ];
+}
+
+/** Standard surface resources without scene geometry tables. */
+export function createStandardSurfaceLightingBindGroup(
+  runtime: RenderSystemRuntime,
+  layout: BindGroupLayout,
+  grid: { readonly x: number; readonly y: number; readonly z: number },
+  ssaoOptions: SsaoBindOptions = { enabled: false },
+): BindGroup | null {
+  const buffers = getOrCreateHdrpBuffers(runtime, grid);
+  const fallback = getOrCreateSsaoFallbackTexture(runtime);
+  if (buffers === null || fallback === null) return null;
+  const result = runtime.device.createBindGroup({
+    label: 'standard-surface-lighting',
+    layout,
+    entries: standardLightingEntries(
+      buffers,
+      ssaoOptions.enabled ? ssaoOptions.ssaoBlurredView : fallback.view,
+      fallback.sampler,
+    ),
+  });
+  if (!result.ok) {
+    runtime.errorRegistry.fire(result.error);
+    return null;
+  }
+  return result.value;
+}
+
 export function createHdrpUnifiedBindGroup(
   runtime: RenderSystemRuntime,
   hdrpBuffers: HdrpBuffers,
@@ -443,42 +514,7 @@ export function createHdrpUnifiedBindGroup(
           },
         },
       },
-      {
-        binding: 3,
-        resource: {
-          kind: 'buffer',
-          value: { buffer: hdrpBuffers.lightDataBuffer },
-        },
-      },
-      {
-        binding: 4,
-        resource: {
-          kind: 'buffer',
-          value: { buffer: hdrpBuffers.clusterGridBuffer },
-        },
-      },
-      {
-        binding: 5,
-        resource: {
-          kind: 'buffer',
-          value: { buffer: hdrpBuffers.lightIndexListBuffer },
-        },
-      },
-      {
-        binding: 6,
-        resource: {
-          kind: 'buffer',
-          value: { buffer: hdrpBuffers.clusterUniformBuffer },
-        },
-      },
-      {
-        binding: 7,
-        resource: { kind: 'textureView', value: ssaoTexView },
-      },
-      {
-        binding: 8,
-        resource: { kind: 'sampler', value: ssaoSampler },
-      },
+      ...standardLightingEntries(hdrpBuffers, ssaoTexView, ssaoSampler),
     ],
   });
   if (!result.ok) {

package/src/ibl/frame-resources.ts

@@ -0,0 +1,38 @@
+import type { RhiError } from '@forgeax/engine-rhi';
+import { ok, type Result } from '@forgeax/engine-types';
+import type { RenderSystemRuntime } from '../record/render-context';
+import type { SkylightSnapshot } from '../render-system-extract';
+import { getOrCreateIblCache } from './IblPipelineCache';
+import type { SkylightBindGroupResources, SkylightFallback } from './skylight-bind-group';
+
+const EMPTY_SKYLIGHT = new Float32Array([0, 0, 0, 0, 0, 0, 0, 1]);
+
+/** Standard and feature materials consume the same generation-owned environment. */
+export function resolveFrameSkylightResources(
+  runtime: Pick<RenderSystemRuntime, 'device' | 'deviceScope'>,
+  fallback: SkylightFallback,
+  skylight: SkylightSnapshot | undefined,
+): Result<SkylightBindGroupResources, RhiError> {
+  const payload =
+    skylight === undefined
+      ? EMPTY_SKYLIGHT
+      : new Float32Array([skylight.intensity, ...skylight.color, ...skylight.rotation]);
+  const uploaded = runtime.device.queue.writeBuffer(fallback.intensityBuffer, 0, payload);
+  if (!uploaded.ok) return uploaded;
+  const cache = skylight === undefined ? undefined : getOrCreateIblCache(runtime.deviceScope);
+  const resident =
+    cache?.irradianceView !== undefined &&
+    cache.prefilterView !== undefined &&
+    cache.brdfLutView !== undefined
+      ? cache
+      : undefined;
+  return ok({
+    irradianceView: resident?.irradianceView ?? fallback.irradianceView,
+    irradianceSampler: fallback.sampler,
+    prefilterView: resident?.prefilterView ?? fallback.prefilterView,
+    prefilterSampler: fallback.sampler,
+    brdfLutView: resident?.brdfLutView ?? fallback.brdfLutView,
+    brdfLutSampler: fallback.sampler,
+    intensityBuffer: fallback.intensityBuffer,
+  });
+}

package/src/ibl/skylight-bind-group.ts

@@ -311,13 +311,14 @@ export function assembleMaterialWithSkylightEntries(
       resource: { kind: 'textureView', value: transmissionView },
     },
   );
-  const clearcoatStart = result.length;
+  // Standard physical maps occupy fixed bindings 26..45.  The `slot` value
+  // is the canonical index from STANDARD_PHYSICAL_TEXTURE_FIELDS; preserve
+  // gaps for omitted authored maps instead of compacting this tail.
+  const physicalStart = 26;
   for (let index = 0; index < textureInjections.length; index += 1) {
     const resource = textureInjections[index];
     if (resource === undefined) continue;
-    // Slots are offsets from one stable injection base. Using the growing
-    // result length here made slot 1/2 drift past their BGL bindings.
-    const binding = clearcoatStart + resource.slot * 2;
+    const binding = physicalStart + resource.slot * 2;
     result.push(
       {
         binding,