@forgeax/engine-render 0.1.27 → 0.1.29

package/src/device/gpu-residency.ts

@@ -1,3 +1,4 @@
+import { type MeshResidencyLease, MeshResidencyLifetime } from './mesh-residency-lifetime';
 // @forgeax/engine-runtime - GpuResidencyCache
 // (feat-20260601-device/gpu-residency-extraction M1; M2 added the deriveRenderData
 // projection seam — see render-data.ts).
@@ -37,10 +38,7 @@ import {
   prepareMipmaps,
 } from '@forgeax/engine-assets-runtime';
 import type { World } from '@forgeax/engine-ecs';
-import {
-  PROCEDURAL_FLOATS_PER_VERTEX,
-  type VertexLayoutProjection,
-} from '@forgeax/engine-geometry';
+import { deriveVertexCount, type VertexLayoutProjection } from '@forgeax/engine-geometry';
 import { halfFloat } from '@forgeax/engine-math';
 import {
   type Buffer,
@@ -100,7 +98,6 @@ import {
   runIblPrecompute,
 } from '../ibl/IblPipelineCache';
 import type { RhiErrorListenerRegistry } from '../lifecycle';
-import type { RecoveryColdWorkGuard } from '../record/render-context';
 import {
   type CubeRenderData,
   deriveRenderDataCubemap,
@@ -371,6 +368,23 @@ function packMeshLodGeometry(
     }
     lowerData.push(projected.value);
   }
+  if (
+    deriveVertexCount(root.vertices, rootData.layoutProjection) === undefined ||
+    lowerMeshes.some((mesh, index) => {
+      const data = lowerData[index];
+      return (
+        data === undefined || deriveVertexCount(mesh.vertices, data.layoutProjection) === undefined
+      );
+    })
+  ) {
+    return err(
+      new RhiError({
+        code: 'asset-not-registered',
+        expected: 'every MeshAsset LOD vertex byte length to match its layout projection stride',
+        hint: 'reimport the LOD chain so interleaved vertex bytes match attributes',
+      }),
+    );
+  }
   if (
     lowerData.some(
       (data) =>
@@ -478,14 +492,6 @@ export interface MeshGpuHandles {
   readonly iboBytes: number;
   readonly indexCount: number;
   readonly indexFormat: 'uint16' | 'uint32';
-  /**
-   * Vertex stride discriminator (feat-20260611). `'12F'` = 48 B
-   * (position+normal+uv+tangent); `'18F'` = 72 B (12F + skinIndex(uint16x4) +
-   * skinWeight(float32x4)). Mirrors `MeshRenderData.layout` in render-data.ts
-   * and `MeshRenderData.layout` -- the residency and render-data layout
-   * fields are the same union and move together.
-   */
-  readonly layout: '12F' | '18F';
   /** Geometry-owned vertex layout projection used by every GPU consumer. */
   readonly layoutProjection: VertexLayoutProjection;
   /**
@@ -496,7 +502,7 @@ export interface MeshGpuHandles {
    * MeshRenderData.uvSetCount.
    */
   readonly uvSetCount: number;
-  /** Vertex count uses 18F for skin or the geometry-owned canonical base stride. */
+  /** Vertex count derived from the geometry-owned layout projection. */
   readonly vertexCount: number;
   /** True when `MeshAsset.indices` is present (indexed draw path). */
   readonly indexed: boolean;
@@ -546,7 +552,6 @@ export class GpuResidencyCache {
   // Hardware-probe caps injected at `configureGpuDevice`; guards the HDR cubemap
   // path (_uploadCubemapFromEquirect) when `rgba16floatRenderable` is false.
   private caps: RhiCaps | undefined = undefined;
-  private recoveryColdWorkGuard: RecoveryColdWorkGuard | undefined;
   private deviceEpoch = 0;
   private textureGeneration = 0;
 
@@ -557,6 +562,36 @@ export class GpuResidencyCache {
   // equirect source always resolves to the same cubemap (idempotent, A2).
   private readonly cubemapIdempotentMap: Map<number, Handle<'EquirectAsset', 'shared'>> = new Map();
   private readonly meshGpuHandles: Map<string | number, MeshGpuHandles> = new Map();
+  private readonly meshLifetimes = new WeakMap<MeshGpuHandles, MeshResidencyLifetime>();
+  private readonly retiredMeshes = new Set<MeshGpuHandles>();
+
+  private meshLifetime(entry: MeshGpuHandles): MeshResidencyLifetime {
+    let lifetime = this.meshLifetimes.get(entry);
+    if (lifetime === undefined) {
+      lifetime = new MeshResidencyLifetime(() => {
+        if (!entry.vertexBuffer.isDestroyed) entry.vertexBuffer.destroy();
+        if (entry.indexBuffer !== null && !entry.indexBuffer.isDestroyed)
+          entry.indexBuffer.destroy();
+        this.retiredMeshes.delete(entry);
+      });
+      this.meshLifetimes.set(entry, lifetime);
+    }
+    return lifetime;
+  }
+
+  /** All resident entries conservatively cover main, shadow and cached GPU-driven draws. */
+  trackMeshSubmission(completed: Promise<unknown>): void {
+    for (const entry of this.meshGpuHandles.values()) this.meshLifetime(entry).track(completed);
+  }
+
+  private retireMeshEntry(key: string | number, entry: MeshGpuHandles): void {
+    if (this.meshGpuHandles.get(key) === entry) {
+      this.meshGpuHandles.delete(key);
+      this.meshResidencyEpoch += 1;
+    }
+    this.retiredMeshes.add(entry);
+    this.meshLifetime(entry).retire();
+  }
 
   /**
    * Compose a cache key from the raw handle slot and its owning World. The
@@ -626,9 +661,6 @@ export class GpuResidencyCache {
   }
 
   /** Arm the first-published-frame assertion on this generation's store. */
-  setRecoveryColdWorkGuard(guard: RecoveryColdWorkGuard | undefined): void {
-    this.recoveryColdWorkGuard = guard;
-  }
 
   /**
    * Wrap a raw RHI Buffer handle into a GpuBuffer. The wrapper holds a
@@ -711,11 +743,12 @@ export class GpuResidencyCache {
     this.cubemapGpuHandles.clear();
     this.cubemapIdempotentMap.clear();
 
-    for (const entry of this.meshGpuHandles.values()) {
+    for (const entry of [...this.meshGpuHandles.values(), ...this.retiredMeshes]) {
       destroyBuf(entry.vertexBuffer);
       if (entry.indexBuffer !== null) destroyBuf(entry.indexBuffer);
     }
     this.meshGpuHandles.clear();
+    this.retiredMeshes.clear();
   }
 
   /** Number of candidate-owned GPU resources currently held by this cache. */
@@ -730,6 +763,7 @@ export class GpuResidencyCache {
     }
     return (
       this.meshGpuHandles.size +
+      this.retiredMeshes.size +
       this.textureGpuHandles.size +
       this.samplerGpuHandles.size +
       cubemapResources
@@ -802,27 +836,13 @@ export class GpuResidencyCache {
     const entry = this.meshGpuHandles.get(id);
     if (entry === undefined) return { freed: 0, errors: [] };
 
-    let freed = 0;
-    const errors: RhiError[] = [];
-
-    const destroyBuf = (gpuBuf: GpuBuffer): void => {
-      if (!gpuBuf.isDestroyed) {
-        const r = gpuBuf.destroy();
-        if (r.ok) {
-          freed += 1;
-        } else {
-          errors.push(r.error);
-          if (this.errorRegistry) this.errorRegistry.fire(r.error);
-        }
-      }
+    if (this.meshLifetime(entry).owners > 0) return { freed: 0, errors: [] };
+    this.retireMeshEntry(id, entry);
+    return {
+      freed:
+        Number(entry.vertexBuffer.isDestroyed) + Number(entry.indexBuffer?.isDestroyed ?? false),
+      errors: [],
     };
-
-    destroyBuf(entry.vertexBuffer);
-    if (entry.indexBuffer !== null) destroyBuf(entry.indexBuffer);
-
-    this.meshGpuHandles.delete(id);
-    this.meshResidencyEpoch += 1;
-    return { freed: freed > 0 ? 1 : 0, errors };
   }
 
   evictCubemap(id: number): { freed: number; errors: RhiError[] } {
@@ -862,7 +882,6 @@ export class GpuResidencyCache {
   releaseUnreferenced(liveSet: Set<number>): { freed: number; errors: RhiError[] } {
     let freed = 0;
     const errors: RhiError[] = [];
-    let meshResidencyChanged = false;
     let materialResidencyChanged = false;
     const liveSlots = new Set([...liveSet].map((slot) => String(slot)));
     const isLiveKey = (key: string | number): boolean => {
@@ -916,35 +935,14 @@ export class GpuResidencyCache {
       }
     }
 
-    for (const key of this.meshGpuHandles.keys()) {
-      if (!isLiveKey(key)) {
-        const entry = this.meshGpuHandles.get(key);
-        if (entry !== undefined) {
-          if (!entry.vertexBuffer.isDestroyed) {
-            const r = entry.vertexBuffer.destroy();
-            if (r.ok) {
-              freed += 1;
-            } else {
-              errors.push(r.error);
-              if (this.errorRegistry) this.errorRegistry.fire(r.error);
-            }
-          }
-          if (entry.indexBuffer !== null && !entry.indexBuffer.isDestroyed) {
-            const r = entry.indexBuffer.destroy();
-            if (r.ok) {
-              freed += 1;
-            } else {
-              errors.push(r.error);
-              if (this.errorRegistry) this.errorRegistry.fire(r.error);
-            }
-          }
-          this.meshGpuHandles.delete(key);
-          meshResidencyChanged = true;
-        }
+    for (const [key, entry] of this.meshGpuHandles) {
+      if (!isLiveKey(key) && this.meshLifetime(entry).owners === 0) {
+        this.retireMeshEntry(key, entry);
+        freed +=
+          Number(entry.vertexBuffer.isDestroyed) + Number(entry.indexBuffer?.isDestroyed ?? false);
       }
     }
 
-    if (meshResidencyChanged) this.meshResidencyEpoch += 1;
     if (materialResidencyChanged) this.materialResourceEpoch += 1;
 
     return { freed, errors };
@@ -1026,7 +1024,6 @@ export class GpuResidencyCache {
     const key = this.worldKey(handleSlot(handle), worldId);
     const existing = this.samplerGpuHandles.get(key);
     if (existing !== undefined) return ok(existing);
-    this.recoveryColdWorkGuard?.noteUploadColdWork();
     const device = this.gpuDevice;
     if (device === undefined) {
       return err(
@@ -1096,23 +1093,26 @@ export class GpuResidencyCache {
     return this.meshGpuHandles.get(this.worldKey(handleSlot(handle), worldId));
   }
 
-  /**
-   * Drop one mutable shared mesh's GPU copy after ECS publishes `markChanged`.
-   * The next record pass resolves the same POD and rebuilds residency through
-   * the normal pull path, so ECS remains the payload authority.
-   */
+  /** Candidate leases retain the concrete allocation even after cache invalidation. */
+  retainMeshResidency(
+    handle: Handle<'MeshAsset', 'shared'>,
+    worldId: World | number = 0,
+  ): MeshResidencyLease | undefined {
+    const key = this.worldKey(handleSlot(handle), worldId);
+    const entry = this.meshGpuHandles.get(key);
+    return entry === undefined
+      ? undefined
+      : this.meshLifetime(entry).retain(() => {
+          if (this.meshGpuHandles.get(key) === entry) this.invalidateMesh(handle, worldId);
+          else this.meshLifetime(entry).retire();
+        });
+  }
+
+  /** In-place author changes immediately miss the cache; old submissions keep their allocation. */
   invalidateMesh(handle: number, worldId: World | number = 0): void {
-    // SharedRefMutation publishes the encoded handle value, while the cache
-    // key is derived from the decoded slot. Keep the invalidation path aligned
-    // with getMeshGpuHandles/ensureResident so an in-place ECS payload change
-    // cannot leave the old VBO resident.
     const key = this.worldKey(handleSlot(toShared<'MeshAsset'>(handle)), worldId);
     const entry = this.meshGpuHandles.get(key);
-    if (entry === undefined) return;
-    entry.vertexBuffer.destroy();
-    if (entry.indexBuffer !== null) entry.indexBuffer.destroy();
-    this.meshGpuHandles.delete(key);
-    this.meshResidencyEpoch += 1;
+    if (entry !== undefined) this.retireMeshEntry(key, entry);
   }
 
   /**
@@ -1159,7 +1159,6 @@ export class GpuResidencyCache {
         const key = this.worldKey(id, worldId);
         const existing = this.meshGpuHandles.get(key);
         if (existing !== undefined) return ok(existing);
-        this.recoveryColdWorkGuard?.noteUploadColdWork();
         const projected = deriveRenderDataMesh(pod);
         if (!projected.ok) return projected;
         return this.uploadMeshById(key, pod, projected.value, lodMeshes);
@@ -1168,7 +1167,6 @@ export class GpuResidencyCache {
         const texKey = this.worldKey(id, worldId);
         const existing = this.textureGpuHandles.get(texKey);
         if (existing !== undefined) return ok(existing);
-        this.recoveryColdWorkGuard?.noteUploadColdWork();
         const projected = deriveRenderDataTexture(pod);
         if (!projected.ok) return projected;
         const decoded: DecodedImage = decodedFromTexture(pod);
@@ -2010,6 +2008,16 @@ export class GpuResidencyCache {
       );
     }
 
+    const vertexCount = deriveVertexCount(mesh.vertices, renderData.layoutProjection);
+    if (vertexCount === undefined) {
+      return err(
+        new RhiError({
+          code: 'asset-not-registered',
+          expected: 'MeshAsset.vertices byteLength to be divisible by its layout projection stride',
+          hint: 'reimport the mesh so the interleaved vertex bytes match attributes',
+        }),
+      );
+    }
     const packed = packMeshLodGeometry(mesh, renderData, lodMeshes);
     if (!packed.ok) return packed;
     const { vertices, indices, lodRanges } = packed.value;
@@ -2068,14 +2076,9 @@ export class GpuResidencyCache {
       iboBytes: indices === undefined ? 0 : indexBytes,
       indexCount: mesh.indices === undefined ? 0 : mesh.indices.length,
       indexFormat: indices instanceof Uint32Array ? 'uint32' : 'uint16',
-      layout: renderData.layoutProjection.attributes.some(
-        (attribute) => attribute.key === 'skinIndex' || attribute.key === 'skinWeight',
-      )
-        ? '18F'
-        : '12F',
       layoutProjection: renderData.layoutProjection,
       uvSetCount: 1 + extraUvSets,
-      vertexCount: mesh.vertices.byteLength / renderData.layoutProjection.arrayStride,
+      vertexCount,
       indexed: mesh.indices !== undefined,
       topology: renderData.submeshes[0]?.topology ?? 'triangle-list',
       submeshes: renderData.submeshes,
@@ -2102,6 +2105,8 @@ export class GpuResidencyCache {
     if (entry === undefined) return;
 
     const newVertexBytes = newVertices.byteLength;
+    const newVertexCount = deriveVertexCount(newVertices, entry.layoutProjection);
+    if (newVertexCount === undefined) return;
     const indexBytesUnpadded = newIndices.byteLength;
     const newIndexBytes = ((indexBytesUnpadded + 3) >> 2) << 2;
 
@@ -2131,10 +2136,9 @@ export class GpuResidencyCache {
         iboBytes: entry.iboBytes,
         indexCount: newIndices.length,
         indexFormat: 'uint16',
-        layout: '12F',
         layoutProjection: entry.layoutProjection,
         uvSetCount: entry.uvSetCount,
-        vertexCount: newVertices.length / PROCEDURAL_FLOATS_PER_VERTEX,
+        vertexCount: newVertexCount,
         indexed: true,
         topology: entry.topology,
         submeshes: nextSubmeshes,
@@ -2175,10 +2179,9 @@ export class GpuResidencyCache {
       iboBytes: newIndexBytes,
       indexCount: newIndices.length,
       indexFormat: 'uint16',
-      layout: '12F',
       layoutProjection: entry.layoutProjection,
       uvSetCount: entry.uvSetCount,
-      vertexCount: newVertices.length / PROCEDURAL_FLOATS_PER_VERTEX,
+      vertexCount: newVertexCount,
       indexed: true,
       topology: entry.topology,
       submeshes: nextSubmeshes,

package/src/device/mesh-residency-lifetime.ts

@@ -0,0 +1,73 @@
+/** A lease captures one GPU allocation, never a reusable World handle slot. */
+export interface MeshResidencyLease {
+  track(completed: Promise<unknown>): void;
+  release(evict: boolean): Promise<void> | undefined;
+}
+
+/** Shared candidates and queue submissions have one allocation lifetime owner. */
+export class MeshResidencyLifetime {
+  private leases = 0;
+  private retired = false;
+  private eviction: (() => void) | undefined;
+  private readonly submissions = new Set<Promise<unknown>>();
+  private readonly waiters = new Set<() => void>();
+
+  constructor(private destroy: (() => void) | undefined) {}
+
+  get owners(): number {
+    return this.leases;
+  }
+
+  retain(evict: () => void): MeshResidencyLease {
+    this.leases += 1;
+    this.eviction = undefined;
+    let released = false;
+    let completion: Promise<void> | undefined;
+    return {
+      track: (submitted) => this.track(submitted),
+      release: (shouldEvict) => {
+        if (released) return completion;
+        released = true;
+        this.leases -= 1;
+        if (this.leases === 0 && shouldEvict) this.eviction = evict;
+        completion =
+          this.submissions.size === 0
+            ? undefined
+            : new Promise<void>((resolve) => this.waiters.add(resolve));
+        this.flush();
+        return completion;
+      },
+    };
+  }
+
+  track(completed: Promise<unknown>): void {
+    if (this.submissions.has(completed)) return;
+    this.submissions.add(completed);
+    const finish = (): void => {
+      this.submissions.delete(completed);
+      this.flush();
+    };
+    void completed.then(finish, finish);
+  }
+
+  retire(): void {
+    this.retired = true;
+    this.flush();
+  }
+
+  private flush(): void {
+    if (this.submissions.size !== 0) return;
+    if (this.leases === 0 && this.eviction !== undefined) {
+      const evict = this.eviction;
+      this.eviction = undefined;
+      evict();
+    }
+    if (this.retired && this.leases === 0 && this.destroy !== undefined) {
+      const destroy = this.destroy;
+      this.destroy = undefined;
+      destroy();
+    }
+    for (const resolve of this.waiters) resolve();
+    this.waiters.clear();
+  }
+}