@forgeax/engine-render 0.1.29 → 0.1.31

package/src/components/dynamic-resolution.ts

@@ -0,0 +1,67 @@
+import { defineComponent, type SchemaOf, type ShapeOf } from '@forgeax/engine-ecs';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import {
+  type DynamicResolutionError,
+  DynamicResolutionInvalidParameterError,
+  DynamicResolutionRequiresTaaError,
+} from '../errors/render';
+
+/** Optional Camera companion that enables fixed or adaptive internal scaling. */
+export const DynamicResolution = defineComponent('DynamicResolution', {
+  targetGpuMs: { type: 'f32', default: 16.67 },
+  minScale: { type: 'f32', default: 0.67 },
+  maxScale: { type: 'f32', default: 1.0 },
+});
+
+export type DynamicResolutionData = ShapeOf<SchemaOf<typeof DynamicResolution>>;
+
+const DEFAULT_DYNAMIC_RESOLUTION: DynamicResolutionData = Object.freeze({
+  targetGpuMs: 16.67,
+  minScale: 0.67,
+  maxScale: 1,
+});
+
+function invalid(
+  field: 'targetGpuMs' | 'minScale' | 'maxScale',
+  value: number,
+  expected: string,
+): DynamicResolutionInvalidParameterError {
+  return new DynamicResolutionInvalidParameterError({ field, value, expected });
+}
+
+/** Validate one detached DynamicResolution authoring POD before graph work. */
+export function validateDynamicResolutionParameters(
+  input: Partial<DynamicResolutionData> | undefined,
+): Result<DynamicResolutionData, DynamicResolutionInvalidParameterError> {
+  const value = input ?? {};
+  const targetGpuMs = value.targetGpuMs ?? DEFAULT_DYNAMIC_RESOLUTION.targetGpuMs;
+  const minScale = value.minScale ?? DEFAULT_DYNAMIC_RESOLUTION.minScale;
+  const maxScale = value.maxScale ?? DEFAULT_DYNAMIC_RESOLUTION.maxScale;
+  if (!Number.isFinite(targetGpuMs) || targetGpuMs <= 0) {
+    return err(invalid('targetGpuMs', targetGpuMs, 'finite and greater than 0'));
+  }
+  if (!Number.isFinite(minScale) || minScale < 0.5 || minScale > 1) {
+    return err(invalid('minScale', minScale, 'finite and in [0.5, 1.0]'));
+  }
+  if (!Number.isFinite(maxScale) || maxScale < 0.5 || maxScale > 1) {
+    return err(invalid('maxScale', maxScale, 'finite and in [0.5, 1.0]'));
+  }
+  if (minScale > maxScale) {
+    return err(invalid('minScale', minScale, 'less than or equal to maxScale'));
+  }
+  return ok(Object.freeze({ targetGpuMs, minScale, maxScale }));
+}
+
+/** Validate the Camera companion relationship at the extraction boundary. */
+export function validateDynamicResolutionCamera(
+  input: Partial<DynamicResolutionData> | undefined,
+  antialias: 'none' | 'fxaa' | 'msaa' | 'taa',
+): Result<DynamicResolutionData | undefined, DynamicResolutionError> {
+  if (input === undefined) return ok(undefined);
+  const parameters = validateDynamicResolutionParameters(input);
+  if (!parameters.ok) return parameters;
+  if (antialias !== 'taa') {
+    return err(new DynamicResolutionRequiresTaaError({ antialias }));
+  }
+  return parameters;
+}

package/src/components/index.ts

@@ -2,6 +2,7 @@ export * from './atmosphere';
 export * from './camera';
 export * from './cube-camera';
 export * from './directional-light';
+export * from './dynamic-resolution';
 export * from './fog';
 export { Instances, type InstancesData } from './instances';
 export { Layer } from './layer';

package/src/components/light-helpers.ts

@@ -149,7 +149,12 @@ export function validateDirectionalLightData(
         }),
       );
     }
-    if (shadowAngularRadius < PCSS_RADIUS_MIN || shadowAngularRadius > PCSS_RADIUS_MAX) {
+    // ECS stores this field as f32; both authored endpoints round outward.
+    // Accept their stored representations, but not the adjacent out-of-range f32.
+    if (
+      shadowAngularRadius < Math.fround(PCSS_RADIUS_MIN) ||
+      shadowAngularRadius > Math.fround(PCSS_RADIUS_MAX)
+    ) {
       return err(
         new ShadowInvalidConfigError('shadowAngularRadius', shadowAngularRadius, {
           kind: 'range',

package/src/components/reflection-probe.ts

@@ -40,6 +40,7 @@ export function reflectionProbeUpdateIntentToF32(intent: ReflectionProbeUpdateIn
 export const ReflectionProbe = defineComponent('ReflectionProbe', {
   halfExtents: { type: 'array<f32, 3>', default: new Float32Array([1, 1, 1]) },
   priority: { type: 'f32', default: 0 },
+  boxProjection: { type: 'bool', default: false },
   intensity: { type: 'f32', default: 1 },
   resolution: { type: 'u32', default: 256 },
   updateIntent: { type: 'f32', default: REFLECTION_PROBE_UPDATE_ONCE },

package/src/components/skylight.ts

@@ -40,7 +40,10 @@ import { defineComponent } from '@forgeax/engine-ecs';
  * Skylight ambient environment light.
  *
  * A single Skylight entity provides ambient lighting for all StandardMaterial
- * surfaces. Two modes share one component:
+ * surfaces. When Atmosphere is selected and equirect is omitted, the same sky
+ * cube supplies diffuse and roughness-filtered specular IBL. Color/intensity
+ * still scale the result; without Atmosphere the solid-color behavior applies.
+ * Two authored inputs share one component:
  *
  * - **Solid-color ambient (no equirect).** Omit `equirect` for a constant
  *   ambient = `color` * `intensity` applied immediately, with no async GPU

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

@@ -183,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(
@@ -196,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);
 }
 
@@ -204,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);
@@ -216,6 +223,7 @@ export function writeAllPrefilterUniforms(
         roughness,
         mipFaceSize,
         sourceMipLevelCount,
+        sourceSpace,
       );
       if (!result.ok) return result;
     }
@@ -677,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). */
@@ -690,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);
   }
 
   /**

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

@@ -5,24 +5,39 @@ 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 graph-owned sky cube feeds the background; the sun disc is added only there. */
+/** 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<void, RenderGraphError> {
-  const cube = graph.createTexture('atmosphere-sky', {
-    format: 'rgba16float',
-    size: { width: CUBE_SIZE, height: CUBE_SIZE, depthOrArrayLayers: 6 },
-  });
+): 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.createBuffer('atmosphere-params', { size: 64 });
+  const params = graph.importBuffer(
+    'atmosphere-params',
+    { size: 64, usage: 0x48 },
+    (frame) => atmosphereStorage(frame).params,
+  );
   if (!params.ok) return params;
-  const vertices = graph.createBuffer('atmosphere-face-vertices', { size: 6 * 3 * 3 * 4 });
+  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',
@@ -30,7 +45,6 @@ export function addAtmosphereBackground(
     (frame) => (frame as _InternalRenderPipelineContext).pipelineState.viewUniformBuffer,
   );
   if (!view.ok) return view;
-  let submittedSignature: string | undefined;
   let state:
     | {
         cubePipeline: RenderPipeline;
@@ -44,7 +58,8 @@ export function addAtmosphereBackground(
     | undefined;
   const frameOf = (frame: RenderPipelineFrame) => frame as _InternalRenderPipelineContext;
   const dirty = (frame: RenderPipelineFrame) =>
-    frameOf(frame).frameState.environmentFrame?.environmentSignature !== submittedSignature;
+    frameOf(frame).frameState.environmentFrame?.environmentSignature !==
+    atmosphereStorage(frame).submittedSignature;
   const upload = graph.addCopyPass('atmosphere-prepare', {
     accesses: [
       { resource: params.value, usage: 'copy-dst' },
@@ -206,14 +221,16 @@ export function addAtmosphereBackground(
         if (face === 5) {
           const signature = frameOf(frame).frameState.environmentFrame?.environmentSignature;
           frameOf(frame).frameState.pendingAtmospherePublish = () => {
-            submittedSignature = signature;
+            atmosphereStorage(frame).submittedSignature = signature;
           };
         }
       },
     });
     if (!pass.ok) return pass;
   }
-  return graph.addRasterPass('atmosphere-background', {
+  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' },
@@ -260,4 +277,5 @@ export function addAtmosphereBackground(
       pass.draw(3);
     },
   });
+  return background.ok ? ibl : background;
 }

package/src/environment/ibl.ts

@@ -0,0 +1,211 @@
+import type {
+  GraphBuffer,
+  GraphTextureView,
+  RenderGraphBuilder,
+  RenderGraphError,
+} from '@forgeax/engine-render-graph';
+import {
+  type BindGroup,
+  type BindGroupLayout,
+  type RenderPipeline,
+  RhiError,
+  type Sampler,
+} from '@forgeax/engine-rhi';
+import { ok, type Result } from '@forgeax/engine-types';
+import type { RenderPipelineFrame } from '../render-pipeline';
+import { atmosphereStorage } from './storage';
+
+/** Graph views of the shared device-owned sky and its lighting products. */
+export interface GraphEnvironment {
+  readonly sky: GraphTextureView;
+  readonly irradiance: GraphTextureView;
+  readonly prefilter: GraphTextureView;
+}
+
+export function addAtmosphereIbl(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  sky: GraphTextureView,
+  vertices: GraphBuffer,
+  dirty: (frame: RenderPipelineFrame) => boolean,
+): Result<GraphEnvironment, RenderGraphError> {
+  const irradiance = graph.importTexture(
+    'atmosphere-irradiance',
+    {
+      format: 'rgba16float',
+      size: { width: 16, height: 16, depthOrArrayLayers: 6 },
+      usage: 0x14,
+    },
+    (frame) => atmosphereStorage(frame).irradiance,
+  );
+  if (!irradiance.ok) return irradiance;
+  const prefilter = graph.importTexture(
+    'atmosphere-prefilter',
+    {
+      format: 'rgba16float',
+      size: { width: 64, height: 64, depthOrArrayLayers: 6 },
+      mipLevelCount: 5,
+      usage: 0x14,
+    },
+    (frame) => atmosphereStorage(frame).prefilter,
+  );
+  if (!prefilter.ok) return prefilter;
+  const irradianceView = graph.view(irradiance.value, { dimension: 'cube', arrayLayerCount: 6 });
+  if (!irradianceView.ok) return irradianceView;
+  const prefilterView = graph.view(prefilter.value, { dimension: 'cube', arrayLayerCount: 6 });
+  if (!prefilterView.ok) return prefilterView;
+  const parameters = graph.importBuffer(
+    'atmosphere-ibl-params',
+    { size: 5 * 256, usage: 0x48 },
+    (frame) => atmosphereStorage(frame).iblParams,
+  );
+  if (!parameters.ok) return parameters;
+  const upload = graph.addCopyPass('atmosphere-ibl-prepare', {
+    accesses: [{ resource: parameters.value, usage: 'copy-dst' }],
+    executeIf: dirty,
+    encode: ({ frame, resources }) => {
+      const values = new Float32Array(5 * 64);
+      for (let mip = 0; mip < 5; mip++) values[mip * 64 + 14] = mip / 4;
+      frame.runtime.device.queue
+        .writeBuffer(resources.buffer(parameters.value).unwrap(), 0, values)
+        .unwrap();
+    },
+  });
+  if (!upload.ok) return upload;
+  let state:
+    | {
+        layout: BindGroupLayout;
+        inputLayout: BindGroupLayout;
+        sampler: Sampler;
+        irradiance: RenderPipeline;
+        prefilter: RenderPipeline;
+        inputs?: BindGroup;
+        parameters: BindGroup[];
+      }
+    | undefined;
+  const ensureState = (frame: RenderPipelineFrame) => {
+    if (state !== undefined) return state;
+    const device = frame.runtime.device;
+    const source = frame.atmosphereShaders?.ibl;
+    const factory = frame.runtime.shaderModuleFactory;
+    if (source === undefined || factory === undefined)
+      throw new RhiError({
+        code: 'shader-compile-failed',
+        expected: 'the compiled Atmosphere IBL program is available',
+        hint: 'rebuild the Engine shader manifest before selecting Atmosphere lighting',
+      });
+    const module = factory.createShaderModule({ code: source, label: 'atmosphere_ibl' }).unwrap();
+    const layout = device
+      .createBindGroupLayout({
+        entries: [{ binding: 0, visibility: 2, buffer: { type: 'uniform', minBindingSize: 64 } }],
+      })
+      .unwrap();
+    const inputLayout = device
+      .createBindGroupLayout({
+        entries: [
+          { binding: 0, visibility: 2, texture: { sampleType: 'float', viewDimension: 'cube' } },
+          { binding: 1, visibility: 2, sampler: { type: 'filtering' } },
+        ],
+      })
+      .unwrap();
+    const pipelineLayout = device
+      .createPipelineLayout({ bindGroupLayouts: [layout, inputLayout] })
+      .unwrap();
+    const pipeline = (entryPoint: string) =>
+      device
+        .createRenderPipeline({
+          label: entryPoint,
+          layout: pipelineLayout,
+          vertex: {
+            module,
+            entryPoint: 'atmosphere_ibl_vs',
+            buffers: [
+              {
+                arrayStride: 12,
+                attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' }],
+              },
+            ],
+          },
+          fragment: { module, entryPoint, targets: [{ format: 'rgba16float' }] },
+          primitive: { topology: 'triangle-list' },
+        })
+        .unwrap();
+    state = {
+      layout,
+      inputLayout,
+      sampler: device
+        .createSampler({ magFilter: 'linear', minFilter: 'linear', mipmapFilter: 'linear' })
+        .unwrap(),
+      irradiance: pipeline('atmosphere_irradiance_fs'),
+      prefilter: pipeline('atmosphere_prefilter_fs'),
+      parameters: [],
+    };
+    return state;
+  };
+  for (const product of ['irradiance', 'prefilter'] as const) {
+    for (let mip = 0; mip < (product === 'irradiance' ? 1 : 5); mip++)
+      for (let face = 0; face < 6; face++) {
+        const target = graph.view(product === 'irradiance' ? irradiance.value : prefilter.value, {
+          dimension: '2d',
+          baseArrayLayer: face,
+          arrayLayerCount: 1,
+          baseMipLevel: mip,
+          mipLevelCount: 1,
+        });
+        if (!target.ok) return target;
+        const pass = graph.addRasterPass(`atmosphere-${product}-${mip}-${face}`, {
+          accesses: [
+            { resource: sky, usage: 'sampled-read' },
+            { resource: parameters.value, usage: 'uniform-read' },
+            { resource: vertices, usage: 'vertex-read' },
+            { resource: target.value, usage: 'color-attachment' },
+          ],
+          colorAttachments: [{ view: target.value, loadOp: 'clear', storeOp: 'store' }],
+          executeIf: dirty,
+          encode: ({ frame, resources, pass }) => {
+            const current = ensureState(frame);
+            current.inputs ??= frame.runtime.device
+              .createBindGroup({
+                layout: current.inputLayout,
+                entries: [
+                  {
+                    binding: 0,
+                    resource: { kind: 'textureView', value: resources.textureView(sky).unwrap() },
+                  },
+                  { binding: 1, resource: { kind: 'sampler', value: current.sampler } },
+                ],
+              })
+              .unwrap();
+            let parameterGroup = current.parameters[mip];
+            if (parameterGroup === undefined) {
+              parameterGroup = frame.runtime.device
+                .createBindGroup({
+                  layout: current.layout,
+                  entries: [
+                    {
+                      binding: 0,
+                      resource: {
+                        kind: 'buffer',
+                        value: {
+                          buffer: resources.buffer(parameters.value).unwrap(),
+                          offset: mip * 256,
+                          size: 64,
+                        },
+                      },
+                    },
+                  ],
+                })
+                .unwrap();
+              current.parameters[mip] = parameterGroup;
+            }
+            pass.setPipeline(current[product]);
+            pass.setBindGroup(0, parameterGroup);
+            pass.setBindGroup(1, current.inputs);
+            pass.setVertexBuffer(0, resources.buffer(vertices).unwrap());
+            pass.draw(3, 1, face * 3);
+          },
+        });
+        if (!pass.ok) return pass;
+      }
+  }
+  return ok({ sky, irradiance: irradianceView.value, prefilter: prefilterView.value });
+}

package/src/environment/storage.ts

@@ -0,0 +1,63 @@
+import type { Buffer, Texture } from '@forgeax/engine-rhi';
+import type { DeviceScope } from '../device/device-scope';
+import type { _InternalRenderPipelineContext } from '../record/render-context';
+import type { RenderPipelineFrame } from '../render-pipeline';
+
+/** Device-generation resources survive unrelated probe/scene graph topology changes. */
+export interface AtmosphereStorage {
+  readonly sky: Texture;
+  readonly irradiance: Texture;
+  readonly prefilter: Texture;
+  readonly params: Buffer;
+  readonly vertices: Buffer;
+  readonly iblParams: Buffer;
+  submittedSignature?: string | undefined;
+}
+const generations = new WeakMap<DeviceScope, AtmosphereStorage>();
+
+export function atmosphereStorage(frame: RenderPipelineFrame): AtmosphereStorage {
+  const runtime = (frame as _InternalRenderPipelineContext).runtime;
+  const owner = runtime.deviceScope;
+  const existing = generations.get(owner);
+  if (existing !== undefined) return existing;
+  const scope = owner.createChild('atmosphere');
+  const device = runtime.device;
+  try {
+    const texture = (name: string, size: number, mipLevelCount = 1) => {
+      const value = device
+        .createTexture({
+          label: name,
+          format: 'rgba16float',
+          size: { width: size, height: size, depthOrArrayLayers: 6 },
+          mipLevelCount,
+          usage: 0x14,
+          textureBindingViewDimension: undefined,
+        })
+        .unwrap();
+      scope._adopt('texture', value, (value) => {
+        device.destroyTexture(value).unwrap();
+      });
+      return value;
+    };
+    const buffer = (name: string, size: number, usage: number) => {
+      const value = device.createBuffer({ label: name, size, usage }).unwrap();
+      scope._adopt('buffer', value, (value) => {
+        device.destroyBuffer(value).unwrap();
+      });
+      return value;
+    };
+    const created: AtmosphereStorage = {
+      sky: texture('atmosphere-sky', 128),
+      irradiance: texture('atmosphere-irradiance', 16),
+      prefilter: texture('atmosphere-prefilter', 64, 5),
+      params: buffer('atmosphere-params', 64, 0x48),
+      vertices: buffer('atmosphere-face-vertices', 216, 0x28),
+      iblParams: buffer('atmosphere-ibl-params', 1280, 0x48),
+    };
+    generations.set(owner, created);
+    return created;
+  } catch (cause) {
+    scope.retire();
+    throw cause;
+  }
+}