@forgeax/engine-render 0.1.19 → 0.1.21

package/src/hdrp-buffers.ts

@@ -48,6 +48,7 @@ import {
   GPU_BUFFER_USAGE_UNIFORM,
 } from './gpu-usage';
 import { BYTES_PER_LIGHT_SLOT } from './light-buffer-layout';
+import { createPbrSkinMeshBindGroupEntries } from './pbr-pipeline';
 import {
   CLUSTER_GRID_STRIDE_U32,
   DEFAULT_CLUSTER_GRID,
@@ -55,20 +56,12 @@ import {
   MAX_LIGHTS,
 } from './pipeline/standard-profile';
 import { createHdrpBindGroupLayoutDescriptor } from './pipeline-spec';
-import { MESH_PER_ENTITY_STRIDE, MESH_UBO_FULL_ARRAY_BYTES } from './record/mesh-ssbo';
+import { MESH_PER_ENTITY_STRIDE } from './record/mesh-ssbo';
 import type { RenderSystemRuntime } from './record/render-context';
 import { getOrCreateSsaoFallbackTexture } from './ssao-buffers';
 
 export { getOrCreateSsaoFallbackTexture } from './ssao-buffers';
 
-/**
- * WebGL2 HDRP downlevel light-list capacity. 128 x 64 B = 8 KiB, below the
- * WebGL2 minimum uniform-buffer binding size of 16 KiB. The storage path
- * keeps the full MAX_LIGHTS budget; the uniform path uses the same LightSlot
- * POD and only changes the transport.
- */
-export const HDRP_UNIFORM_LIGHT_CAPACITY = 128;
-
 /** Bind-group layout used only by the WebGPU cluster membership producer. */
 export function createHdrpClusterMembershipBindGroupLayoutDescriptor(): BindGroupLayoutDescriptor {
   return {
@@ -111,9 +104,9 @@ export function createHdrpClusterMembershipBindGroupLayoutDescriptor(): BindGrou
  * cluster 4 buffer).
  */
 export interface HdrpBuffers {
-  /** Whether bindings 3..5 carry storage buffers or uniform-buffer fallback data. */
-  readonly storageBuffer: boolean;
-  /** light_data -- 256 x 64 B on storage, 128 x 64 B on uniform fallback. */
+  /** Device identity that owns every handle in this bundle. */
+  readonly device: RenderSystemRuntime['device'];
+  /** light_data -- the full 256 x 64 B Standard light budget. */
   readonly lightDataBuffer: Buffer;
   readonly lightDataBytes: number;
   /** cluster_grid SSBO -- gridX*gridY*gridZ * 2 u32, BGL slot 4. */
@@ -145,66 +138,92 @@ const cache = new WeakMap<RenderSystemRuntime, HdrpBuffers>();
  * pipeline disable (charter P3 explicit failure).
  *
  * `grid` defaults to `DEFAULT_CLUSTER_GRID` when undefined (matches the M5
- * record-stage default). The buffers are sized at the *first* call's grid; a
- * later install with a different grid keeps the existing allocation as long as
- * it has enough capacity (gridX*gridY*gridZ <= cached.grid product). Different
- * grids that exceed capacity are not currently re-allocated -- M-future.
+ * record-stage default). A smaller grid reuses the existing capacity. When a
+ * later install requests a larger grid, this owner allocates a complete new
+ * bundle, publishes it atomically, and retires the previous bundle after the
+ * device queue fence so graph and bind-group caches never observe a partially
+ * replaced resource set.
  */
 export function getOrCreateHdrpBuffers(
   runtime: RenderSystemRuntime,
   grid: { x: number; y: number; z: number } = DEFAULT_CLUSTER_GRID,
 ): HdrpBuffers | null {
+  // Cluster has one code-level transport. Capability failure is handled by
+  // Standard transport admission; this owner never creates a second UBO ABI.
+  if (runtime.device.caps?.storageBuffer !== true) return null;
+  // Contract tests and reduced host adapters may advertise storage buffers
+  // without implementing the resource-creation surface. Treat that as a
+  // capability miss rather than dereferencing an absent method; callers
+  // already route `null` through the structured cluster-transport fallback.
+  const deviceSurface = runtime.device as unknown as {
+    readonly createBuffer?: unknown;
+    readonly createBindGroupLayout?: unknown;
+    readonly destroyBuffer?: unknown;
+  };
+  if (
+    typeof deviceSurface.createBuffer !== 'function' ||
+    typeof deviceSurface.createBindGroupLayout !== 'function' ||
+    typeof deviceSurface.destroyBuffer !== 'function'
+  ) {
+    return null;
+  }
   const cached = cache.get(runtime);
-  if (cached !== undefined) return cached;
-
+  if (cached !== undefined && cached.device === runtime.device) {
+    const requestedCells = grid.x * grid.y * grid.z;
+    const cachedCells = cached.grid.x * cached.grid.y * cached.grid.z;
+    if (requestedCells <= cachedCells) return cached;
+  }
   const device = runtime.device;
-  const storageBuffer = runtime.device.caps?.storageBuffer === true;
   const clusterUniformBytes = 32;
-  const lightDataBytes =
-    (storageBuffer ? MAX_LIGHTS : HDRP_UNIFORM_LIGHT_CAPACITY) * BYTES_PER_LIGHT_SLOT;
+  const lightDataBytes = MAX_LIGHTS * BYTES_PER_LIGHT_SLOT;
   const clusterCells = grid.x * grid.y * grid.z;
-  const clusterGridBytes = storageBuffer
-    ? clusterCells * CLUSTER_GRID_STRIDE_U32 * 4
-    : clusterUniformBytes;
-  const lightIndexListBytes = storageBuffer ? LIGHT_INDEX_LIST_CAPACITY * 4 : clusterUniformBytes;
+  const clusterGridBytes = clusterCells * CLUSTER_GRID_STRIDE_U32 * 4;
+  const lightIndexListBytes = LIGHT_INDEX_LIST_CAPACITY * 4;
   const lightBoundsBytes = MAX_LIGHTS * 6 * 4;
+  const created: Buffer[] = [];
+  const releaseCreated = (): void => {
+    for (const buffer of created) {
+      const result = device.destroyBuffer(buffer);
+      if (!result.ok) runtime.errorRegistry.fire(result.error);
+    }
+    created.length = 0;
+  };
+  const failAllocation = (error: RhiError): null => {
+    runtime.errorRegistry.fire(error);
+    releaseCreated();
+    return null;
+  };
 
   const lightData = device.createBuffer({
     label: 'hdrp-light-data',
     size: lightDataBytes,
-    usage:
-      (storageBuffer ? GPU_BUFFER_USAGE_STORAGE : GPU_BUFFER_USAGE_UNIFORM) |
-      GPU_BUFFER_USAGE_COPY_DST,
+    usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST,
     mappedAtCreation: false,
   });
   if (!lightData.ok) {
-    runtime.errorRegistry.fire(lightData.error);
-    return null;
+    return failAllocation(lightData.error);
   }
+  created.push(lightData.value);
   const clusterGrid = device.createBuffer({
     label: 'hdrp-cluster-grid',
     size: clusterGridBytes,
-    usage:
-      (storageBuffer ? GPU_BUFFER_USAGE_STORAGE : GPU_BUFFER_USAGE_UNIFORM) |
-      GPU_BUFFER_USAGE_COPY_DST,
+    usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST,
     mappedAtCreation: false,
   });
   if (!clusterGrid.ok) {
-    runtime.errorRegistry.fire(clusterGrid.error);
-    return null;
+    return failAllocation(clusterGrid.error);
   }
+  created.push(clusterGrid.value);
   const lightIndexList = device.createBuffer({
     label: 'hdrp-light-index-list',
     size: lightIndexListBytes,
-    usage:
-      (storageBuffer ? GPU_BUFFER_USAGE_STORAGE : GPU_BUFFER_USAGE_UNIFORM) |
-      GPU_BUFFER_USAGE_COPY_DST,
+    usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST,
     mappedAtCreation: false,
   });
   if (!lightIndexList.ok) {
-    runtime.errorRegistry.fire(lightIndexList.error);
-    return null;
+    return failAllocation(lightIndexList.error);
   }
+  created.push(lightIndexList.value);
   const clusterUniform = device.createBuffer({
     label: 'hdrp-cluster-uniform',
     size: clusterUniformBytes,
@@ -212,36 +231,30 @@ export function getOrCreateHdrpBuffers(
     mappedAtCreation: false,
   });
   if (!clusterUniform.ok) {
-    runtime.errorRegistry.fire(clusterUniform.error);
-    return null;
+    return failAllocation(clusterUniform.error);
   }
+  created.push(clusterUniform.value);
   const lightBounds = device.createBuffer({
     label: 'hdrp-light-bounds',
     size: lightBoundsBytes,
-    usage:
-      (storageBuffer ? GPU_BUFFER_USAGE_STORAGE : GPU_BUFFER_USAGE_UNIFORM) |
-      GPU_BUFFER_USAGE_COPY_DST,
+    usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST,
     mappedAtCreation: false,
   });
   if (!lightBounds.ok) {
-    runtime.errorRegistry.fire(lightBounds.error);
-    return null;
+    return failAllocation(lightBounds.error);
   }
+  created.push(lightBounds.value);
 
   // Create the unified 7-entry BGL layout for group(2)
   // (plan D-6, feat-20260609-hdrp-cluster-fragment-ggx M3).
   // The HDRP BGL descriptor is owned by pipeline-spec and shared with the
   // pipeline dispatcher and its byte-identical tests.
-  const storageBufferCap = runtime.device.caps?.storageBuffer === true;
-  const unifiedBglRes = device.createBindGroupLayout(
-    createHdrpBindGroupLayoutDescriptor(storageBufferCap),
-  );
+  const unifiedBglRes = device.createBindGroupLayout(createHdrpBindGroupLayoutDescriptor());
   if (!unifiedBglRes.ok) {
-    runtime.errorRegistry.fire(unifiedBglRes.error);
-    return null;
+    return failAllocation(unifiedBglRes.error);
   }
   const buffers: HdrpBuffers = {
-    storageBuffer,
+    device,
     lightDataBuffer: lightData.value,
     lightDataBytes,
     clusterGridBuffer: clusterGrid.value,
@@ -256,16 +269,57 @@ export function getOrCreateHdrpBuffers(
     unifiedBindGroupLayout: unifiedBglRes.value,
   };
   cache.set(runtime, buffers);
+  if (cached !== undefined) {
+    retireHdrpBuffers(runtime, cached);
+  }
   return buffers;
 }
 
+/**
+ * Drop the cached bundle before a device recovery or renderer disposal. The
+ * bundle carries the old device identity, so retirement fences that device's
+ * queue instead of consulting the replacement runtime device.
+ */
+export function resetHdrpBuffers(runtime: RenderSystemRuntime): void {
+  const cached = cache.get(runtime);
+  if (cached === undefined) return;
+  cache.delete(runtime);
+  retireHdrpBuffers(runtime, cached);
+}
+
+function retireHdrpBuffers(runtime: RenderSystemRuntime, buffers: HdrpBuffers): void {
+  const device = buffers.device;
+  const destroy = (): void => {
+    for (const buffer of [
+      buffers.lightDataBuffer,
+      buffers.clusterGridBuffer,
+      buffers.lightIndexListBuffer,
+      buffers.clusterUniformBuffer,
+      buffers.lightBoundsBuffer,
+    ]) {
+      const result = device.destroyBuffer(buffer);
+      if (!result.ok) runtime.errorRegistry.fire(result.error);
+    }
+  };
+  const queue = device.queue as {
+    readonly onSubmittedWorkDone?: () => Promise<undefined>;
+  };
+  if (typeof queue.onSubmittedWorkDone === 'function') {
+    queue.onSubmittedWorkDone().then(destroy, destroy);
+  } else {
+    // Minimal null/test devices may not expose queue fences; they also have no
+    // submitted work that can retain the old bundle, so release synchronously.
+    destroy();
+  }
+}
+
 /**
  * Build the 8-float cluster_uniform std140 payload.
  *
  *   [0] gridX  u32 (cast in shader)
  *   [1] gridY  u32
  *   [2] gridZ  u32
- *   [3] lightCount u32 (vec4 alignment; capped by the active transport)
+ *   [3] lightCount u32 (vec4 alignment; capped by MAX_LIGHTS)
  *   [4] near   f32
  *   [5] far    f32
  *   [6] logFarOverNear  f32
@@ -286,7 +340,6 @@ export function packClusterUniform(
   far: number,
   ssaoIntensity: number = 0,
   lightCount: number = 0,
-  lightCapacity: number = HDRP_UNIFORM_LIGHT_CAPACITY,
 ): ArrayBuffer {
   const buf = new ArrayBuffer(32);
   const u32 = new Uint32Array(buf);
@@ -294,7 +347,7 @@ export function packClusterUniform(
   u32[0] = grid.x >>> 0;
   u32[1] = grid.y >>> 0;
   u32[2] = grid.z >>> 0;
-  u32[3] = Math.min(Math.max(lightCount, 0), lightCapacity) >>> 0;
+  u32[3] = Math.min(Math.max(lightCount, 0), MAX_LIGHTS) >>> 0;
   f32[4] = near;
   f32[5] = far;
   // logFarOverNear: log(far/near) used by the shader for log-z slice mapping.
@@ -318,7 +371,7 @@ export function packClusterUniform(
  * feat-20260609-hdrp-cluster-fragment-ggx M4 / w19. Called per-frame from the
  * recordFrame HDRP block after binner+writeBuffer; the resulting BindGroup
  * lands on `passCtx.hdrpClusterBindGroup` and recordMainPass binds it at
- * group(2) when `frameState.isHdrpActive`.
+ * group(2) when the prepared Standard topology selects clustered lighting.
  *
  * Returns `null` on `device.createBindGroup` failure (a structured RhiError
  * is fired on `runtime.errorRegistry`); recordMainPass gracefully falls back
@@ -386,7 +439,7 @@ export function createHdrpUnifiedBindGroup(
           value: {
             buffer: meshStorageBuffer,
             offset: 0,
-            size: hdrpBuffers.storageBuffer ? MESH_PER_ENTITY_STRIDE : MESH_UBO_FULL_ARRAY_BYTES,
+            size: MESH_PER_ENTITY_STRIDE,
           },
         },
       },
@@ -435,6 +488,59 @@ export function createHdrpUnifiedBindGroup(
   return result.value;
 }
 
+/** Build the clustered skin group(2) bind group with one shared palette window. */
+export function createHdrpSkinUnifiedBindGroup(
+  runtime: RenderSystemRuntime,
+  hdrpBuffers: HdrpBuffers,
+  layout: BindGroupLayout,
+  meshStorageBuffer: Buffer,
+  paletteBuffer: Buffer,
+  paletteBindingWindowBytes: number,
+  ssaoOptions: SsaoBindOptions = { enabled: false },
+): BindGroup | null {
+  const fallback = getOrCreateSsaoFallbackTexture(runtime);
+  if (fallback === null) return null;
+  const meshSize = MESH_PER_ENTITY_STRIDE;
+  const result = runtime.device.createBindGroup({
+    label: 'hdrp-skin-unified-bg-group2',
+    layout,
+    entries: [
+      ...createPbrSkinMeshBindGroupEntries(
+        meshStorageBuffer,
+        meshSize,
+        paletteBuffer,
+        paletteBindingWindowBytes,
+      ),
+      { binding: 3, resource: { kind: 'buffer', value: { buffer: hdrpBuffers.lightDataBuffer } } },
+      {
+        binding: 4,
+        resource: { kind: 'buffer', value: { buffer: hdrpBuffers.clusterGridBuffer } },
+      },
+      {
+        binding: 5,
+        resource: { kind: 'buffer', value: { buffer: hdrpBuffers.lightIndexListBuffer } },
+      },
+      {
+        binding: 6,
+        resource: { kind: 'buffer', value: { buffer: hdrpBuffers.clusterUniformBuffer } },
+      },
+      {
+        binding: 7,
+        resource: {
+          kind: 'textureView',
+          value: ssaoOptions.enabled ? ssaoOptions.ssaoBlurredView : fallback.view,
+        },
+      },
+      { binding: 8, resource: { kind: 'sampler', value: fallback.sampler } },
+    ],
+  });
+  if (!result.ok) {
+    runtime.errorRegistry.fire(result.error);
+    return null;
+  }
+  return result.value;
+}
+
 /**
  * Build the compute-only bind group for ordered cluster membership output.
  * Its group is intentionally separate from the fragment group: the same

package/src/ibl/IblPipelineCache.ts

@@ -43,6 +43,14 @@ import {
   type TextureView,
 } from '@forgeax/engine-rhi';
 import type { DeviceScope } from '../device/device-scope';
+import { createIblKernelCache, type IblKernelCache } from './kernel-cache';
+
+export {
+  createIblKernelCache,
+  type IblKernelCache,
+  resetIblKernelCaches,
+} from './kernel-cache';
+
 import { GPU_SHADER_STAGE_FRAGMENT, GPU_SHADER_STAGE_VERTEX } from '../gpu-stage';
 import {
   GPU_TEXTURE_USAGE_COPY_DST,
@@ -90,6 +98,8 @@ export interface IblPipelineError {
  * (idempotent).
  */
 export interface IblPipelineCache {
+  /** Reusable generation-scoped kernel state; per-probe outputs stay elsewhere. */
+  readonly probeKernel: IblKernelCache;
   /** Color format shared by all precompute outputs for this device. */
   outputFormat?: TextureFormat;
   /** Equirectangular-to-cubemap pipeline. */
@@ -151,6 +161,7 @@ export function getOrCreateIblCache(scope: DeviceScope): IblPipelineCache {
   if (existing !== undefined) return existing;
 
   const cache: IblPipelineCache = {
+    probeKernel: createIblKernelCache(scope.generation),
     irradianceBakeCount: 0,
     prefilterBakeCount: 0,
     brdfLutBakeCount: 0,

package/src/ibl/kernel-cache.ts

@@ -0,0 +1,88 @@
+export const REFLECTION_PROBE_IBL_STAGES = ['raw', 'filtered', 'publish'] as const;
+export type ReflectionProbeIblStage = (typeof REFLECTION_PROBE_IBL_STAGES)[number];
+
+export interface IblKernelCache {
+  readonly generation: number;
+  readonly pipelineIdentity: object;
+  readonly samplerIdentity: object;
+  readonly brdfLutIdentity: object;
+}
+
+const kernelCaches = new Map<number, IblKernelCache>();
+
+export function createIblKernelCache(generation: number): IblKernelCache {
+  const existing = kernelCaches.get(generation);
+  if (existing !== undefined) return existing;
+  const created: IblKernelCache = {
+    generation,
+    pipelineIdentity: {},
+    samplerIdentity: {},
+    brdfLutIdentity: {},
+  };
+  kernelCaches.set(generation, created);
+  return created;
+}
+
+export interface ProbeIblOutput {
+  readonly entityKey: number;
+  readonly resolution: number;
+  readonly deviceGeneration: number;
+  readonly raw: object;
+  readonly filtered: object;
+  readonly rawGeneration: number;
+  readonly filteredGeneration: number;
+  readonly lkg: boolean;
+}
+
+export interface ProbeIblUpdate extends ProbeIblOutput {
+  readonly stages: typeof REFLECTION_PROBE_IBL_STAGES;
+  readonly nextStage: ReflectionProbeIblStage;
+  readonly candidateGeneration: number;
+}
+
+export function createProbeIblOutput(input: {
+  readonly entityKey: number;
+  readonly resolution: number;
+  readonly deviceGeneration: number;
+}): ProbeIblOutput {
+  return {
+    ...input,
+    raw: {},
+    filtered: {},
+    rawGeneration: 0,
+    filteredGeneration: 0,
+    lkg: true,
+  };
+}
+
+export function beginProbeIblUpdate(output: ProbeIblOutput): ProbeIblUpdate {
+  return {
+    ...output,
+    stages: REFLECTION_PROBE_IBL_STAGES,
+    nextStage: 'raw',
+    candidateGeneration: output.filteredGeneration + 1,
+  };
+}
+
+export function publishProbeIblOutput(
+  update: ProbeIblUpdate,
+  result: { readonly stage: ReflectionProbeIblStage; readonly ok: boolean },
+): ProbeIblOutput {
+  if (!result.ok || result.stage !== update.nextStage) return update;
+  if (result.stage === 'raw') {
+    return {
+      ...update,
+      rawGeneration: update.candidateGeneration,
+    };
+  }
+  if (result.stage === 'filtered') return update;
+  return {
+    ...update,
+    filteredGeneration: update.candidateGeneration,
+    lkg: true,
+  };
+}
+
+export function resetIblKernelCaches(): void {
+  kernelCaches.clear();
+}