@forgeax/engine-render 0.1.28 → 0.1.30

package/src/gpu-driven/view-gpu.ts

@@ -26,6 +26,7 @@ import {
 } from '../gpu-usage';
 import type { PipelineBuilderShaderModuleFactory } from '../pipeline-builder';
 import type { GpuDrivenCandidate, SubmissionPlan } from './batch-topology';
+import { GPU_DRIVEN_SKIN_FLAG } from './batch-topology';
 
 const COMPUTE_STAGE = 0x4;
 const WORKGROUP_SIZE = 64;
@@ -94,9 +95,10 @@ struct CandidateRecord {
   batchIndex: u32,
   visibleBase: u32,
   visibleCapacity: u32,
-  // Admission is separate from selector membership: suppressed candidates
-  // still contribute to the all-candidate LOD histogram, but never enter the
-  // compacted visible stream.
+  // Low bit is admission; upper bits carry the batch-local projected Mesh row.
+  // Suppressed candidates still contribute to the all-candidate LOD histogram,
+  // but never enter the compacted visible stream. Packing both facts here
+  // keeps the candidate ABI single-source when visibility compacts rows.
   submitAdmission: u32,
   projectedHeight: f32,
   previousLevel: u32,
@@ -232,7 +234,7 @@ fn cullView(@builtin(global_invocation_id) id: vec3<u32>) {
   // candidates outside the frustum and candidates suppressed by the CPU
   // visibility facet. Submission counters below remain compacted draw facts.
   atomicAdd(&counters[lodCounterIndex(candidate.batchIndex, selectedLod)], 1u);
-  if (candidate.submitAdmission == 0u) { return; }
+  if ((candidate.submitAdmission & 1u) == 0u) { return; }
   if (!isVisible(primitive, world)) { return; }
   atomicAdd(
     &counters[counterIndex(candidate.batchIndex) + ${GEOMETRY_WORK_COUNTER_OFFSET}u],
@@ -247,9 +249,13 @@ fn cullView(@builtin(global_invocation_id) id: vec3<u32>) {
     atomicStore(&counters[overflowIndex(candidate.batchIndex)], 1u);
     return;
   }
+  var materialOrPalette = primitive.materialIndex + (candidate.materialSlot & 0x7fffffffu);
+  if ((candidate.materialSlot & 0x80000000u) != 0u) {
+    materialOrPalette = instance.customDataStart;
+  }
   visibleIndices[candidate.visibleBase + localVisible] = vec2<u32>(
-    instanceIndex,
-    primitive.materialIndex + candidate.materialSlot,
+    candidate.submitAdmission >> 1u,
+    materialOrPalette,
   );
 }
 
@@ -258,10 +264,16 @@ fn finalizeView(@builtin(global_invocation_id) id: vec3<u32>) {
   let batchIndex = id.x;
   if (batchIndex >= view.batchCount) { return; }
   let batch = batches[batchIndex];
-  let visibleCount = min(
+  var visibleCount = min(
     atomicLoad(&counters[counterIndex(batchIndex)]),
     batch.visibleCapacity,
   );
+  // Overflow is a failed generation, never a partially valid draw. Keep the
+  // telemetry flag for the producer retry path but emit zero instances so no
+  // subset of a visible batch reaches the rasterizer.
+  if (atomicLoad(&counters[overflowIndex(batchIndex)]) != 0u) {
+    visibleCount = 0u;
+  }
   let args = batch.indirectIndex * 5u;
   let candidate = candidates[batch.candidateBase];
   let selectedLod = selectLodLevel(candidate.projectedHeight, candidate.previousLevel, candidate.historyValid != 0u, candidate.lodRows, candidate.lodCount);
@@ -286,6 +298,12 @@ interface ViewBuffers {
 
 type MutableViewBuffers = { -readonly [Name in keyof ViewBuffers]: ViewBuffers[Name] };
 
+type LodTelemetryCopy = {
+  readonly buffers: ViewBuffers;
+  readonly plan: SubmissionPlan;
+  readonly resourceGeneration: number;
+};
+
 export interface GpuDrivenViewGraphResources {
   readonly primitive: GraphBuffer;
   readonly instance: GraphBuffer;
@@ -329,12 +347,15 @@ export interface GpuDrivenLodSelectionInspection {
   readonly indirectDrawCount: number;
   readonly visible: number;
   readonly occluded: number;
+  /** True when the selector had to reject or clamp a visible candidate. */
+  readonly overflow: boolean;
   readonly lodHistogram: readonly { readonly level: number; readonly count: number }[];
   readonly batches: readonly {
     readonly batchId: number;
     readonly candidateCount: number;
     readonly visible: number;
     readonly occluded: number;
+    readonly overflow: boolean;
     readonly lodHistogram: readonly { readonly level: number; readonly count: number }[];
   }[];
   readonly worldSelections?: readonly {
@@ -408,7 +429,14 @@ export class GpuDrivenView {
   private bindGroupCreates = 0;
   private bufferRebuilds = 0;
   private resourceGeneration = 0;
-  private telemetryPending = false;
+  /** The last readback copy that was actually encoded and is not consumed. */
+  private telemetryPending: LodTelemetryCopy | undefined;
+  /** Coalesce observers while the readback buffer is map-pending. */
+  private lodSelectionReadback:
+    | {
+        readonly promise: Promise<GpuDrivenLodSelectionInspection | undefined>;
+      }
+    | undefined;
   private lodSelection: GpuDrivenLodSelectionInspection | undefined;
 
   private constructor(
@@ -418,13 +446,16 @@ export class GpuDrivenView {
     private readonly resetPipeline: ComputePipeline,
     private readonly cullPipeline: ComputePipeline,
     private readonly finalizePipeline: ComputePipeline,
+    private readonly labelPrefix: string,
   ) {}
 
   static create(input: {
     readonly device: RhiDevice;
     readonly shaderModuleFactory: PipelineBuilderShaderModuleFactory;
+    readonly labelPrefix?: string;
   }): Result<GpuDrivenView, RhiError> {
     const { device, shaderModuleFactory } = input;
+    const labelPrefix = input.labelPrefix ?? 'gpu-driven-view';
     if (!device.caps.compute || !device.caps.storageBuffer || !device.caps.indirectDrawing) {
       return err(
         new RhiError({
@@ -435,7 +466,7 @@ export class GpuDrivenView {
       );
     }
     const layout = device.createBindGroupLayout({
-      label: 'gpu-driven-view-bgl',
+      label: `${labelPrefix}-bgl`,
       entries: [
         { binding: 0, visibility: COMPUTE_STAGE, buffer: { type: 'read-only-storage' } },
         { binding: 1, visibility: COMPUTE_STAGE, buffer: { type: 'read-only-storage' } },
@@ -450,7 +481,7 @@ export class GpuDrivenView {
     });
     if (!layout.ok) return layout;
     const pipelineLayout = device.createPipelineLayout({
-      label: 'gpu-driven-view-pl',
+      label: `${labelPrefix}-pl`,
       bindGroupLayouts: [layout.value],
     });
     if (!pipelineLayout.ok) return pipelineLayout;
@@ -461,7 +492,7 @@ export class GpuDrivenView {
     if (!module.ok) return module;
     const createPipeline = (entryPoint: string): Result<ComputePipeline, RhiError> =>
       device.createComputePipeline({
-        label: `gpu-driven-view.${entryPoint}`,
+        label: `${labelPrefix}.${entryPoint}`,
         layout: pipelineLayout.value,
         compute: { module: module.value, entryPoint },
       });
@@ -479,6 +510,7 @@ export class GpuDrivenView {
         reset.value,
         cull.value,
         finalize.value,
+        labelPrefix,
       ),
     );
   }
@@ -488,11 +520,10 @@ export class GpuDrivenView {
     this.batchUploadBytes = 0;
     this.viewConstantsUploadBytes = 0;
     this.bindGroupCreates = 0;
-    // The readback copy is part of the accepted graph and therefore executes
-    // every submitted frame, not only when that graph is (re)compiled.  Keep
-    // the observation latch armed across per-frame view updates; clearing it
-    // here would make a cached graph silently discard all later LOD samples.
-    this.telemetryPending = true;
+    // The cached graph owns the readback copy.  Do not arm an observation latch
+    // here: a graph can be compiled but not submitted, and its copy can be
+    // skipped while the previous mapAsync is pending.  The encode callback
+    // records only a copy that really reached the command encoder.
     this.lodSelection = undefined;
     const topologyChanged = this.plan !== plan;
     let buffersRebuilt = false;
@@ -540,13 +571,19 @@ export class GpuDrivenView {
         batches.setUint32(batchOffset + 20, batch.batchId, true);
         batches.setUint32(batchOffset + 24, batch.key.drawKind === 'indexed' ? 1 : 0, true);
         batches.setUint32(batchOffset + 28, candidateIndex, true);
+        let visibleProjectionIndex = 0;
         for (const candidate of batch.candidates) {
           const admissionCandidate = candidate as GpuDrivenAdmissionCandidate;
           const candidateOffset = candidateIndex * CANDIDATE_STRIDE;
           candidates.setUint32(candidateOffset, candidate.primitiveIndex, true);
           candidates.setUint32(candidateOffset + 4, candidate.generation, true);
           candidates.setUint32(candidateOffset + 8, candidate.instanceOrdinal, true);
-          candidates.setUint32(candidateOffset + 12, batch.key.materialSlot, true);
+          const isSkin = candidate.prepared?.identity.deformation === 'skin';
+          candidates.setUint32(
+            candidateOffset + 12,
+            batch.key.materialSlot | (isSkin ? GPU_DRIVEN_SKIN_FLAG : 0),
+            true,
+          );
           candidates.setUint32(candidateOffset + 16, batchIndex, true);
           candidates.setUint32(candidateOffset + 20, batch.visibleBase, true);
           candidates.setUint32(candidateOffset + 24, batch.visibleCapacity, true);
@@ -556,9 +593,10 @@ export class GpuDrivenView {
             ...(candidate.lodRanges ?? []),
           ];
           const lodCount = Math.min(LOD_ROW_CAPACITY, Math.max(1, coverages.length, ranges.length));
+          const admitted = admissionCandidate.submitAdmission !== false;
           candidates.setUint32(
             candidateOffset + 28,
-            admissionCandidate.submitAdmission === false ? 0 : 1,
+            (visibleProjectionIndex << 1) | (admitted ? 1 : 0),
             true,
           );
           candidates.setFloat32(
@@ -584,6 +622,7 @@ export class GpuDrivenView {
             candidates.setFloat32(rowOffset + 24, candidate.lodHysteresis ?? 0.08, true);
             candidates.setUint32(rowOffset + 28, 1, true);
           }
+          if (admitted) visibleProjectionIndex += 1;
           candidateIndex += 1;
         }
       }
@@ -620,7 +659,7 @@ export class GpuDrivenView {
       this.sceneMaterial !== scene.materialBuffer;
     if (this.bindGroup === undefined || sceneChanged || buffersRebuilt) {
       const binding = this.device.createBindGroup({
-        label: 'gpu-driven-view-bg',
+        label: `${this.labelPrefix}-bg`,
         layout: this.bindGroupLayout,
         entries: [
           { binding: 0, resource: bufferBinding(scene.primitiveBuffer) },
@@ -687,13 +726,37 @@ export class GpuDrivenView {
   }
 
   /** Read selected levels written by the GPU cull pass for the last submit. */
-  async readLodSelection(): Promise<GpuDrivenLodSelectionInspection | undefined> {
+  readLodSelection(): Promise<GpuDrivenLodSelectionInspection | undefined> {
+    const inFlight = this.lodSelectionReadback;
+    if (inFlight !== undefined) return inFlight.promise;
+
     const buffers = this.buffers;
     const plan = this.plan;
-    if (buffers === undefined || plan === undefined || !this.telemetryPending) {
-      return this.lodSelection;
+    const copy = this.telemetryPending;
+    if (
+      buffers === undefined ||
+      plan === undefined ||
+      copy === undefined ||
+      copy.buffers !== buffers ||
+      copy.plan !== plan ||
+      copy.resourceGeneration !== this.resourceGeneration ||
+      typeof buffers.lodReadback.mapAsync !== 'function' ||
+      buffers.lodReadback.mapState !== 'unmapped'
+    ) {
+      return Promise.resolve(this.lodSelection);
     }
-    this.telemetryPending = false;
+    const promise = this.readLodSelectionCopy(buffers, plan, copy).finally(() => {
+      if (this.lodSelectionReadback?.promise === promise) this.lodSelectionReadback = undefined;
+    });
+    this.lodSelectionReadback = { promise };
+    return promise;
+  }
+
+  private async readLodSelectionCopy(
+    buffers: ViewBuffers,
+    plan: SubmissionPlan,
+    copy: LodTelemetryCopy,
+  ): Promise<GpuDrivenLodSelectionInspection | undefined> {
     const mapped = await buffers.lodReadback.mapAsync(GPU_BUFFER_USAGE_MAP_READ);
     if (!mapped.ok) return undefined;
     const range = mapped.value.getMappedRange();
@@ -704,12 +767,21 @@ export class GpuDrivenView {
     try {
       const values = new DataView(range.value);
       let visible = 0;
+      let overflow = false;
       let geometryWork = 0;
       let rootGeometryWork = 0;
       const histogram = new Map<number, number>();
       for (let batchIndex = 0; batchIndex < plan.batches.length; batchIndex += 1) {
         const offset = batchIndex * COUNTER_STRIDE;
-        visible += values.getUint32(offset, true);
+        const batchOverflow = values.getUint32(offset + 4, true) !== 0;
+        const batchVisible = batchOverflow
+          ? 0
+          : Math.min(
+              values.getUint32(offset, true),
+              plan.batches[batchIndex]?.visibleCapacity ?? 0,
+            );
+        visible += batchVisible;
+        overflow ||= batchOverflow;
         geometryWork += values.getUint32(offset + GEOMETRY_WORK_COUNTER_OFFSET * 4, true);
         rootGeometryWork += values.getUint32(offset + ROOT_GEOMETRY_WORK_COUNTER_OFFSET * 4, true);
         for (let level = 0; level < LOD_ROW_CAPACITY; level += 1) {
@@ -717,6 +789,16 @@ export class GpuDrivenView {
           if (count > 0) histogram.set(level, (histogram.get(level) ?? 0) + count);
         }
       }
+      // A topology/resource replacement may have happened while mapAsync was
+      // pending. Never publish those counters into the new plan/cache.
+      if (
+        this.buffers !== buffers ||
+        this.plan !== plan ||
+        this.resourceGeneration !== copy.resourceGeneration ||
+        this.telemetryPending !== copy
+      ) {
+        return undefined;
+      }
       const candidateCount = plan.candidateCount;
       this.lodSelection = Object.freeze({
         candidateCount,
@@ -732,6 +814,7 @@ export class GpuDrivenView {
         // histogram here would mislabel a visible candidate dropped only by an
         // indirect-capacity overflow as occluded.
         occluded: Math.max(0, candidateCount - visible),
+        overflow,
         lodHistogram: Object.freeze(
           [...histogram.entries()]
             .sort(([left], [right]) => left - right)
@@ -745,12 +828,16 @@ export class GpuDrivenView {
               const count = values.getUint32(offset + (2 + level) * 4, true);
               if (count > 0) batchHistogram.set(level, count);
             }
-            const batchVisible = values.getUint32(offset, true);
+            const batchOverflow = values.getUint32(offset + 4, true) !== 0;
+            const batchVisible = batchOverflow
+              ? 0
+              : Math.min(values.getUint32(offset, true), batch.visibleCapacity);
             return Object.freeze({
               batchId: batch.batchId,
               candidateCount: batch.candidates.length,
               visible: batchVisible,
               occluded: Math.max(0, batch.candidates.length - batchVisible),
+              overflow: batchOverflow,
               lodHistogram: Object.freeze(
                 [...batchHistogram.entries()]
                   .sort(([left], [right]) => left - right)
@@ -762,6 +849,7 @@ export class GpuDrivenView {
         geometryWork,
         rootGeometryWork,
       });
+      this.telemetryPending = undefined;
       return this.lodSelection;
     } finally {
       mapped.value.unmap();
@@ -770,6 +858,8 @@ export class GpuDrivenView {
 
   addPasses<FrameCtx extends RenderGraphFrame>(
     builder: RenderGraphBuilder<FrameCtx>,
+    labelPrefix = 'gpu-driven',
+    includeCompute = true,
   ): Result<GpuDrivenViewGraphResources, RenderGraphError> {
     const buffers = this.buffers;
     const bindGroup = this.bindGroup;
@@ -791,84 +881,96 @@ export class GpuDrivenView {
     }
     const importBuffer = (name: string, buffer: Buffer, size: number, usage: number) =>
       builder.importBuffer(name, { size, usage }, () => buffer);
+    const scenePrefix = labelPrefix === 'gpu-driven' ? 'gpu-scene' : `${labelPrefix}.scene`;
     const primitive = importBuffer(
-      'gpu-scene.primitive',
+      `${scenePrefix}.primitive`,
       this.scenePrimitive as Buffer,
       this.sceneCapacity * GPU_SCENE_LAYOUTS.primitive.stride,
       GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST | GPU_BUFFER_USAGE_COPY_SRC,
     );
     if (!primitive.ok) return primitive;
     const transform = importBuffer(
-      'gpu-scene.transform',
+      `${scenePrefix}.transform`,
       this.sceneTransform as Buffer,
       this.sceneCapacity * GPU_SCENE_LAYOUTS.transform.stride,
       GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST | GPU_BUFFER_USAGE_COPY_SRC,
     );
     if (!transform.ok) return transform;
     const instance = importBuffer(
-      'gpu-scene.instance',
+      `${scenePrefix}.instance`,
       this.sceneInstance as Buffer,
       this.sceneCapacity * GPU_SCENE_LAYOUTS.instance.stride,
       GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST | GPU_BUFFER_USAGE_COPY_SRC,
     );
     if (!instance.ok) return instance;
     const material = importBuffer(
-      'gpu-scene.material',
+      `${scenePrefix}.material`,
       this.sceneMaterial as Buffer,
       this.sceneCapacity * GPU_SCENE_LAYOUTS.material.stride,
       GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST | GPU_BUFFER_USAGE_COPY_SRC,
     );
     if (!material.ok) return material;
     const candidates = importBuffer(
-      'gpu-driven.candidates',
+      `${labelPrefix}.candidates`,
       buffers.candidates,
       this.candidateCapacity * CANDIDATE_STRIDE,
       GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST,
     );
     if (!candidates.ok) return candidates;
     const batches = importBuffer(
-      'gpu-driven.batches',
+      `${labelPrefix}.batches`,
       buffers.batches,
       this.batchCapacity * BATCH_STRIDE,
       GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST,
     );
     if (!batches.ok) return batches;
     const view = importBuffer(
-      'gpu-driven.view',
+      `${labelPrefix}.view`,
       buffers.view,
       VIEW_BYTES,
       GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
     );
     if (!view.ok) return view;
     const counters = importBuffer(
-      'gpu-driven.counters',
+      `${labelPrefix}.counters`,
       buffers.counters,
       this.batchCapacity * COUNTER_STRIDE,
       GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_SRC,
     );
     if (!counters.ok) return counters;
     const lodReadback = importBuffer(
-      'gpu-driven.lod-selection-readback',
+      `${labelPrefix}.lod-selection-readback`,
       buffers.lodReadback,
       this.batchCapacity * COUNTER_STRIDE,
       GPU_BUFFER_USAGE_MAP_READ | GPU_BUFFER_USAGE_COPY_DST,
     );
     if (!lodReadback.ok) return lodReadback;
     const visible = importBuffer(
-      'gpu-driven.visible',
+      `${labelPrefix}.visible`,
       buffers.visible,
       this.visibleBufferCapacity * 8,
       GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_SRC,
     );
     if (!visible.ok) return visible;
     const indirect = importBuffer(
-      'gpu-driven.indirect',
+      `${labelPrefix}.indirect`,
       buffers.indirect,
       this.indirectCapacity * 20,
       GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_INDIRECT | GPU_BUFFER_USAGE_COPY_SRC,
     );
     if (!indirect.ok) return indirect;
-    const reset = builder.addComputePass('gpu-driven.view-reset', {
+    if (!includeCompute) {
+      return ok({
+        visible: visible.value,
+        primitive: primitive.value,
+        instance: instance.value,
+        transform: transform.value,
+        material: material.value,
+        indirect: indirect.value,
+        overflow: counters.value,
+      });
+    }
+    const reset = builder.addComputePass(`${labelPrefix}.view-reset`, {
       accesses: [
         { resource: view.value, usage: 'uniform-read' },
         { resource: counters.value, usage: 'storage-read-write' },
@@ -880,7 +982,7 @@ export class GpuDrivenView {
       },
     });
     if (!reset.ok) return reset;
-    const cull = builder.addComputePass('gpu-driven.frustum-compact', {
+    const cull = builder.addComputePass(`${labelPrefix}.frustum-compact`, {
       accesses: [
         { resource: primitive.value, usage: 'storage-read' },
         { resource: instance.value, usage: 'storage-read' },
@@ -897,7 +999,7 @@ export class GpuDrivenView {
       },
     });
     if (!cull.ok) return cull;
-    const finalize = builder.addComputePass('gpu-driven.finalize-indirect', {
+    const finalize = builder.addComputePass(`${labelPrefix}.finalize-indirect`, {
       accesses: [
         { resource: batches.value, usage: 'storage-read' },
         { resource: view.value, usage: 'uniform-read' },
@@ -911,21 +1013,46 @@ export class GpuDrivenView {
       },
     });
     if (!finalize.ok) return finalize;
-    const readback = builder.addCopyPass('gpu-driven.lod-selection-readback', {
+    const graphResourceGeneration = this.resourceGeneration;
+    const readback = builder.addCopyPass(`${labelPrefix}.lod-selection-readback`, {
       accesses: [
         { resource: counters.value, usage: 'copy-src' },
         { resource: lodReadback.value, usage: 'copy-dst' },
       ],
       encode: ({ encoder, resources }) => {
+        // A cached graph may run while an observer is awaiting mapAsync on the
+        // previous copy. WebGPU forbids submitting a copy into a
+        // pending/mapped buffer; skip only this telemetry copy and keep the
+        // raster/indirect work intact. RhiNull has no runtime mapState, so its
+        // undefined value remains structurally executable.
+        const mapState = buffers.lodReadback.mapState;
+        if (mapState !== undefined && mapState !== 'unmapped') return;
         encoder.copyBufferToBuffer(
           resources.buffer(counters.value).unwrap(),
           resources.buffer(lodReadback.value).unwrap(),
           this.batchCapacity * COUNTER_STRIDE,
         );
+        // The render graph is cached across camera-only LOD projection
+        // changes. The pass closure therefore retains the graph-generation
+        // plan while `this.plan` carries the plan uploaded for the frame that
+        // is actually being submitted. Counters belong to that current plan;
+        // retaining the stale closure plan would make every observation fail
+        // the identity fence and silently leave the CPU level-0 placeholder.
+        const submittedPlan = this.plan;
+        if (
+          this.buffers === buffers &&
+          submittedPlan !== undefined &&
+          this.resourceGeneration === graphResourceGeneration
+        ) {
+          this.telemetryPending = {
+            buffers,
+            plan: submittedPlan,
+            resourceGeneration: graphResourceGeneration,
+          };
+        }
       },
     });
     if (!readback.ok) return readback;
-    this.telemetryPending = true;
     return ok({
       visible: visible.value,
       primitive: primitive.value,
@@ -952,6 +1079,9 @@ export class GpuDrivenView {
     this.sceneTransform = undefined;
     this.sceneMaterial = undefined;
     this.sceneCapacity = 0;
+    this.telemetryPending = undefined;
+    this.lodSelectionReadback = undefined;
+    this.lodSelection = undefined;
     this.destroyAfterSubmittedWork(buffers);
     void this.pipelineLayout;
   }
@@ -969,6 +1099,22 @@ export class GpuDrivenView {
     this.destroyAfterSubmittedWork(buffers);
   }
 
+  /**
+   * @internal
+   * Grow every view buffer after a GPU overflow was observed. The next
+   * `update` rewrites the same plan into the replacement generation, so the
+   * failed generation cannot be reused even when topology identity is stable.
+   */
+  _recoverFromOverflow(): Result<void, RhiError> {
+    if (this.buffers === undefined) return ok(undefined);
+    return this.rebuildBuffers(
+      this.candidateCapacity * 2,
+      this.visibleBufferCapacity * 2,
+      this.batchCapacity * 2,
+      this.indirectCapacity * 2,
+    );
+  }
+
   private rebuildBuffers(
     candidateCapacity: number,
     visibleCapacity: number,
@@ -1067,6 +1213,7 @@ export class GpuDrivenView {
     this.indirectCapacity = nextIndirect;
     this.bufferRebuilds += 1;
     this.bindGroup = undefined;
+    this.telemetryPending = undefined;
     return ok(undefined);
   }
 

package/src/gpu-resource.ts

@@ -52,6 +52,7 @@
 //     introduced in feat-20260612 M1 / w1).
 
 import type { Buffer, Result, RhiDevice, RhiError, Texture } from '@forgeax/engine-rhi';
+import type { DeviceScope } from './device/device-scope';
 
 /**
  * Runtime wrapper around an RHI `Buffer` opaque handle that exposes
@@ -81,10 +82,17 @@ export class GpuBuffer {
   // BUFFER_META_MAP. This local flag is a derived view written only on
   // the success branch of `device.destroyBuffer(...)`; charter §F1.
   private destroyed = false;
+  private releaseScope: (() => void) | undefined;
 
-  constructor(device: RhiDevice, handle: Buffer) {
+  constructor(device: RhiDevice, handle: Buffer, scope?: DeviceScope) {
     this.device = device;
     this.handle = handle;
+    if (scope !== undefined) {
+      const ref = scope._adopt('buffer', this, (value) => {
+        if (!value.isDestroyed) value.destroy();
+      });
+      this.releaseScope = () => scope._release(ref);
+    }
   }
 
   get isDestroyed(): boolean {
@@ -101,6 +109,8 @@ export class GpuBuffer {
     const r = this.device.destroyBuffer(this.handle);
     if (r.ok) {
       this.destroyed = true;
+      this.releaseScope?.();
+      this.releaseScope = undefined;
     }
     return r;
   }
@@ -126,10 +136,17 @@ export class GpuTexture {
   readonly device: RhiDevice;
   readonly handle: Texture;
   private destroyed = false;
+  private releaseScope: (() => void) | undefined;
 
-  constructor(device: RhiDevice, handle: Texture) {
+  constructor(device: RhiDevice, handle: Texture, scope?: DeviceScope) {
     this.device = device;
     this.handle = handle;
+    if (scope !== undefined) {
+      const ref = scope._adopt('texture', this, (value) => {
+        if (!value.isDestroyed) value.destroy();
+      });
+      this.releaseScope = () => scope._release(ref);
+    }
   }
 
   get isDestroyed(): boolean {
@@ -144,6 +161,8 @@ export class GpuTexture {
     const r = this.device.destroyTexture(this.handle);
     if (r.ok) {
       this.destroyed = true;
+      this.releaseScope?.();
+      this.releaseScope = undefined;
     }
     return r;
   }