@forgeax/engine-render 0.1.27 → 0.1.29

package/src/reflection/record-owner.ts

@@ -130,12 +130,10 @@ export class ReflectionProbeRecordOwner {
   private outputFormat: TextureFormat;
   private fallbackFormatAvailable: boolean;
   private nextFallbackTicket = 0;
-  // Readback completion is asynchronous and can overlap the next frame's
-  // prepare. Key tickets by immutable id and retain only the latest ticket
-  // per renderable; an older completion is stale by definition once a newer
-  // candidate has been staged, but cannot erase the newer ticket.
-  private pendingFallback = new Map<number, PendingFallback>();
-  private latestFallbackTickets = new Map<string, number>();
+  // Submitted frames own their immutable candidates until completion. Keep
+  // only the current projection here: preparing a source-identical frame
+  // must not starve an earlier asynchronous readback of publication.
+  private latestFallbackTickets = new Map<string, PendingFallback>();
   private fallbackRetiredFrames = new Map<string, number>();
   private fallbackCommittedFrames = new Map<string, number>();
   private fallbackGenerations = new Map<
@@ -283,14 +281,13 @@ export class ReflectionProbeRecordOwner {
   }
 
   private retireFallbackState(frameId: number): void {
-    for (const pending of this.pendingFallback.values()) {
+    for (const pending of this.latestFallbackTickets.values()) {
       const key = pending.projection.renderableKey;
       if (key !== undefined) this.fallbackRetiredFrames.set(key, frameId);
     }
     for (const key of this.fallbackReceipts.keys()) {
       this.fallbackRetiredFrames.set(key, frameId);
     }
-    this.pendingFallback.clear();
     this.latestFallbackTickets.clear();
     this.fallbackReceipts.clear();
     this.fallbackSignatures.clear();
@@ -561,7 +558,6 @@ export class ReflectionProbeRecordOwner {
       // producer's second output, so the graph intentionally omits the MRT.
       // Retire only this frame's candidate tickets; keep any previously
       // committed LKG receipt without manufacturing a readback failure.
-      this.discardFallbackTickets(fallbackTickets);
       return;
     }
     let completionFailure: ReflectionFallbackFailureInput | undefined;
@@ -650,6 +646,13 @@ export class ReflectionProbeRecordOwner {
         continue;
       }
       const signature = reflectionFallbackProjectionSignature(projection.value);
+      const previousCandidate = this.latestFallbackTickets.get(renderableKey);
+      if (
+        previousCandidate !== undefined &&
+        reflectionFallbackProjectionSignature(previousCandidate.projection) !== signature
+      ) {
+        this.fallbackRetiredFrames.set(renderableKey, frameId);
+      }
       const previousSignature = this.fallbackSignatures.get(renderableKey);
       if (previousSignature !== undefined && previousSignature !== signature) {
         // A changed source, coverage, extent, or BRDF is not a compatible LKG.
@@ -668,11 +671,8 @@ export class ReflectionProbeRecordOwner {
         deviceGeneration: this.internals.deviceScope.generation,
         projection: projection.value,
       };
-      const previousTicket = this.latestFallbackTickets.get(renderableKey);
-      if (previousTicket !== undefined) this.pendingFallback.delete(previousTicket);
       tickets.set(renderableKey, pending);
-      this.pendingFallback.set(pending.ticket, pending);
-      this.latestFallbackTickets.set(renderableKey, pending.ticket);
+      this.latestFallbackTickets.set(renderableKey, pending);
     }
     // Retire rows that disappeared from this frame's main-pass selection.
     // Keeping them would make a detached inspection row outlive its source.
@@ -688,23 +688,12 @@ export class ReflectionProbeRecordOwner {
     for (const renderableKey of this.fallbackGenerations.keys()) {
       if (!tickets.has(renderableKey)) this.fallbackGenerations.delete(renderableKey);
     }
-    // An in-flight ticket for a row that disappeared is no longer admissible.
-    // Remove it eagerly so the map remains bounded; completion still sees the
-    // missing ticket and safely rejects it as stale.
-    for (const [ticket, pending] of this.pendingFallback) {
-      const key = pending.projection.renderableKey;
-      const current = key === undefined ? undefined : tickets.get(key);
-      if (
-        key !== undefined &&
-        pending.frameId < frameId &&
-        (current === undefined ||
-          current.projection.source === 'neutral' ||
-          reflectionFallbackProjectionSignature(current.projection) !==
-            reflectionFallbackProjectionSignature(pending.projection))
-      ) {
-        this.pendingFallback.delete(ticket);
-        if (current === undefined) this.fallbackRetiredFrames.set(key, frameId);
-      }
+    // Retire even uncommitted rows, so disappear/reappear cannot revive an
+    // old completion. Storage stays bounded by current renderables.
+    for (const key of this.latestFallbackTickets.keys()) {
+      if (tickets.has(key)) continue;
+      this.latestFallbackTickets.delete(key);
+      this.fallbackRetiredFrames.set(key, frameId);
     }
     if (tickets.size === 0 && facts.length === 0) {
       const neutralKey = '__frame__';
@@ -723,11 +712,8 @@ export class ReflectionProbeRecordOwner {
           deviceGeneration: this.internals.deviceScope.generation,
           projection: projection.value,
         };
-        const previousTicket = this.latestFallbackTickets.get(neutralKey);
-        if (previousTicket !== undefined) this.pendingFallback.delete(previousTicket);
         tickets.set(neutralKey, pending);
-        this.pendingFallback.set(pending.ticket, pending);
-        this.latestFallbackTickets.set(neutralKey, pending.ticket);
+        this.latestFallbackTickets.set(neutralKey, pending);
       }
     }
     this.selectFallbackReceiptKey(tickets, skylight !== undefined);
@@ -778,19 +764,13 @@ export class ReflectionProbeRecordOwner {
     this.fallbackReceiptKey = firstKey;
   }
 
-  private discardFallbackTickets(fallbackTickets: ReadonlyMap<string, PendingFallback>): void {
-    for (const pending of fallbackTickets.values()) {
-      this.pendingFallback.delete(pending.ticket);
-    }
-  }
-
   /** Commit exact-zero neutral rows even when a non-neutral MRT readback fails. */
   private commitNeutralFallbacks(fallbackTickets: ReadonlyMap<string, PendingFallback>): number {
     let committed = 0;
     for (const [renderableKey, pending] of fallbackTickets) {
       if (
         pending.projection.source === 'neutral' &&
-        this.latestFallbackTickets.get(renderableKey) === pending.ticket &&
+        this.latestFallbackTickets.get(renderableKey) === pending &&
         pending.deviceGeneration === this.internals.deviceScope.generation
       ) {
         this.commitFallbackProjection(renderableKey, pending, 'neutral');
@@ -839,7 +819,7 @@ export class ReflectionProbeRecordOwner {
   /** Retain only a source-identical committed row after candidate failure. */
   private preserveFallbackLkg(fallbackTickets: ReadonlyMap<string, PendingFallback>): void {
     for (const [renderableKey, pending] of fallbackTickets) {
-      if (this.latestFallbackTickets.get(renderableKey) !== pending.ticket) continue;
+      if (this.latestFallbackTickets.get(renderableKey) !== pending) continue;
       const previous = this.fallbackReceipts.get(renderableKey);
       const signature = reflectionFallbackProjectionSignature(pending.projection);
       const compatible =
@@ -887,7 +867,6 @@ export class ReflectionProbeRecordOwner {
     // fallback attachment probe. The prepare phase already published the
     // structured capability failure and retired all current rows.
     if (!this.fallbackFormatAvailable) {
-      this.discardFallbackTickets(fallbackTickets);
       return;
     }
     // A graph attachment descriptor is not a producer receipt.  Until the
@@ -906,7 +885,6 @@ export class ReflectionProbeRecordOwner {
         );
         this.preserveFallbackLkg(fallbackTickets);
       }
-      this.discardFallbackTickets(fallbackTickets);
       return;
     }
     if (fallbackOutput?.readback === undefined) {
@@ -930,7 +908,6 @@ export class ReflectionProbeRecordOwner {
         });
       }
       this.preserveFallbackLkg(nonNeutral);
-      this.discardFallbackTickets(fallbackTickets);
       return;
     }
     let readback: {
@@ -954,7 +931,6 @@ export class ReflectionProbeRecordOwner {
           [...fallbackTickets].filter(([, pending]) => pending.projection.source !== 'neutral'),
         ),
       );
-      this.discardFallbackTickets(fallbackTickets);
       return;
     }
     if (
@@ -979,25 +955,23 @@ export class ReflectionProbeRecordOwner {
           [...fallbackTickets].filter(([, pending]) => pending.projection.source !== 'neutral'),
         ),
       );
-      this.discardFallbackTickets(fallbackTickets);
       return;
     }
     const eligible: Array<[string, PendingFallback]> = [];
     let staleCount = 0;
     for (const [renderableKey, pending] of fallbackTickets) {
-      const staged = this.pendingFallback.get(pending.ticket);
       const latest = this.latestFallbackTickets.get(renderableKey);
       const retiredAt = this.fallbackRetiredFrames.get(renderableKey);
       const committedFrame = this.fallbackCommittedFrames.get(renderableKey);
       if (
-        staged !== pending ||
-        latest !== pending.ticket ||
+        latest === undefined ||
+        reflectionFallbackProjectionSignature(latest.projection) !==
+          reflectionFallbackProjectionSignature(pending.projection) ||
         pending.frameId !== fallbackOutput.frameId ||
         pending.deviceGeneration !== this.internals.deviceScope.generation ||
         (retiredAt !== undefined && pending.frameId < retiredAt) ||
         (committedFrame !== undefined && pending.frameId <= committedFrame)
       ) {
-        this.pendingFallback.delete(pending.ticket);
         staleCount += 1;
         continue;
       }
@@ -1009,7 +983,7 @@ export class ReflectionProbeRecordOwner {
           stage: 'completion',
           code: 'reflection-fallback-stale-ticket',
           expected:
-            'the fallback completion ticket to match the latest frame and device generation',
+            'the completed fallback to match the current projection and device without rolling back a committed frame',
           detail: { staleCount },
         });
       }
@@ -1042,7 +1016,6 @@ export class ReflectionProbeRecordOwner {
       });
     }
     for (const [renderableKey, pending] of eligible) {
-      this.pendingFallback.delete(pending.ticket);
       this.commitFallbackProjection(
         renderableKey,
         pending,
@@ -1058,7 +1031,6 @@ export class ReflectionProbeRecordOwner {
       this.destroyProbeResource(resource);
     }
     this.resources.clear();
-    this.pendingFallback.clear();
     this.latestFallbackTickets.clear();
     this.fallbackRetiredFrames.clear();
     this.fallbackCommittedFrames.clear();