@forgeax/engine-render 0.1.28 → 0.1.30

package/src/device/device-scope.ts

@@ -62,7 +62,7 @@ export class DeviceScope {
   readonly owner: string;
   readonly parent: DeviceScope | undefined;
   private lifecycleState: DeviceScopeState = 'active';
-  private readonly resources: OwnedResource[] = [];
+  private readonly resources = new Map<ResourceRef<unknown>, OwnedResource>();
   private readonly children: DeviceScope[] = [];
 
   private constructor(generation: number, owner: string, parent?: DeviceScope) {
@@ -99,7 +99,7 @@ export class DeviceScope {
 
   ref<T>(kind: DeviceResourceKind, value: T): ResourceRef<T> {
     const ref = new DeviceResourceRef(kind, this.owner, this.generation, value);
-    this.resources.push({ ref: ref as DeviceResourceRef<unknown>, cleanup: () => undefined });
+    this.resources.set(ref, { ref, cleanup: () => undefined });
     return ref;
   }
 
@@ -116,7 +116,7 @@ export class DeviceScope {
   }
 
   resourceDelta(): number {
-    return this.resources.length;
+    return this.resources.size;
   }
 
   /** @internal */
@@ -126,16 +126,22 @@ export class DeviceScope {
     cleanup: (value: T) => void | Promise<void>,
   ): ResourceRef<T> {
     const ref = new DeviceResourceRef(kind, this.owner, this.generation, value);
-    this.resources.push({
-      ref: ref as DeviceResourceRef<unknown>,
+    this.resources.set(ref, {
+      ref,
       cleanup: idempotentCleanup(cleanup) as (resource: unknown) => void | Promise<void>,
     });
     return ref;
   }
 
+  /** @internal Remove ownership only after the resource's cleanup succeeded. */
+  _release(ref: ResourceRef<unknown>): void {
+    this.resources.delete(ref);
+  }
+
   /** @internal */
   _clearResources(): OwnedResource[] {
-    const resources = this.resources.splice(0);
+    const resources = [...this.resources.values()];
+    this.resources.clear();
     for (const resource of resources.reverse()) {
       try {
         const pending = resource.cleanup(resource.ref.value);
@@ -214,7 +220,7 @@ export class DeviceScope {
     return {
       owner: this.owner,
       generation: this.generation,
-      resourceCount: this.resources.length,
+      resourceCount: this.resources.size,
     };
   }
 }

package/src/device/gpu-residency.ts

@@ -38,10 +38,7 @@ import {
   prepareMipmaps,
 } from '@forgeax/engine-assets-runtime';
 import type { World } from '@forgeax/engine-ecs';
-import {
-  PROCEDURAL_FLOATS_PER_VERTEX,
-  type VertexLayoutProjection,
-} from '@forgeax/engine-geometry';
+import { deriveVertexCount, type VertexLayoutProjection } from '@forgeax/engine-geometry';
 import { halfFloat } from '@forgeax/engine-math';
 import {
   type Buffer,
@@ -101,7 +98,6 @@ import {
   runIblPrecompute,
 } from '../ibl/IblPipelineCache';
 import type { RhiErrorListenerRegistry } from '../lifecycle';
-import type { RecoveryColdWorkGuard } from '../record/render-context';
 import {
   type CubeRenderData,
   deriveRenderDataCubemap,
@@ -187,6 +183,7 @@ export function writePrefilterUniforms(
   roughness: number,
   mipFaceSize: number,
   sourceMipLevelCount = 1,
+  sourceSpace: 'image' | 'camera' = 'image',
 ): Result<void, RhiError> {
   if (subPassIdx < 0 || subPassIdx >= PREFILTER_SUBPASS_COUNT) {
     return invalidUniformInput(
@@ -200,7 +197,12 @@ export function writePrefilterUniforms(
       `writePrefilterUniforms received sourceMipLevelCount=${sourceMipLevelCount}`,
     );
   }
-  const payload = new Float32Array([roughness, mipFaceSize, sourceMipLevelCount, 0]);
+  const payload = new Float32Array([
+    roughness,
+    mipFaceSize,
+    sourceMipLevelCount,
+    sourceSpace === 'camera' ? 1 : 0,
+  ]);
   return device.queue.writeBuffer(buffer, subPassIdx * DYNAMIC_OFFSET_STRIDE, payload);
 }
 
@@ -208,6 +210,7 @@ export function writeAllPrefilterUniforms(
   device: FaceUniformsDevice,
   buffer: Buffer,
   sourceMipLevelCount = 1,
+  sourceSpace: 'image' | 'camera' = 'image',
 ): Result<void, RhiError> {
   for (let mip = 0; mip < PREFILTER_MIP_LEVELS; mip++) {
     const roughness = mip / (PREFILTER_MIP_LEVELS - 1);
@@ -220,6 +223,7 @@ export function writeAllPrefilterUniforms(
         roughness,
         mipFaceSize,
         sourceMipLevelCount,
+        sourceSpace,
       );
       if (!result.ok) return result;
     }
@@ -372,6 +376,23 @@ function packMeshLodGeometry(
     }
     lowerData.push(projected.value);
   }
+  if (
+    deriveVertexCount(root.vertices, rootData.layoutProjection) === undefined ||
+    lowerMeshes.some((mesh, index) => {
+      const data = lowerData[index];
+      return (
+        data === undefined || deriveVertexCount(mesh.vertices, data.layoutProjection) === undefined
+      );
+    })
+  ) {
+    return err(
+      new RhiError({
+        code: 'asset-not-registered',
+        expected: 'every MeshAsset LOD vertex byte length to match its layout projection stride',
+        hint: 'reimport the LOD chain so interleaved vertex bytes match attributes',
+      }),
+    );
+  }
   if (
     lowerData.some(
       (data) =>
@@ -479,14 +500,6 @@ export interface MeshGpuHandles {
   readonly iboBytes: number;
   readonly indexCount: number;
   readonly indexFormat: 'uint16' | 'uint32';
-  /**
-   * Vertex stride discriminator (feat-20260611). `'12F'` = 48 B
-   * (position+normal+uv+tangent); `'18F'` = 72 B (12F + skinIndex(uint16x4) +
-   * skinWeight(float32x4)). Mirrors `MeshRenderData.layout` in render-data.ts
-   * and `MeshRenderData.layout` -- the residency and render-data layout
-   * fields are the same union and move together.
-   */
-  readonly layout: '12F' | '18F';
   /** Geometry-owned vertex layout projection used by every GPU consumer. */
   readonly layoutProjection: VertexLayoutProjection;
   /**
@@ -497,7 +510,7 @@ export interface MeshGpuHandles {
    * MeshRenderData.uvSetCount.
    */
   readonly uvSetCount: number;
-  /** Vertex count uses 18F for skin or the geometry-owned canonical base stride. */
+  /** Vertex count derived from the geometry-owned layout projection. */
   readonly vertexCount: number;
   /** True when `MeshAsset.indices` is present (indexed draw path). */
   readonly indexed: boolean;
@@ -547,7 +560,6 @@ export class GpuResidencyCache {
   // Hardware-probe caps injected at `configureGpuDevice`; guards the HDR cubemap
   // path (_uploadCubemapFromEquirect) when `rgba16floatRenderable` is false.
   private caps: RhiCaps | undefined = undefined;
-  private recoveryColdWorkGuard: RecoveryColdWorkGuard | undefined;
   private deviceEpoch = 0;
   private textureGeneration = 0;
 
@@ -657,9 +669,6 @@ export class GpuResidencyCache {
   }
 
   /** Arm the first-published-frame assertion on this generation's store. */
-  setRecoveryColdWorkGuard(guard: RecoveryColdWorkGuard | undefined): void {
-    this.recoveryColdWorkGuard = guard;
-  }
 
   /**
    * Wrap a raw RHI Buffer handle into a GpuBuffer. The wrapper holds a
@@ -676,11 +685,7 @@ export class GpuResidencyCache {
     if (device === undefined) {
       throw new Error('GpuResidencyCache.wrapBuf called before configureGpuDevice');
     }
-    const resource = new GpuBuffer(device, rawHandle);
-    this.deviceScope?._adopt('buffer', resource, (value: GpuBuffer) => {
-      if (!value.isDestroyed) value.destroy();
-    });
-    return resource;
+    return new GpuBuffer(device, rawHandle, this.deviceScope);
   }
 
   /** Wrap a raw RHI Texture handle into a GpuTexture (mirror of wrapBuf). */
@@ -689,11 +694,7 @@ export class GpuResidencyCache {
     if (device === undefined) {
       throw new Error('GpuResidencyCache.wrapTex called before configureGpuDevice');
     }
-    const resource = new GpuTexture(device, rawHandle);
-    this.deviceScope?._adopt('texture', resource, (value: GpuTexture) => {
-      if (!value.isDestroyed) value.destroy();
-    });
-    return resource;
+    return new GpuTexture(device, rawHandle, this.deviceScope);
   }
 
   /**
@@ -1023,7 +1024,6 @@ export class GpuResidencyCache {
     const key = this.worldKey(handleSlot(handle), worldId);
     const existing = this.samplerGpuHandles.get(key);
     if (existing !== undefined) return ok(existing);
-    this.recoveryColdWorkGuard?.noteUploadColdWork();
     const device = this.gpuDevice;
     if (device === undefined) {
       return err(
@@ -1159,7 +1159,6 @@ export class GpuResidencyCache {
         const key = this.worldKey(id, worldId);
         const existing = this.meshGpuHandles.get(key);
         if (existing !== undefined) return ok(existing);
-        this.recoveryColdWorkGuard?.noteUploadColdWork();
         const projected = deriveRenderDataMesh(pod);
         if (!projected.ok) return projected;
         return this.uploadMeshById(key, pod, projected.value, lodMeshes);
@@ -1168,7 +1167,6 @@ export class GpuResidencyCache {
         const texKey = this.worldKey(id, worldId);
         const existing = this.textureGpuHandles.get(texKey);
         if (existing !== undefined) return ok(existing);
-        this.recoveryColdWorkGuard?.noteUploadColdWork();
         const projected = deriveRenderDataTexture(pod);
         if (!projected.ok) return projected;
         const decoded: DecodedImage = decodedFromTexture(pod);
@@ -2010,6 +2008,16 @@ export class GpuResidencyCache {
       );
     }
 
+    const vertexCount = deriveVertexCount(mesh.vertices, renderData.layoutProjection);
+    if (vertexCount === undefined) {
+      return err(
+        new RhiError({
+          code: 'asset-not-registered',
+          expected: 'MeshAsset.vertices byteLength to be divisible by its layout projection stride',
+          hint: 'reimport the mesh so the interleaved vertex bytes match attributes',
+        }),
+      );
+    }
     const packed = packMeshLodGeometry(mesh, renderData, lodMeshes);
     if (!packed.ok) return packed;
     const { vertices, indices, lodRanges } = packed.value;
@@ -2068,14 +2076,9 @@ export class GpuResidencyCache {
       iboBytes: indices === undefined ? 0 : indexBytes,
       indexCount: mesh.indices === undefined ? 0 : mesh.indices.length,
       indexFormat: indices instanceof Uint32Array ? 'uint32' : 'uint16',
-      layout: renderData.layoutProjection.attributes.some(
-        (attribute) => attribute.key === 'skinIndex' || attribute.key === 'skinWeight',
-      )
-        ? '18F'
-        : '12F',
       layoutProjection: renderData.layoutProjection,
       uvSetCount: 1 + extraUvSets,
-      vertexCount: mesh.vertices.byteLength / renderData.layoutProjection.arrayStride,
+      vertexCount,
       indexed: mesh.indices !== undefined,
       topology: renderData.submeshes[0]?.topology ?? 'triangle-list',
       submeshes: renderData.submeshes,
@@ -2102,6 +2105,8 @@ export class GpuResidencyCache {
     if (entry === undefined) return;
 
     const newVertexBytes = newVertices.byteLength;
+    const newVertexCount = deriveVertexCount(newVertices, entry.layoutProjection);
+    if (newVertexCount === undefined) return;
     const indexBytesUnpadded = newIndices.byteLength;
     const newIndexBytes = ((indexBytesUnpadded + 3) >> 2) << 2;
 
@@ -2131,10 +2136,9 @@ export class GpuResidencyCache {
         iboBytes: entry.iboBytes,
         indexCount: newIndices.length,
         indexFormat: 'uint16',
-        layout: '12F',
         layoutProjection: entry.layoutProjection,
         uvSetCount: entry.uvSetCount,
-        vertexCount: newVertices.length / PROCEDURAL_FLOATS_PER_VERTEX,
+        vertexCount: newVertexCount,
         indexed: true,
         topology: entry.topology,
         submeshes: nextSubmeshes,
@@ -2175,10 +2179,9 @@ export class GpuResidencyCache {
       iboBytes: newIndexBytes,
       indexCount: newIndices.length,
       indexFormat: 'uint16',
-      layout: '12F',
       layoutProjection: entry.layoutProjection,
       uvSetCount: entry.uvSetCount,
-      vertexCount: newVertices.length / PROCEDURAL_FLOATS_PER_VERTEX,
+      vertexCount: newVertexCount,
       indexed: true,
       topology: entry.topology,
       submeshes: nextSubmeshes,

package/src/dynamic-geometry.ts

@@ -199,13 +199,11 @@ function cloneCandidate(candidate: DynamicGeometryCandidate): DynamicGeometryCan
 
 function validateMesh(mesh: MeshAsset): string | undefined {
   if (mesh.kind !== 'mesh') return 'MeshAsset.kind must be mesh';
-  if (
-    !(mesh.vertices instanceof Float32Array) ||
-    mesh.vertices.length === 0 ||
-    mesh.vertices.length % 3 !== 0
-  ) {
-    return 'MeshAsset.vertices must be a non-empty Float32Array with xyz triples';
+  if (!(mesh.vertices instanceof Float32Array) || mesh.vertices.length === 0) {
+    return 'MeshAsset.vertices must be a non-empty Float32Array';
   }
+  // vertices may be interleaved. Attribute layout validation belongs to the
+  // mesh producer/residency path; this gate must not assume an xyz-only stride.
   if (
     mesh.indices !== undefined &&
     !(mesh.indices instanceof Uint16Array || mesh.indices instanceof Uint32Array)
@@ -214,8 +212,15 @@ function validateMesh(mesh: MeshAsset): string | undefined {
   }
   if (mesh.submeshes.length === 0)
     return 'MeshAsset.submeshes must contain at least one topology range';
-  if (mesh.materialSlots.length < mesh.submeshes.length) {
-    return 'MeshAsset.materialSlots must cover every submesh';
+  if (
+    mesh.submeshes.some(
+      (submesh) =>
+        !Number.isSafeInteger(submesh.materialSlot) ||
+        submesh.materialSlot < 0 ||
+        submesh.materialSlot >= mesh.materialSlots.length,
+    )
+  ) {
+    return 'MeshAsset.materialSlots must cover every referenced materialSlot';
   }
   if (mesh.vertices.some((value) => !Number.isFinite(value)))
     return 'MeshAsset.vertices must be finite';

package/src/environment/background.ts

@@ -0,0 +1,281 @@
+import type { RenderGraphBuilder, RenderGraphError } from '@forgeax/engine-render-graph';
+import type { BindGroup, BindGroupLayout, RenderPipeline, Sampler } from '@forgeax/engine-rhi';
+import { RhiError } from '@forgeax/engine-rhi';
+import type { Result } from '@forgeax/engine-types';
+import type { _InternalRenderPipelineContext } from '../record/render-context';
+import { VIEW_UNIFORM_BYTES } from '../record/view-ubo';
+import type { RenderPipelineFrame, RenderPipelineTarget } from '../render-pipeline';
+import { addAtmosphereIbl, type GraphEnvironment } from './ibl';
+import { atmosphereStorage } from './storage';
+
+const CUBE_SIZE = 128;
+
+/** One device-owned sky cube feeds the graph background; the sun disc is added only there. */
+export function addAtmosphereBackground(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  color: RenderPipelineTarget,
+): Result<GraphEnvironment, RenderGraphError> {
+  const cube = graph.importTexture(
+    'atmosphere-sky',
+    {
+      format: 'rgba16float',
+      size: { width: CUBE_SIZE, height: CUBE_SIZE, depthOrArrayLayers: 6 },
+      usage: 0x14,
+    },
+    (frame) => atmosphereStorage(frame).sky,
+  );
+  if (!cube.ok) return cube;
+  const cubeView = graph.view(cube.value, { dimension: 'cube', arrayLayerCount: 6 });
+  if (!cubeView.ok) return cubeView;
+  const params = graph.importBuffer(
+    'atmosphere-params',
+    { size: 64, usage: 0x48 },
+    (frame) => atmosphereStorage(frame).params,
+  );
+  if (!params.ok) return params;
+  const vertices = graph.importBuffer(
+    'atmosphere-face-vertices',
+    { size: 6 * 3 * 3 * 4, usage: 0x28 },
+    (frame) => atmosphereStorage(frame).vertices,
+  );
+  if (!vertices.ok) return vertices;
+  const view = graph.importBuffer(
+    'atmosphere-view',
+    { size: VIEW_UNIFORM_BYTES, usage: 0x40 | 0x08 },
+    (frame) => (frame as _InternalRenderPipelineContext).pipelineState.viewUniformBuffer,
+  );
+  if (!view.ok) return view;
+  let state:
+    | {
+        cubePipeline: RenderPipeline;
+        cubeLayout: BindGroupLayout;
+        backgroundPipeline: RenderPipeline;
+        backgroundLayout: BindGroupLayout;
+        sampler: Sampler;
+        cubeGroup?: BindGroup;
+        backgroundGroup?: BindGroup;
+      }
+    | undefined;
+  const frameOf = (frame: RenderPipelineFrame) => frame as _InternalRenderPipelineContext;
+  const dirty = (frame: RenderPipelineFrame) =>
+    frameOf(frame).frameState.environmentFrame?.environmentSignature !==
+    atmosphereStorage(frame).submittedSignature;
+  const upload = graph.addCopyPass('atmosphere-prepare', {
+    accesses: [
+      { resource: params.value, usage: 'copy-dst' },
+      { resource: vertices.value, usage: 'copy-dst' },
+    ],
+    executeIf: dirty,
+    encode: ({ frame, resources }) => {
+      const environment = frameOf(frame).frameState.environmentFrame;
+      const sun = environment?.sun;
+      if (environment?.source.kind !== 'atmosphere' || sun === undefined) {
+        throw new RhiError({
+          code: 'webgpu-runtime-error',
+          expected: 'selected Atmosphere frame carries its directional sun',
+          hint: 'publish the validated resource-owner environment frame before graph recording',
+        });
+      }
+      const settings = environment.source.atmosphere;
+      const values = new Float32Array([
+        ...sun.direction,
+        sun.intensity,
+        ...sun.color,
+        0,
+        settings.turbidity,
+        settings.rayleigh,
+        settings.mieCoefficient,
+        settings.mieDirectionalG,
+        settings.sunAngularRadius,
+        settings.sunAngularRadius > 0 ? 1 : 0,
+        0,
+        0,
+      ]);
+      frame.runtime.device.queue
+        .writeBuffer(resources.buffer(params.value).unwrap(), 0, values)
+        .unwrap();
+      const triangles = new Float32Array(6 * 9);
+      for (let face = 0; face < 6; face += 1) {
+        triangles.set([-1, -1, face + 1, 3, -1, face + 1, -1, 3, face + 1], face * 9);
+      }
+      frame.runtime.device.queue
+        .writeBuffer(resources.buffer(vertices.value).unwrap(), 0, triangles)
+        .unwrap();
+    },
+  });
+  if (!upload.ok) return upload;
+  const ensureState = (frame: RenderPipelineFrame) => {
+    if (state !== undefined) return state;
+    const sources = frame.atmosphereShaders;
+    const factory = frame.runtime.shaderModuleFactory;
+    if (sources === undefined || factory === undefined) {
+      throw new RhiError({
+        code: 'shader-compile-failed',
+        expected: 'shader manifest includes the Atmosphere cube and background programs',
+        hint: 'rebuild the Engine shader manifest with the package-owned Atmosphere entries',
+      });
+    }
+    const device = frame.runtime.device;
+    const cubeModule = factory
+      .createShaderModule({ code: sources.cube, label: 'atmosphere_cube' })
+      .unwrap();
+    const backgroundModule = factory
+      .createShaderModule({ code: sources.background, label: 'atmosphere_background' })
+      .unwrap();
+    const cubeLayout = device
+      .createBindGroupLayout({
+        entries: [{ binding: 0, visibility: 2, buffer: { type: 'uniform', minBindingSize: 64 } }],
+      })
+      .unwrap();
+    const backgroundLayout = device
+      .createBindGroupLayout({
+        entries: [
+          { binding: 0, visibility: 2, texture: { sampleType: 'float', viewDimension: 'cube' } },
+          { binding: 1, visibility: 2, sampler: { type: 'filtering' } },
+          {
+            binding: 2,
+            visibility: 2,
+            buffer: { type: 'uniform', minBindingSize: VIEW_UNIFORM_BYTES },
+          },
+          { binding: 3, visibility: 2, buffer: { type: 'uniform', minBindingSize: 64 } },
+        ],
+      })
+      .unwrap();
+    const cubePipeline = device
+      .createRenderPipeline({
+        label: 'atmosphere_cube',
+        layout: device.createPipelineLayout({ bindGroupLayouts: [cubeLayout] }).unwrap(),
+        vertex: {
+          module: cubeModule,
+          entryPoint: 'atmosphere_cubemap_vs',
+          buffers: [
+            {
+              arrayStride: 12,
+              attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' }],
+            },
+          ],
+        },
+        fragment: {
+          module: cubeModule,
+          entryPoint: 'atmosphere_cubemap_fs',
+          targets: [{ format: 'rgba16float' }],
+        },
+        primitive: { topology: 'triangle-list', cullMode: 'none' },
+      })
+      .unwrap();
+    const backgroundPipeline = device
+      .createRenderPipeline({
+        label: 'atmosphere_background',
+        layout: device.createPipelineLayout({ bindGroupLayouts: [backgroundLayout] }).unwrap(),
+        vertex: { module: backgroundModule, entryPoint: 'atmosphere_background_vs', buffers: [] },
+        fragment: {
+          module: backgroundModule,
+          entryPoint: 'atmosphere_background_fs',
+          targets: [{ format: color.format }],
+        },
+        primitive: { topology: 'triangle-list', cullMode: 'none' },
+        multisample: { count: color.sampleCount },
+      })
+      .unwrap();
+    const sampler = device
+      .createSampler({ minFilter: 'linear', magFilter: 'linear', mipmapFilter: 'linear' })
+      .unwrap();
+    state = { cubePipeline, cubeLayout, backgroundPipeline, backgroundLayout, sampler };
+    return state;
+  };
+  for (let face = 0; face < 6; face += 1) {
+    const faceView = graph.view(cube.value, {
+      dimension: '2d',
+      baseArrayLayer: face,
+      arrayLayerCount: 1,
+    });
+    if (!faceView.ok) return faceView;
+    const pass = graph.addRasterPass(`atmosphere-cube-${face}`, {
+      accesses: [
+        { resource: faceView.value, usage: 'color-attachment' },
+        { resource: params.value, usage: 'uniform-read' },
+        { resource: vertices.value, usage: 'vertex-read' },
+      ],
+      colorAttachments: [{ view: faceView.value, loadOp: 'clear', storeOp: 'store' }],
+      executeIf: dirty,
+      encode: ({ pass, frame, resources }) => {
+        const current = ensureState(frame);
+        current.cubeGroup ??= frame.runtime.device
+          .createBindGroup({
+            layout: current.cubeLayout,
+            entries: [
+              {
+                binding: 0,
+                resource: {
+                  kind: 'buffer',
+                  value: { buffer: resources.buffer(params.value).unwrap(), size: 64 },
+                },
+              },
+            ],
+          })
+          .unwrap();
+        pass.setPipeline(current.cubePipeline);
+        pass.setBindGroup(0, current.cubeGroup);
+        pass.setVertexBuffer(0, resources.buffer(vertices.value).unwrap());
+        pass.draw(3, 1, face * 3, 0);
+        if (face === 5) {
+          const signature = frameOf(frame).frameState.environmentFrame?.environmentSignature;
+          frameOf(frame).frameState.pendingAtmospherePublish = () => {
+            atmosphereStorage(frame).submittedSignature = signature;
+          };
+        }
+      },
+    });
+    if (!pass.ok) return pass;
+  }
+  const ibl = addAtmosphereIbl(graph, cubeView.value, vertices.value, dirty);
+  if (!ibl.ok) return ibl;
+  const background = graph.addRasterPass('atmosphere-background', {
+    accesses: [
+      { resource: cubeView.value, usage: 'sampled-read' },
+      { resource: params.value, usage: 'uniform-read' },
+      { resource: view.value, usage: 'uniform-read' },
+      { resource: color.view, usage: 'color-attachment' },
+    ],
+    // Initialize scene radiance before opaque and transparent draws. Geometry
+    // uses the normal scene depth authority, so alpha blending sees the sky
+    // and no later background pass can overwrite a transparent foreground.
+    colorAttachments: [{ view: color.view, loadOp: 'clear', storeOp: 'store' }],
+    encode: ({ pass, frame, resources }) => {
+      const current = ensureState(frame);
+      current.backgroundGroup ??= frame.runtime.device
+        .createBindGroup({
+          layout: current.backgroundLayout,
+          entries: [
+            {
+              binding: 0,
+              resource: {
+                kind: 'textureView',
+                value: resources.textureView(cubeView.value).unwrap(),
+              },
+            },
+            { binding: 1, resource: { kind: 'sampler', value: current.sampler } },
+            {
+              binding: 2,
+              resource: {
+                kind: 'buffer',
+                value: { buffer: resources.buffer(view.value).unwrap(), size: VIEW_UNIFORM_BYTES },
+              },
+            },
+            {
+              binding: 3,
+              resource: {
+                kind: 'buffer',
+                value: { buffer: resources.buffer(params.value).unwrap(), size: 64 },
+              },
+            },
+          ],
+        })
+        .unwrap();
+      pass.setPipeline(current.backgroundPipeline);
+      pass.setBindGroup(0, current.backgroundGroup);
+      pass.draw(3);
+    },
+  });
+  return background.ok ? ibl : background;
+}