@forgeax/engine-render 0.1.33 → 0.1.35

package/src/record/main-pass.ts

@@ -1,8 +1,8 @@
-import type { World } from '@forgeax/engine-ecs';
 import { probeVideoHighPerfUpload } from '@forgeax/engine-graphics-extras';
 import type { GraphResourceResolver } from '@forgeax/engine-render-graph';
 import {
   type BindGroup,
+  type Buffer,
   RhiError,
   type RhiRenderPassEncoder,
   type TextureView,
@@ -10,6 +10,7 @@ import {
 import type { PassKind, PassSelector } from '@forgeax/engine-types';
 import {
   createGpuDrivenLightingBindGroup,
+  createHdrpSkinUnifiedBindGroup,
   createHdrpUnifiedBindGroup,
   getOrCreateHdrpBuffers,
 } from '../hdrp-buffers';
@@ -17,10 +18,12 @@ import { getOrCreateIblCache } from '../ibl/IblPipelineCache';
 import type { SkylightBindGroupResources } from '../ibl/skylight-bind-group';
 import { buildBeginRenderPassDescriptor, standardTopologyBindGroupReady } from '../pipeline-spec';
 import { POINTS_LINES_MATERIAL_SHADER_ID } from '../points-lines/record';
+import type { RenderResourceScope } from '../publication/resource-scope';
 import type { ReflectionProbeSelectionResult } from '../reflection/projection';
 import type { RenderRecordPhase } from '../render-contract';
 import type {
   GpuDrivenStandardPbrFrameResources,
+  RenderPipelineGpuDrivenFilter,
   RenderPipelineGpuDrivenProjection,
 } from '../render-pipeline';
 import type { MaterialSnapshot } from '../render-system-extract';
@@ -65,12 +68,28 @@ export type MainPassOptions = {
   readonly depthView?: TextureView | null;
   readonly passKind?: PassKind;
   readonly clearColor?: readonly [number, number, number, number];
-  readonly recordMode?: 'opaque' | 'transmission' | 'transparent';
+  readonly recordMode?:
+    | 'opaque'
+    | 'transmission'
+    | 'transparent'
+    | 'single-layer-medium-nearest-layer'
+    | 'single-layer-medium-color';
+  readonly gpuDrivenFilter?: RenderPipelineGpuDrivenFilter;
+  /** Write transparent fragment depth for depth-bounded medium transport. */
+  readonly transparentDepthWrite?: boolean;
   /** Exclude material/pass pairs already consumed by an earlier graph lane. */
   readonly excludeSelector?: PassSelector;
   /** Require the same material to contribute to another graph lane. */
   readonly includeSelector?: PassSelector;
   readonly transmissionBackdropView?: TextureView | null;
+  /** Independent sampled raw depth produced before the medium passes. */
+  readonly surfaceRawDepthView?: TextureView | null;
+  /** Nearest-layer color produced by the preceding medium pass. */
+  readonly surfaceNearestLayerView?: TextureView | null;
+  /** Nearest-layer depth produced by the preceding medium pass. */
+  readonly surfaceNearestDepthView?: TextureView | null;
+  /** Surface shader fragment entry selected by the typed pass owner. */
+  readonly fragmentEntryPoint?: string;
   /** Select the material temporal entry's binary coverage output. */
   readonly coverageOnly?: boolean;
   readonly gpuDriven?: {
@@ -89,29 +108,53 @@ function isTransmissionMaterial(material: MaterialSnapshot): boolean {
 
 function matchesRecordMode(
   material: MaterialSnapshot,
-  mode: 'opaque' | 'transmission' | 'transparent',
+  mode:
+    | 'opaque'
+    | 'transmission'
+    | 'transparent'
+    | 'single-layer-medium-nearest-layer'
+    | 'single-layer-medium-color',
 ): boolean {
+  const medium =
+    material.surfaceModel === 'single-layer-medium' ||
+    material.materialShaderId === 'forgeax::single-layer-medium';
+  if (mode === 'single-layer-medium-nearest-layer' || mode === 'single-layer-medium-color') {
+    return medium;
+  }
   const transmission = isTransmissionMaterial(material);
   if (mode === 'transmission') return transmission;
-  if (mode === 'transparent') return material.transparent === true && !transmission;
-  return !transmission && material.transparent !== true;
+  if (mode === 'transparent') return material.transparent === true && !transmission && !medium;
+  return !transmission && material.transparent !== true && !medium;
 }
 
 function matchedMaterialsForRecordMode(
   c: _InternalRenderPipelineContext,
   matchedMaterials: ReadonlyMap<number, ReadonlySet<number>> | null,
-  mode: 'opaque' | 'transmission' | 'transparent' | undefined,
+  mode:
+    | 'opaque'
+    | 'transmission'
+    | 'transparent'
+    | 'single-layer-medium-nearest-layer'
+    | 'single-layer-medium-color'
+    | undefined,
 ): ReadonlyMap<number, ReadonlySet<number>> | null {
   if (mode === undefined) return matchedMaterials;
+  const surfaceMode =
+    mode === 'single-layer-medium-nearest-layer' || mode === 'single-layer-medium-color';
   const filtered = new Map<number, ReadonlySet<number>>();
   for (const entry of c.validatedOrdered) {
     const dispatchHandles = matchedMaterials?.get(entry.renderableIndex);
-    if (matchedMaterials !== null && dispatchHandles === undefined) continue;
-    const candidateHandles =
-      dispatchHandles ??
-      (mode === 'transmission'
-        ? []
-        : entry.source.materials.map((material) => material.materialHandle ?? 0));
+    // Surface graph membership is owned by the resolved surface model. A
+    // Surface-authored pass does not need to duplicate the generic Forward
+    // LightMode tag: its prepared direct program already carries the pass
+    // specialization selected by the material producer.
+    if (!surfaceMode && matchedMaterials !== null && dispatchHandles === undefined) continue;
+    const candidateHandles = surfaceMode
+      ? entry.source.materials.map((material) => material.materialHandle ?? 0)
+      : (dispatchHandles ??
+        (mode === 'transmission'
+          ? []
+          : entry.source.materials.map((material) => material.materialHandle ?? 0)));
     const handles = new Set<number>();
     for (const handle of candidateHandles) {
       const material =
@@ -173,11 +216,19 @@ export function recordMainPass(
   const passKind = options?.passKind ?? 'forward';
   const recordMode = options?.recordMode;
   const transmissionBackdropView = options?.transmissionBackdropView;
-  if (recordMode === 'transmission' && transmissionBackdropView == null) {
+  const surfaceRawDepthView = options?.surfaceRawDepthView;
+  const surfaceNearestLayerView = options?.surfaceNearestLayerView;
+  const surfaceNearestDepthView = options?.surfaceNearestDepthView;
+  if (
+    (recordMode === 'transmission' ||
+      recordMode === 'single-layer-medium-nearest-layer' ||
+      recordMode === 'single-layer-medium-color') &&
+    transmissionBackdropView == null
+  ) {
     throw new RhiError({
       code: 'webgpu-runtime-error',
-      expected: 'transmissionBackdropView != null for transmission record mode',
-      hint: 'the typed Standard transmission pass must resolve its private backdrop view',
+      expected: 'transmissionBackdropView != null for a backdrop-consuming record mode',
+      hint: 'the typed Standard backdrop pass must resolve its graph-paired color view',
     });
   }
   const colorViews = options?.colorViews ?? [geometryColorView];
@@ -224,12 +275,11 @@ export function recordMainPass(
   // fallback because the transient SSAO texture does not exist that early.
   // Built per frame (the SSAO target is a graph transient, so no cross-frame
   // cache); HDRP-only and SSAO-only, so URP and SSAO-off paths are untouched.
+  const hdrpBuffers = clusteredLighting
+    ? getOrCreateHdrpBuffers(runtime, frameState.installedPipelineConfig?.clusterGrid)
+    : null;
   let hdrpSsaoBindGroup: BindGroup | null = null;
-  if (clusteredLighting && hdrpClusterBindGroup !== null && c.hdrpSsaoBlurredView !== undefined) {
-    const hdrpBuffers = getOrCreateHdrpBuffers(
-      runtime,
-      frameState.installedPipelineConfig?.clusterGrid,
-    );
+  if (hdrpClusterBindGroup !== null && c.hdrpSsaoBlurredView !== undefined) {
     if (hdrpBuffers !== null) {
       hdrpSsaoBindGroup = createHdrpUnifiedBindGroup(
         runtime,
@@ -242,6 +292,71 @@ export function recordMainPass(
   const meshGroup2: BindGroup | null = clusteredLighting
     ? (hdrpSsaoBindGroup ?? hdrpClusterBindGroup)
     : meshBindGroup;
+  if (gpuDrivenStandardPbrFrameResources !== undefined) {
+    // The GPU-driven owner prepares before transient graph resources exist;
+    // publish the actual Standard group(2) here, at the existing main-pass
+    // binding seam, immediately before indirect encoding.
+    gpuDrivenStandardPbrFrameResources.clusterBindGroup =
+      clusteredLighting && meshGroup2 !== null ? meshGroup2 : undefined;
+    if (hdrpBuffers === null) {
+      gpuDrivenStandardPbrFrameResources.clusterBindGroupForMesh = undefined;
+      gpuDrivenStandardPbrFrameResources.clusterBindGroupForSkin = undefined;
+    } else {
+      const projectedGroups = new Map<Buffer, BindGroup>();
+      gpuDrivenStandardPbrFrameResources.clusterBindGroupForMesh = (meshBuffer, bindingBytes) => {
+        const cached = projectedGroups.get(meshBuffer);
+        if (cached !== undefined) return cached;
+        const created = createHdrpUnifiedBindGroup(
+          runtime,
+          hdrpBuffers,
+          meshBuffer,
+          c.hdrpSsaoBlurredView === undefined
+            ? { enabled: false }
+            : { enabled: true, ssaoBlurredView: c.hdrpSsaoBlurredView },
+          bindingBytes,
+        );
+        if (created !== null) projectedGroups.set(meshBuffer, created);
+        return created ?? undefined;
+      };
+      const projectedSkinGroups = new Map<Buffer, Map<Buffer, Map<string, BindGroup>>>();
+      gpuDrivenStandardPbrFrameResources.clusterBindGroupForSkin = (
+        meshBuffer,
+        meshBindingBytes,
+        paletteBuffer,
+        paletteBindingWindowBytes,
+      ) => {
+        let meshGroups = projectedSkinGroups.get(meshBuffer);
+        if (meshGroups === undefined) {
+          meshGroups = new Map();
+          projectedSkinGroups.set(meshBuffer, meshGroups);
+        }
+        let paletteGroups = meshGroups.get(paletteBuffer);
+        if (paletteGroups === undefined) {
+          paletteGroups = new Map();
+          meshGroups.set(paletteBuffer, paletteGroups);
+        }
+        const bindingKey = `${meshBindingBytes}:${paletteBindingWindowBytes}`;
+        const cached = paletteGroups.get(bindingKey);
+        if (cached !== undefined) return cached;
+        const skinLayout = pipelineState.hdrpSkinMeshBindGroupLayout;
+        if (skinLayout === null) return undefined;
+        const created = createHdrpSkinUnifiedBindGroup(
+          runtime,
+          hdrpBuffers,
+          skinLayout,
+          meshBuffer,
+          paletteBuffer,
+          paletteBindingWindowBytes,
+          c.hdrpSsaoBlurredView === undefined
+            ? { enabled: false }
+            : { enabled: true, ssaoBlurredView: c.hdrpSsaoBlurredView },
+          meshBindingBytes,
+        );
+        if (created !== null) paletteGroups.set(bindingKey, created);
+        return created ?? undefined;
+      };
+    }
+  }
   // ── Geometry (main colour) pass ──────────────────────────────────
   // D-2: tracks whether the geometry pass was explicitly ended inside
   // the `if (validatedOrdered.length > 0)` block (sprite split path),
@@ -414,7 +529,7 @@ export function recordMainPass(
           identities: [
             getOpaqueResourceIdentity(skylightResources.irradianceSampler as object),
             getOpaqueResourceIdentity(skylightResources.prefilterSampler as object),
-            getOpaqueResourceIdentity(skylightResources.brdfLutSampler as object),
+            getOpaqueResourceIdentity(skylightResources.irradianceSampler as object),
           ],
         },
         resources: {
@@ -434,7 +549,9 @@ export function recordMainPass(
           },
           brdfLut: {
             viewIdentity: getOpaqueResourceIdentity(skylightResources.brdfLutView as object),
-            samplerIdentity: getOpaqueResourceIdentity(skylightResources.brdfLutSampler as object),
+            samplerIdentity: getOpaqueResourceIdentity(
+              skylightResources.irradianceSampler as object,
+            ),
             deviceGeneration: runtime.deviceScope.generation,
           },
           intensityBufferIdentity: getOpaqueResourceIdentity(
@@ -475,7 +592,7 @@ export function recordMainPass(
     // which cannot render a PBR decal). Captures only frame-stable closure
     // state; the caller passes the per-submesh material snapshot + entityKey
     // (for video texture routing) and sets the dynamic UBO offset itself.
-    // Selection keys use the extracted frame index, never World.identity.
+    // Selection keys use the extracted frame index, never RenderResourceScope.identity.
     const hasProbeBindings = (c.reflectionProbes?.table.rows.length ?? 0) > 0;
     const worldIndices = hasProbeBindings
       ? new Map(
@@ -517,7 +634,6 @@ export function recordMainPass(
           skylightPrefilterView: skylightResources.prefilterView,
           prefilterSampler: row.sampler,
           brdfLutView: skylightResources.brdfLutView,
-          brdfLutSampler: skylightResources.brdfLutSampler,
           intensityBuffer: row.uniformBuffer,
         };
         return { resources: probeResources, probeIndex: row.index };
@@ -535,11 +651,14 @@ export function recordMainPass(
               gpuDrivenSceneMaterialBuffer,
           }),
       ...(transmissionBackdropView === undefined ? {} : { transmissionBackdropView }),
+      ...(surfaceRawDepthView === undefined ? {} : { surfaceRawDepthView }),
+      ...(surfaceNearestLayerView === undefined ? {} : { surfaceNearestLayerView }),
+      ...(surfaceNearestDepthView === undefined ? {} : { surfaceNearestDepthView }),
     };
     const buildPerSubmeshMaterialBg = (
       submeshMaterial: MaterialSnapshot,
       entityKey: number,
-      materialWorld: World = world,
+      materialWorld: RenderResourceScope = world,
       materialShaderId: string | undefined = submeshMaterial.materialShaderId,
     ): BindGroup =>
       buildPerSubmeshMaterialBgImpl(
@@ -558,6 +677,12 @@ export function recordMainPass(
     for (let materialSlot = 0; materialSlot < materialSlotCount; materialSlot += 1) {
       const material = materialSlots[materialSlot];
       if (material === undefined || (material.videoTextureFields?.size ?? 0) > 0) continue;
+      // A graph scene pass owns only the materials selected by its record
+      // mode. In particular, the opaque pass runs before the raw-depth
+      // producer and must not assemble medium bindings with resources that do
+      // not exist until the later nearest-layer/color passes. Keep holes for
+      // the other lanes; the GPU encoder validates the exact slot it consumes.
+      if (recordMode !== undefined && !matchesRecordMode(material, recordMode)) continue;
       const owner = materialSlotOwners[materialSlot];
       if (owner === undefined) continue;
       preparedMaterialBindGroups[materialSlot] = buildPerSubmeshMaterialBg(
@@ -624,7 +749,7 @@ export function recordMainPass(
       materialSlot: number,
       material: MaterialSnapshot,
       entityKey: number,
-      materialWorld: World = world,
+      materialWorld: RenderResourceScope = world,
       materialShaderId: string | undefined = material.materialShaderId,
     ): BindGroup =>
       !hasProbeBindings &&
@@ -656,6 +781,13 @@ export function recordMainPass(
         selectedDispatch,
         colorFormats,
         options?.coverageOnly ?? false,
+        options?.fragmentEntryPoint,
+        recordMode === 'single-layer-medium-nearest-layer'
+          ? 'nearest-layer'
+          : recordMode === 'single-layer-medium-color'
+            ? 'color'
+            : undefined,
+        options?.transparentDepthWrite ?? false,
       );
     };
     if (c.profilePhase === undefined) {
@@ -676,7 +808,10 @@ export function recordMainPass(
           hint: 'publish the current frame view/light/shadow bind group before GPU raster',
         });
       }
-      if (gpuDrivenStandardPbrFrameResources === undefined) {
+      if (
+        gpuDrivenStandardPbrFrameResources === undefined ||
+        gpuDrivenStandardPbrFrameResources.materialBindGroups.length === 0
+      ) {
         throw new RhiError({
           code: 'rhi-not-available',
           expected: 'complete main-pass Standard PBR material bind-group receipt',
@@ -688,6 +823,8 @@ export function recordMainPass(
         pass,
         options.gpuDriven.resources,
         gpuDrivenStandardPbrFrameResources,
+        options.gpuDrivenFilter,
+        options?.fragmentEntryPoint,
       );
     }
 

package/src/record/motion-blur-receipt.ts

@@ -0,0 +1,91 @@
+import { getRenderFeaturePlanExecutionProjection } from '../features/host';
+import type { RenderFeaturePlannedFrame } from '../features/plan';
+import type { MotionBlurExecutionPass, MotionBlurExecutionReceipt } from '../inspection-types';
+import type { RenderFrameState } from './frame-snapshot';
+import type { RenderSystemInternals } from './render-context';
+
+/**
+ * Project one accepted Motion Blur compute execution from the same graph and
+ * resolved dispatch objects used by the encoder. A plan/capability candidate
+ * without both executed passes deliberately returns no receipt.
+ */
+export function deriveMotionBlurExecutionReceipt(
+  internals: RenderSystemInternals,
+  frameState: RenderFrameState,
+  plans: readonly RenderFeaturePlannedFrame[],
+): MotionBlurExecutionReceipt | undefined {
+  const graph = frameState.compiledFrameGraph;
+  const deviceGeneration = internals.deviceScope?.generation;
+  if (graph === null || deviceGeneration === undefined) return undefined;
+  const info = graph.inspect();
+  const graphPasses = new Map(info.passes.map((pass) => [pass.name, pass]));
+  const summaryGraphPass = graphPasses.get('motion-blur-tile-summary');
+  const reconstructGraphPass = graphPasses.get('motion-blur');
+  if (summaryGraphPass?.kind !== 'compute' || reconstructGraphPass?.kind !== 'compute') {
+    return undefined;
+  }
+  const planned = plans.find((candidate) => candidate.featureIdentity === 'forgeax.motion-blur');
+  const execution =
+    planned === undefined ? undefined : getRenderFeaturePlanExecutionProjection(planned);
+  if (execution === undefined || execution.featureIdentity !== 'forgeax.motion-blur') {
+    return undefined;
+  }
+  const executionPass = (name: 'motion-blur-tile-summary' | 'motion-blur') =>
+    execution.passes.find((pass) => pass.name === name);
+  const summary = executionPass('motion-blur-tile-summary');
+  const reconstruct = executionPass('motion-blur');
+  if (
+    summary?.gpuCompute === undefined ||
+    reconstruct?.gpuCompute === undefined ||
+    summary.resolvedGpuCompute === undefined ||
+    reconstruct.resolvedGpuCompute === undefined
+  ) {
+    return undefined;
+  }
+  const directWorkgroups = (
+    pass: NonNullable<typeof summary.resolvedGpuCompute>,
+  ): readonly [number, number, number] | undefined => {
+    const dispatch = pass.dispatches[0];
+    if (dispatch === undefined || !('workgroups' in dispatch)) return undefined;
+    return dispatch.workgroups;
+  };
+  const summaryWorkgroups = directWorkgroups(summary.resolvedGpuCompute);
+  const reconstructWorkgroups = directWorkgroups(reconstruct.resolvedGpuCompute);
+  if (summaryWorkgroups === undefined || reconstructWorkgroups === undefined) return undefined;
+  const outputResource = info.resources.find(
+    (resource) =>
+      resource.label === 'motion-blurred-color' ||
+      reconstructGraphPass.accesses.some(
+        (access) => access.resource === resource.label && access.usage === 'storage-write',
+      ),
+  );
+  if (
+    outputResource?.descriptor.kind !== 'texture' ||
+    outputResource.descriptor.format !== 'rgba16float'
+  ) {
+    return undefined;
+  }
+  const summaryReceipt: MotionBlurExecutionPass = {
+    name: 'motion-blur-tile-summary',
+    kind: 'compute',
+    entryPoint: 'tile_summary',
+    workgroups: summaryWorkgroups,
+  };
+  const reconstructReceipt: MotionBlurExecutionPass = {
+    name: 'motion-blur',
+    kind: 'compute',
+    entryPoint: 'reconstruct',
+    workgroups: reconstructWorkgroups,
+  };
+  return Object.freeze({
+    frameId: frameState.frameNumber,
+    deviceGeneration,
+    // RenderGraphBuilder generations are process-global. The renderer's
+    // frame-state generation is the identity used by inspection and by the
+    // same-frame admission check below, so retain that owner-scoped value.
+    graphGeneration: frameState.graphGeneration,
+    program: 'motion-blur-compute' as const,
+    outputFormat: 'rgba16float' as const,
+    passes: [summaryReceipt, reconstructReceipt] as const,
+  });
+}

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

@@ -1,5 +1,4 @@
 import { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
-import type { World } from '@forgeax/engine-ecs';
 import type { BindGroupEntry, BindGroupLayout, Buffer } from '@forgeax/engine-rhi';
 import { err, ok } from '@forgeax/engine-rhi';
 import {
@@ -14,6 +13,8 @@ import { transmissionBackdropAvailable } from '../assembly/device-feature-admiss
 import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_UNIFORM } from '../gpu-usage';
 import type { SkylightBindGroupResources } from '../ibl/skylight-bind-group';
 import { assembleMaterialWithSkylightEntries } from '../ibl/skylight-bind-group';
+import type { RenderResourceScope } from '../publication/resource-scope';
+import { renderAssetByGuid } from '../publication/resource-scope';
 import {
   applyParamSchemaDefaultsToUbo,
   applyParamSnapshotToUbo,
@@ -28,7 +29,7 @@ export type PreparedResolverCaches = {
   readonly preparedGroup0Pipelines: WeakSet<object>;
   readonly preparedViewOnlyPipelines: WeakSet<object>;
   readonly preparedRenderMaterialPipelines: WeakSet<object>;
-  readonly preparedAssetHandles: WeakMap<World, Map<string, number>>;
+  readonly preparedAssetHandles: WeakMap<RenderResourceScope, Map<string, number>>;
 };
 
 export function createPreparedResolverCaches(): PreparedResolverCaches {
@@ -45,7 +46,7 @@ export function createPreparedResolverCaches(): PreparedResolverCaches {
 function preparedHandle<Brand extends string>(
   runtime: RenderSystemInternals,
   caches: PreparedResolverCaches,
-  world: World,
+  world: RenderResourceScope,
   guid: string,
   brand: Brand,
 ): Handle<Brand, 'shared'> | undefined {
@@ -57,6 +58,8 @@ function preparedHandle<Brand extends string>(
   const key = `${brand}:${guid.toLowerCase()}`;
   const cached = handles.get(key);
   if (cached !== undefined) return cached as Handle<Brand, 'shared'>;
+  if ('resolveAsset' in world)
+    return world.handleForGuid(guid) as Handle<Brand, 'shared'> | undefined;
   const asset = runtime.assets.lookup(guid);
   if (asset === undefined) return undefined;
   const handle = world.allocSharedRef(brand, asset);
@@ -67,7 +70,7 @@ function preparedHandle<Brand extends string>(
 export function preparedMaterialBindings(
   runtime: RenderSystemInternals,
   caches: PreparedResolverCaches,
-  worlds: readonly World[],
+  worlds: readonly RenderResourceScope[],
   materialShaderId: string,
   worldIndex: number,
   materialGuid: string,
@@ -75,7 +78,10 @@ export function preparedMaterialBindings(
   skylightResources?: SkylightBindGroupResources,
 ) {
   const world = worlds[worldIndex];
-  const material = runtime.assets.lookup(materialGuid) as MaterialAsset | undefined;
+  const material =
+    world === undefined
+      ? undefined
+      : renderAssetByGuid<MaterialAsset>(world, runtime.assets, materialGuid);
   const pipelineState = runtime.getPipelineState();
   if (world === undefined || material?.kind !== 'material' || pipelineState === null) {
     return err(new Error('prepared material asset is unavailable'));
@@ -203,7 +209,6 @@ export function preparedMaterialBindings(
       prefilterView: fallback.prefilterView,
       prefilterSampler: fallback.sampler,
       brdfLutView: fallback.brdfLutView,
-      brdfLutSampler: fallback.sampler,
       intensityBuffer: fallback.intensityBuffer,
     },
     transmissionBackdropAvailable(runtime.device.limits.maxSampledTexturesPerShaderStage)

package/src/record/probe-blend-buffer.ts

@@ -0,0 +1,180 @@
+import type { Buffer, RhiDevice } from '@forgeax/engine-rhi';
+import { GpuBuffer } from '../gpu-resource';
+import {
+  GPU_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_STORAGE,
+  GPU_BUFFER_USAGE_UNIFORM,
+} from '../gpu-usage';
+import type { ProbeBlendBufferProjection } from '../scene/probe-blend';
+import {
+  PROBE_BLEND_RECORD_STRIDE,
+  type ProbeBlendRecord,
+  probeBlendRecordOffset,
+} from '../scene/probe-blend-record';
+import type { RenderFrameState } from './frame-snapshot';
+
+export interface ProbeBlendBufferRecord {
+  readonly cacheKey: number;
+  readonly record: ProbeBlendRecord;
+}
+
+function isProbeBlendProjection(
+  input: ProbeBlendBufferProjection | readonly ProbeBlendBufferRecord[],
+): input is ProbeBlendBufferProjection {
+  return !Array.isArray(input);
+}
+
+function retireProbeBlendRecordBuffer(buffer: GpuBuffer): void {
+  const destroy = (): void => {
+    if (!buffer.isDestroyed) void buffer.destroy();
+  };
+  void buffer.device.queue.onSubmittedWorkDone().then(destroy, destroy);
+}
+
+function createCompleteProbeBlendBuffer(
+  device: RhiDevice,
+  requiredCapacity: number,
+  records: readonly ProbeBlendBufferRecord[],
+): {
+  readonly buffer: GpuBuffer;
+  readonly cache: ReadonlyMap<number, { readonly generation: number; readonly bytes: Uint8Array }>;
+} {
+  const created = device.createBuffer({
+    label: 'probe-blend-records',
+    size: requiredCapacity * PROBE_BLEND_RECORD_STRIDE,
+    usage:
+      (device.caps.storageBuffer ? GPU_BUFFER_USAGE_STORAGE : GPU_BUFFER_USAGE_UNIFORM) |
+      GPU_BUFFER_USAGE_COPY_DST,
+    mappedAtCreation: false,
+  });
+  if (!created.ok) throw created.error;
+  const candidate = new GpuBuffer(device, created.value);
+  const cache = new Map<number, { readonly generation: number; readonly bytes: Uint8Array }>();
+  try {
+    for (const { cacheKey, record } of records) {
+      const uploaded = device.queue.writeBuffer(
+        candidate.handle,
+        probeBlendRecordOffset(record.objectKey),
+        record.bytes,
+      );
+      if (!uploaded.ok) throw uploaded.error;
+      cache.set(cacheKey, {
+        generation: record.generation,
+        bytes: new Uint8Array(record.bytes),
+      });
+    }
+  } catch (cause) {
+    void candidate.destroy();
+    throw cause;
+  }
+  return { buffer: candidate, cache };
+}
+
+/**
+ * Retain one device buffer for direct and scene-index ProbeBlend consumers.
+ * Capacity is settled before any upload so a growth cannot erase records
+ * written earlier in the same frame. Slot zero remains the producer sentinel;
+ * RenderScene object slot N occupies aligned record N+1.
+ */
+export function ensureProbeBlendRecordBuffer(
+  device: RhiDevice,
+  frameState: Pick<
+    RenderFrameState,
+    | 'probeBlendRecordBuffer'
+    | 'probeBlendRecordBufferCapacity'
+    | 'probeBlendBuffers'
+    | 'probeBlendRecordProjection'
+  >,
+  input: ProbeBlendBufferProjection | readonly ProbeBlendBufferRecord[] | undefined,
+): Buffer | undefined {
+  const projection = input !== undefined && isProbeBlendProjection(input) ? input : undefined;
+  const records: readonly ProbeBlendBufferRecord[] =
+    input === undefined
+      ? []
+      : (projection?.records ?? (input as readonly ProbeBlendBufferRecord[]));
+  let buffer = frameState.probeBlendRecordBuffer;
+  const accepted = frameState.probeBlendRecordProjection;
+  if (
+    projection !== undefined &&
+    accepted?.projection === projection &&
+    accepted.device === device
+  ) {
+    if (records.length === 0) return undefined;
+    if (accepted.buffer === buffer && buffer !== undefined && !buffer.isDestroyed) {
+      return buffer.handle;
+    }
+  }
+  if (records.length === 0) {
+    if (projection !== undefined) {
+      frameState.probeBlendBuffers.clear();
+      frameState.probeBlendRecordProjection = {
+        projection,
+        device,
+        buffer: undefined,
+      };
+    }
+    return undefined;
+  }
+  const requiredCapacity =
+    projection?.capacity ??
+    records.reduce((capacity, { record }) => Math.max(capacity, record.objectKey + 2), 1);
+  const grows =
+    buffer === undefined ||
+    buffer.isDestroyed ||
+    buffer.device !== device ||
+    frameState.probeBlendRecordBufferCapacity < requiredCapacity;
+  const hasAcceptedBaseline =
+    projection !== undefined &&
+    accepted !== undefined &&
+    accepted.device === device &&
+    accepted.buffer === buffer &&
+    buffer !== undefined &&
+    !buffer.isDestroyed &&
+    accepted.projection.sourceIdentity === projection.sourceIdentity &&
+    accepted.projection.revision === projection.baseRevision;
+  const requiresCompletePublish =
+    grows ||
+    (projection !== undefined && (!hasAcceptedBaseline || projection.dirtyRecords.length > 1));
+  if (requiresCompletePublish) {
+    const candidate = createCompleteProbeBlendBuffer(device, requiredCapacity, records);
+    const previous = buffer;
+    buffer = candidate.buffer;
+    frameState.probeBlendRecordBuffer = candidate.buffer;
+    frameState.probeBlendRecordBufferCapacity = requiredCapacity;
+    frameState.probeBlendBuffers.clear();
+    for (const [key, value] of candidate.cache) frameState.probeBlendBuffers.set(key, value);
+    if (projection === undefined) delete frameState.probeBlendRecordProjection;
+    else frameState.probeBlendRecordProjection = { projection, device, buffer: candidate.buffer };
+    if (previous !== undefined) retireProbeBlendRecordBuffer(previous);
+    return candidate.buffer.handle;
+  }
+  if (buffer === undefined) return undefined;
+  const changed = projection?.dirtyRecords ?? records;
+  const cacheUpdates: [number, { readonly generation: number; readonly bytes: Uint8Array }][] = [];
+  for (const { cacheKey, record } of changed) {
+    const cached = frameState.probeBlendBuffers.get(cacheKey);
+    const unchanged =
+      cached !== undefined &&
+      cached.generation === record.generation &&
+      cached.bytes.length === record.bytes.length &&
+      cached.bytes.every((value, index) => value === record.bytes[index]);
+    if (unchanged) continue;
+    const uploaded = device.queue.writeBuffer(
+      buffer.handle,
+      probeBlendRecordOffset(record.objectKey),
+      record.bytes,
+    );
+    if (!uploaded.ok) throw uploaded.error;
+    cacheUpdates.push([
+      cacheKey,
+      { generation: record.generation, bytes: new Uint8Array(record.bytes) },
+    ]);
+  }
+  for (const [cacheKey, value] of cacheUpdates) frameState.probeBlendBuffers.set(cacheKey, value);
+  for (const cacheKey of projection?.removedCacheKeys ?? []) {
+    frameState.probeBlendBuffers.delete(cacheKey);
+  }
+  if (projection === undefined) delete frameState.probeBlendRecordProjection;
+  else frameState.probeBlendRecordProjection = { projection, device, buffer };
+  return buffer.handle;
+}