@forgeax/engine-render 0.1.27 → 0.1.29

package/src/internal.ts

@@ -49,4 +49,26 @@ export {
   type OcclusionRuntimeTestHooks,
   setOcclusionRuntimeTestHooks,
 } from './scene/visibility/occlusion-runtime';
+export {
+  createSsrHistoryOwner,
+  SSR_HISTORY_FORMAT,
+  type SsrHistoryCandidate,
+  type SsrHistoryError,
+  type SsrHistoryFailureStage,
+  type SsrHistoryInspection,
+  SsrHistoryOwner,
+  type SsrHistoryResetReason,
+  type SsrHistoryResources,
+  type SsrHistorySlot,
+  type SsrHistoryState,
+} from './ssr/history';
+export { estimateSsrSpatialMemory } from './ssr/resources';
+export {
+  createSsrTemporalConsumer,
+  type SsrTemporalCandidate,
+  SsrTemporalConsumer,
+  type SsrTemporalError,
+  type SsrTemporalExecutionError,
+  type SsrTemporalInspection,
+} from './ssr/temporal';
 export { TemporalFrameCoordinator } from './temporal/frame-coordinator';

package/src/lifecycle.ts

@@ -3,6 +3,7 @@ import type { RenderGraphError } from '@forgeax/engine-render-graph';
 import type { RhiError } from '@forgeax/engine-rhi';
 import type { SkinError } from '@forgeax/engine-skinning';
 import type { ImageError } from '@forgeax/engine-types';
+import type { GpuDrivenPreparationError } from './errors/gpu-driven';
 import type { RenderError } from './errors/render';
 import type { PostProcessError } from './post-process-errors';
 
@@ -18,6 +19,7 @@ export type RendererError =
   | RenderGraphError
   | ImageError
   | RenderError
+  | GpuDrivenPreparationError
   | AssetRuntimeError
   | SkinError
   | PostProcessError;

package/src/material-row.ts

@@ -0,0 +1,145 @@
+import {
+  type MaterialShaderArtifactReceipt,
+  STANDARD_PIPELINE_PARAM_SCHEMA,
+} from '@forgeax/engine-shader';
+import { derive, type UboFieldLayout } from '@forgeax/engine-types';
+import { GPU_SCENE_LAYOUTS } from './gpu-scene-schema';
+import type { MaterialSnapshot } from './render-system-extract';
+
+const ROW = GPU_SCENE_LAYOUTS.material;
+const STANDARD_PIPELINE_DERIVED = derive(STANDARD_PIPELINE_PARAM_SCHEMA);
+const STANDARD_PARAM_ENTRIES = new Map(
+  STANDARD_PIPELINE_PARAM_SCHEMA.map((entry) => [entry.name, entry]),
+);
+
+function isNumericValue(value: unknown): value is number | readonly number[] {
+  return typeof value === 'number' || Array.isArray(value);
+}
+
+function numericFallback(
+  name: string,
+  material: MaterialSnapshot,
+): number | readonly number[] | undefined {
+  switch (name) {
+    case 'baseColor':
+      return [
+        material.baseColor[0] ?? 0,
+        material.baseColor[1] ?? 0,
+        material.baseColor[2] ?? 0,
+        1,
+      ];
+    case 'metallic':
+      return material.metallic;
+    case 'roughness':
+      return material.roughness;
+    case 'emissive':
+      return material.emissive ?? [0, 0, 0];
+    case 'emissiveIntensity':
+      return material.emissiveIntensity ?? 0;
+    case 'occlusionStrength':
+      return material.occlusionStrength ?? 1;
+    case 'normalScale':
+      return material.normalScale ?? 1;
+    case 'specularColor':
+      return material.specularColor ?? [1, 1, 1];
+    default: {
+      const defaultValue = STANDARD_PARAM_ENTRIES.get(name)?.default;
+      return isNumericValue(defaultValue) ? defaultValue : undefined;
+    }
+  }
+}
+
+function numericValue(
+  name: string,
+  material: MaterialSnapshot,
+): number | readonly number[] | undefined {
+  const snapshotValue = material.paramSnapshot?.[name];
+  return isNumericValue(snapshotValue) ? snapshotValue : numericFallback(name, material);
+}
+
+function writeScalar(view: DataView, member: UboFieldLayout, value: number): void {
+  switch (member.type) {
+    case 'f32':
+    case 'vec2':
+    case 'vec3':
+    case 'vec4':
+    case 'color':
+      view.setFloat32(member.offset, value, true);
+      return;
+    case 'i32':
+      view.setInt32(member.offset, value, true);
+      return;
+    case 'u32':
+      view.setUint32(member.offset, value, true);
+      return;
+  }
+}
+
+function writeNumeric(
+  view: DataView,
+  member: UboFieldLayout,
+  value: number | readonly number[] | undefined,
+): void {
+  if (member.type === 'f32' || member.type === 'i32' || member.type === 'u32') {
+    writeScalar(view, member, typeof value === 'number' ? value : (value?.[0] ?? 0));
+    return;
+  }
+  const values = Array.isArray(value) ? value : [];
+  const count = member.type === 'vec2' ? 2 : member.type === 'vec3' ? 3 : 4;
+  for (let index = 0; index < count; index += 1) {
+    writeScalar(
+      view,
+      { ...member, offset: member.offset + index * 4, type: 'f32' },
+      values[index] ?? 0,
+    );
+  }
+}
+
+function writeVec4(view: DataView, offset: number, values: readonly number[]): void {
+  for (let index = 0; index < 4; index += 1) {
+    view.setFloat32(offset + index * 4, values[index] ?? 0, true);
+  }
+}
+
+function validateReceipt(receipt: MaterialShaderArtifactReceipt): void {
+  const expectedFields = ROW.fields.map((field) => field.name);
+  if (
+    receipt.materialRow.byteLength !== ROW.stride ||
+    receipt.materialRow.fields.length !== expectedFields.length ||
+    receipt.materialRow.fields.some((field, index) => field !== expectedFields[index])
+  ) {
+    throw new RangeError(
+      `Standard PBR material row receipt must match the ${ROW.stride}-byte canonical ABI`,
+    );
+  }
+}
+
+/** Pack the producer receipt's numeric Standard PBR row into the GPU Scene table. */
+export function packStandardPbrMaterialRow(
+  receipt: MaterialShaderArtifactReceipt,
+  material: MaterialSnapshot,
+): Uint8Array {
+  validateReceipt(receipt);
+  const payload = new Uint8Array(ROW.stride);
+  const view = new DataView(payload.buffer);
+  for (const member of STANDARD_PIPELINE_DERIVED.numericMembers) {
+    writeNumeric(view, member, numericValue(member.name, material));
+  }
+  for (const record of STANDARD_PIPELINE_DERIVED.coordinateRecords) {
+    const coordinates = material.textureCoordinates?.get(record.parameter);
+    const transform = coordinates?.transform;
+    writeVec4(view, record.offset, [
+      transform?.offset?.[0] ?? 0,
+      transform?.offset?.[1] ?? 0,
+      transform?.scale?.[0] ?? 1,
+      transform?.scale?.[1] ?? 1,
+    ]);
+    writeVec4(view, record.offset + 16, [
+      coordinates?.set ?? 0,
+      transform?.rotation ?? 0,
+      coordinates?.physicalUvScale?.[0] ?? 1,
+      coordinates?.physicalUvScale?.[1] ?? 1,
+    ]);
+  }
+  return payload;
+}

package/src/materials.ts

@@ -21,6 +21,36 @@ export type MaterialTransmissionValidationReason =
   | 'blend'
   | 'depth-write';
 
+export type MaterialAuthoringValidationReason = 'non-finite' | 'range';
+
+/** Structured authoring failure for a built-in Standard material parameter. */
+export class MaterialAuthoringContractError extends Error {
+  readonly code = 'material-authoring-contract-invalid' as const;
+  readonly expected =
+    'Standard material authoring values are finite and within their declared ranges';
+  readonly hint =
+    'repair the named Standard material parameter alphaCutoff before publishing the material';
+  readonly detail: {
+    readonly code: 'material-authoring-contract-invalid';
+    readonly material: 'Standard';
+    readonly parameter: 'alphaCutoff';
+    readonly reason: MaterialAuthoringValidationReason;
+    readonly actual?: unknown;
+  };
+
+  constructor(reason: MaterialAuthoringValidationReason, actual?: unknown) {
+    super(`Materials.standard: alphaCutoff violates the authoring contract (${reason})`);
+    this.name = 'MaterialAuthoringContractError';
+    this.detail = {
+      code: 'material-authoring-contract-invalid',
+      material: 'Standard',
+      parameter: 'alphaCutoff',
+      reason,
+      ...(actual === undefined ? {} : { actual }),
+    };
+  }
+}
+
 /** Structured authoring failure for the Standard transmission contract. */
 export class MaterialTransmissionContractError extends Error {
   readonly code = 'material-transmission-contract-invalid' as const;
@@ -195,11 +225,6 @@ function standardParameters(
     'occlusionStrength',
     'alphaCutoff',
     'normalScale',
-    'baseColorTexture',
-    'metallicRoughnessTexture',
-    'normalTexture',
-    'emissiveTexture',
-    'occlusionTexture',
     'specular',
     'specularColor',
     // IOR is part of the always-present dielectric F0 contract. The
@@ -224,12 +249,20 @@ function standardParameters(
       'thickness',
       'attenuationColor',
       'attenuationDistance',
-      'transmissionTexture',
-      'thicknessTexture',
     ]) {
       baseNames.add(name);
     }
   }
+  // A texture declaration selects its compiled sampling path. Loading state
+  // does not: an authored but not-yet-resident slot still needs its fallback.
+  for (const parameter of DEFAULT_STANDARD_PBR_PARAM_SCHEMA) {
+    if (
+      parameter.type === 'texture2d' &&
+      opts[parameter.name as keyof StandardOpts] !== undefined
+    ) {
+      baseNames.add(parameter.name);
+    }
+  }
   // All Standard fields come from one root schema. Physical fields are
   // projected by the authored option membership above; appending a second
   // physical schema would create a parallel ABI authority.
@@ -487,8 +520,11 @@ function standardDefault(opts: DefaultStandardOptions): MaterialAsset {
       `Materials.standard: occlusionStrength must be in [0, 1], got ${occlusionStrength}`,
     );
   }
+  if (opts.alphaCutoff !== undefined && !Number.isFinite(opts.alphaCutoff)) {
+    throw new MaterialAuthoringContractError('non-finite', opts.alphaCutoff);
+  }
   if (opts.alphaCutoff !== undefined && (opts.alphaCutoff < 0 || opts.alphaCutoff > 1)) {
-    throw new Error(`Materials.standard: alphaCutoff must be in [0, 1], got ${opts.alphaCutoff}`);
+    throw new MaterialAuthoringContractError('range', opts.alphaCutoff);
   }
   validateChannel('metallicChannel', opts.metallicChannel);
   validateChannel('roughnessChannel', opts.roughnessChannel);

package/src/pbr-pipeline.ts

@@ -34,6 +34,7 @@ import type {
 } from '@forgeax/engine-rhi';
 import {
   type ShaderCatalog,
+  STANDARD_PHYSICAL_TEXTURE_FIELDS,
   STANDARD_PIPELINE_PARAM_SCHEMA,
   standardPhysicalTextureFields,
 } from '@forgeax/engine-shader';
@@ -154,7 +155,7 @@ export function buildPbrMaterialUserRegionEntries(
   // Project the engine-owned entry shape into the DOM WebGPU descriptor. Omit
   // absent optional members so exactOptionalPropertyTypes remains true at the
   // boundary instead of leaking an `undefined` property into the descriptor.
-  const entries = derived.bglEntries.map(
+  let entries = derived.bglEntries.map(
     (entry): GPUBindGroupLayoutEntry => ({
       binding: entry.binding,
       visibility: entry.visibility,
@@ -164,9 +165,11 @@ export function buildPbrMaterialUserRegionEntries(
       ...(entry.storageTexture === undefined ? {} : { storageTexture: entry.storageTexture }),
     }),
   );
-  // Patch binding 0 (the material UBO) to the dynamic-offset, vertex-visible
-  // material-UBO contract. derive() emits binding 0 as the first numeric run's
-  // merged UBO; an empty schema has no binding-0 UBO and needs no patch.
+  // The record path always owns one dynamic material-UBO slot, even when an
+  // authored shader declares no numeric parameters (an empty paramSchema).
+  // Reserve that slot here so the IBL/transmission injection starts at the
+  // same binding used by `buildPerSubmeshMaterialBg`; otherwise binding 0 in
+  // the layout is a cube texture while the record path submits a UBO.
   const ubo = entries[0];
   if (ubo !== undefined && ubo.binding === 0 && ubo.buffer?.type === 'uniform') {
     entries[0] = {
@@ -174,6 +177,15 @@ export function buildPbrMaterialUserRegionEntries(
       visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT,
       buffer: { type: 'uniform', hasDynamicOffset: true },
     };
+  } else {
+    entries = [
+      {
+        binding: 0,
+        visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT,
+        buffer: { type: 'uniform', hasDynamicOffset: true },
+      },
+      ...entries.map((entry) => ({ ...entry, binding: entry.binding + 1 })),
+    ];
   }
   return entries;
 }
@@ -351,16 +363,22 @@ export function physicalTextureFields(paramSchema: readonly ParamSchemaEntry[]):
 }
 
 export function appendTextureInjection(
-  bgl: readonly GPUBindGroupLayoutEntry[],
+  _bgl: readonly GPUBindGroupLayoutEntry[],
   fields: readonly string[],
 ): GPUBindGroupLayoutEntry[] {
-  const start = bgl.length;
   const fieldSet = new Set(fields);
+  // Physical resources use the Standard root's fixed slots (26 + canonical
+  // index * 2).  Do not compact an authored subset: the shader template and
+  // scene-index receipt share these canonical bindings, while gaps simply
+  // represent physical axes omitted by the selected root contract.
   return standardPhysicalTextureFields(
-    fields.map((name) => ({ name, type: 'texture2d' as const })),
-  ).flatMap((field, index) => {
+    STANDARD_PIPELINE_PARAM_SCHEMA.concat(
+      fields.map((name) => ({ name, type: 'texture2d' as const })),
+    ),
+  ).flatMap((field) => {
     if (!fieldSet.has(field)) return [];
-    const binding = start + index * 2;
+    const canonicalIndex = STANDARD_PHYSICAL_TEXTURE_FIELDS.indexOf(field);
+    const binding = 26 + canonicalIndex * 2;
     return [
       {
         binding,
@@ -441,7 +459,7 @@ export interface PbrCaps {
  *   fragment-only). feat-20260612-point-light-shadows-urp-hdrp Round-2 F-1.
  * binding 6 = point shadow params UBO (`array<vec4<f32>, 4>`, 64 B;
  *   fragment-only). One lane per shadow-casting point light slot
- *   (shadowAtlasLayer in [0, 4)) carrying `(near, far, 1/(far-near), 0)`.
+ *   (shadowAtlasLayer in [0, 4)) carrying `(near, far, depthBias, normalBias)`.
  * binding 7 = shadowCasterCascade UBO (16 B; vertex + fragment). Per-pass
  *   cascade-index uniform consumed exclusively by `shadow_caster.wgsl` to
  *   pick `view.lightViewProj_X` for the cascade currently being rasterized
@@ -506,7 +524,7 @@ export function buildPbrViewBglEntries(caps: PbrCaps): GPUBindGroupLayoutEntry[]
     // feat-20260612-point-light-shadows-urp-hdrp Round-2 F-1: point shadow
     // params UBO. Carries `array<vec4<f32>, 4>` = 64 B with one lane per
     // shadow-casting point light slot (shadowAtlasLayer in [0, 4)). Each
-    // lane stores `(near, far, 1/(far-near), 0)` so the fragment-shader
+    // lane stores `(near, far, depthBias, normalBias)` so the fragment-shader
     // depth-ref reconstruction (lighting-punctual.wgsl evalPointShadowed)
     // can avoid sampling DirectLightSlot for the URP path. The shared
     // DirectLightSlot metadata remains the identity owner, so binding 6 is
@@ -648,7 +666,10 @@ export function buildPbrPipelineLayouts(
   // The transmission start binding is computed from the post-Skylight BGL
   // length (= 22 for the canonical Standard schema) by appendInjection.
   const materialBglRes = device.createBindGroupLayout(
-    buildBindGroupLayoutDescriptor(BGL_ONLY_SPEC_STUB, { kind: 'pbr-material-merged' }),
+    buildBindGroupLayoutDescriptor(BGL_ONLY_SPEC_STUB, {
+      kind: 'pbr-material-merged',
+      caps,
+    }),
   );
   if (!materialBglRes.ok) throw materialBglRes.error;
 
@@ -751,10 +772,24 @@ export function isStandardPbrSkinMaterialShader(shaderId: string | undefined): b
   );
 }
 
-export function shadowCasterVariantSet(storageBuffer: boolean, skinned: boolean): string {
+export function shadowCasterVariantSet(
+  storageBuffer: boolean,
+  skinned: boolean,
+  gpuDrivenSceneIndex = false,
+  alphaMask = false,
+): string {
   const skinningDisabled = !skinned;
-  if (storageBuffer && skinningDisabled) return '';
-  return `SKINNING_DISABLED=${String(skinningDisabled)}+STORAGE_BUFFER_AVAILABLE=${String(storageBuffer)}`;
+  const defines: Record<string, boolean> = {
+    ALPHA_MASK: alphaMask,
+    GPU_DRIVEN_SCENE_INDEX_AVAILABLE: gpuDrivenSceneIndex,
+    GPU_DRIVEN_SCENE_INDEX_EXPLICIT: false,
+    SKINNING_DISABLED: skinningDisabled,
+    STORAGE_BUFFER_AVAILABLE: storageBuffer,
+  };
+  return Object.entries(defines)
+    .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+    .map(([name, value]) => `${name}=${String(value)}`)
+    .join('+');
 }
 
 export function isSkinnedShadowCasterVariant(
@@ -894,6 +929,65 @@ export function buildPbrSkinLayouts(
   };
 }
 
+/**
+ * Build the dedicated slot-3 layout used by scene-index GPU-driven draws.
+ *
+ * Direct material draws deliberately keep `pbr-instances-bgl` at binding(0),
+ * and ProbeBlend deliberately owns binding(1).  The scene-index stream is
+ * therefore a separate BGL at binding(2), rather than an optional entry added
+ * to the direct layout.  This keeps every bind group complete for its shader
+ * and prevents a direct draw from having to bind a dummy visible stream.
+ */
+export function buildGpuDrivenPbrInstancesBindGroupLayout(
+  device: PbrPipelineDevice,
+  caps: PbrCaps,
+): BindGroupLayout {
+  if (!caps.storageBuffer) {
+    throw new Error('GPU-driven PBR instances layout requires storage-buffer capability');
+  }
+  const result = device.createBindGroupLayout(
+    buildBindGroupLayoutDescriptor(BGL_ONLY_SPEC_STUB, {
+      kind: 'pbr-gpu-driven-instances',
+      caps,
+    }),
+  );
+  if (!result.ok) throw result.error;
+  return result.value;
+}
+
+/** Build the four-slot rigid scene-index pipeline layout. */
+export function buildGpuDrivenPbrPipelineLayout(
+  device: PbrPipelineDevice,
+  pbr: PbrPipelineLayoutBundle,
+  gpuDrivenInstancesBgl: BindGroupLayout,
+): PipelineLayout {
+  const result = device.createPipelineLayout({
+    label: 'pbr-gpu-driven-pl',
+    bindGroupLayouts: [pbr.viewBgl, pbr.materialBgl, pbr.meshArrayBgl, gpuDrivenInstancesBgl],
+  });
+  if (!result.ok) throw result.error;
+  return result.value;
+}
+
+/** Build the four-slot skinned scene-index pipeline layout. */
+export function buildGpuDrivenPbrSkinPipelineLayout(
+  device: PbrPipelineDevice,
+  pbrSkin: PbrPipelineLayoutBundle,
+  gpuDrivenInstancesBgl: BindGroupLayout,
+): PipelineLayout {
+  const result = device.createPipelineLayout({
+    label: 'pbr-skin-gpu-driven-pl',
+    bindGroupLayouts: [
+      pbrSkin.viewBgl,
+      pbrSkin.materialBgl,
+      pbrSkin.meshArrayBgl,
+      gpuDrivenInstancesBgl,
+    ],
+  });
+  if (!result.ok) throw result.error;
+  return result.value;
+}
+
 /** Project the canonical group(2) resources for a PBR skin draw. */
 export function createPbrSkinMeshBindGroupEntries(
   meshBuffer: Buffer,
@@ -1064,7 +1158,9 @@ export const SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET = '';
  *      (directional 3/4, point 5/6, cascade 7, spot atlas 8; the former
  *      spot lightViewProj matrices moved into the View UBO)
  *    - `'pbr-mesh-array'` — 1 entry: per-entity mesh SSBO (dynamic-offset)
- *    - `'pbr-instances'` — 1 entry: per-instance SSBO (no dynamic-offset)
+ *    - `'pbr-instances'` — 2 entries: per-instance SSBO plus the compact
+ *      visible-item index stream (the second entry is used only by the
+ *      scene-index vertex entry and shares the frame's instance bind group)
  *    - `'pbr-skin-mesh-array'` — 3 entries: meshes + current/previous palette
  * 3. Attachment-driven (fullscreen post-process):
  *    - `'fullscreen-post'` — 2 entries: input texture + sampler. The texture
@@ -1084,6 +1180,7 @@ export type BglKind =
   | 'pbr-material-merged'
   | 'pbr-mesh-array'
   | 'pbr-instances'
+  | 'pbr-gpu-driven-instances'
   | 'pbr-skin-mesh-array'
   | 'unlit-material'
   | 'hdrp-7-slot'
@@ -1318,6 +1415,41 @@ export function buildBindGroupLayoutDescriptor(
         ),
       };
     }
+    case 'pbr-gpu-driven-instances': {
+      const caps = options.caps ?? { storageBuffer: true };
+      const meshBufType: GPUBufferBindingType = caps.storageBuffer
+        ? 'read-only-storage'
+        : 'uniform';
+      // GPU-driven scene-index draws use a physically distinct slot-3 layout.
+      // The ordinary instances BGL intentionally stays one-entry for direct
+      // draws, while ProbeBlend owns binding(1). Keep the compact visible
+      // `(meshRow, materialRow)` stream at binding(2) so a future probe-enabled
+      // GPU variant can coexist without colliding with the probe record.
+      return {
+        label: 'pbr-gpu-driven-instances-bgl',
+        entries: [
+          {
+            binding: 0,
+            visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT,
+            buffer: { type: meshBufType, hasDynamicOffset: false },
+          },
+          {
+            // ShadowCaster's scene-index entry still reads the visible row
+            // through binding(1). Keep this alias in the dedicated layout so
+            // the shared visible bind group can serve both the Standard PBR
+            // (binding(2)) and depth-only shadow (binding(1)) consumers.
+            binding: 1,
+            visibility: GPU_SHADER_STAGE_VERTEX,
+            buffer: { type: meshBufType, hasDynamicOffset: false },
+          },
+          {
+            binding: 2,
+            visibility: GPU_SHADER_STAGE_VERTEX,
+            buffer: { type: meshBufType, hasDynamicOffset: false },
+          },
+        ],
+      };
+    }
     case 'pbr-skin-mesh-array': {
       const caps = options.caps ?? { storageBuffer: true };
       const meshBufType: GPUBufferBindingType = caps.storageBuffer
@@ -1328,7 +1460,7 @@ export function buildBindGroupLayoutDescriptor(
         entries: [
           {
             binding: 0,
-            visibility: GPU_SHADER_STAGE_VERTEX,
+            visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT,
             buffer: { type: meshBufType, hasDynamicOffset: true },
           },
           {
@@ -1372,6 +1504,16 @@ export function buildBindGroupLayoutDescriptor(
         ...afterTransmission,
         ...appendTextureInjection(afterTransmission, physicalFields),
       ];
+      // Scene-index Standard variants consume one producer-owned material row
+      // after the complete fixed physical range.  Keeping it at binding 46
+      // prevents any authored physical subset from aliasing the row.
+      if (options.caps?.storageBuffer ?? true) {
+        merged.push({
+          binding: 46,
+          visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT,
+          buffer: { type: 'read-only-storage', hasDynamicOffset: false },
+        });
+      }
       return {
         label: 'pbr-material-skylight-bgl',
         entries: merged,

package/src/pipeline/standard-forward-lane.ts

@@ -4,6 +4,7 @@ import type {
   RenderGraphError,
 } from '@forgeax/engine-render-graph';
 import { err, ok, type Result } from '@forgeax/engine-types';
+import { addAtmosphereBackground } from '../environment/background';
 import { SceneDataUnavailableError } from '../errors/render';
 import {
   GPU_TEXTURE_USAGE_COPY_SRC,
@@ -170,7 +171,14 @@ function buildUrp(
     if (!initialized.ok) return initialized;
   }
 
-  const shadows = addTypedShadowPasses(graph, topology);
+  const featureShadows = context.contributeShadowFeatures?.();
+  if (featureShadows !== undefined && !featureShadows.ok) return featureShadows;
+  const shadows = addTypedShadowPasses(
+    graph,
+    topology,
+    context.projectGpuDrivenShadow,
+    featureShadows?.value,
+  );
   if (!shadows.ok) return shadows;
 
   const clusterBuffers = clearOnly ? ok(null) : importStandardClusterBuffers(graph, lighting);
@@ -183,12 +191,22 @@ function buildUrp(
   const clusterReads =
     clusterBuffers.value === null ? [] : standardClusterReadAccesses(clusterBuffers.value);
 
-  const skybox = addTypedSkyboxPass(graph, scene.value);
+  const skybox =
+    topology.atmosphere === true
+      ? addAtmosphereBackground(graph, scene.value)
+      : addTypedSkyboxPass(graph, scene.value);
   if (!skybox.ok) return skybox;
-  const gpuDriven = context.projectGpuDriven({
-    format: scene.value.format,
-    sampleCount: scene.value.sampleCount,
-  });
+  // The GPU-driven Standard PBR raster adapter owns one color target. A
+  // reflection fallback adds a second attachment to this pass, so keep that
+  // topology on the ordinary producer rather than binding a one-target
+  // pipeline into a multi-target render pass.
+  const gpuDriven =
+    reflectionFallback.value === undefined
+      ? context.projectGpuDriven({
+          format: scene.value.format,
+          sampleCount: scene.value.sampleCount,
+        })
+      : ok(undefined);
   if (!gpuDriven.ok) return gpuDriven;
   const transmissionDemand = transmissionDemandForTopology(topology);
   const transmissionActive = resolveTransmissionBackdropTopology({
@@ -330,24 +348,34 @@ function buildUrp(
     if (!volume.ok) return volume;
   }
 
-  const features = context.contributeFeatures([
-    {
-      name: 'linear-hdr',
-      kind: 'scene-color',
-      texture: scene.value.texture,
-      view: scene.value.view,
-      ...(msaa ? { resolveTarget: sceneResolved.value.view } : {}),
-      format: scene.value.format,
-      sampleCount: scene.value.sampleCount,
-    },
-    {
-      kind: 'scene-depth',
-      texture: depth.value.texture,
-      view: depth.value.view,
-      format: depth.value.format,
-      sampleCount: depth.value.sampleCount,
-    },
-  ]);
+  const features = context.contributeFeatures(
+    [
+      {
+        name: 'linear-hdr',
+        kind: 'scene-color',
+        texture: scene.value.texture,
+        view: scene.value.view,
+        ...(msaa ? { resolveTarget: sceneResolved.value.view } : {}),
+        format: scene.value.format,
+        sampleCount: scene.value.sampleCount,
+      },
+      {
+        kind: 'scene-depth',
+        texture: depth.value.texture,
+        view: depth.value.view,
+        format: depth.value.format,
+        sampleCount: depth.value.sampleCount,
+      },
+    ],
+    [],
+    {},
+    [
+      ...clusterReads,
+      ...[shadows.value.directional, shadows.value.spot, shadows.value.point].flatMap((target) =>
+        target === undefined ? [] : [{ resource: target.view, usage: 'sampled-read' as const }],
+      ),
+    ],
+  );
   if (!features.ok) return features;
 
   if (hdr || linearLdr || rawOnly) {