@ifc-lite/renderer 6.0.1 → 6.3.0

package/dist/scene.js

@@ -9,6 +9,7 @@ import { createInstancedRteDeltaStream, invalidateInstancedRteDeltas } from './i
 import { materializeInstances } from './scene-instance-materialization.js';
 import { InstanceSuppression } from './scene-instance-suppression.js';
 import { createSceneBatch } from './scene-batch-upload.js';
+import { flushQueuedMeshes } from './scene-flush.js';
 import { createStaticGpuBuffer } from './gpu-static-upload.js';
 import { createSceneAppearancePreview, rebindSceneAppearanceAccess } from './scene-appearance-preview.js';
 import { AppearanceBuckets } from './scene-appearance-buckets.js';
@@ -36,62 +37,15 @@ import { translateSceneModel, rotateSceneModelInstances, releaseInstanceVertices
 import { ModelTranslations } from './model-translation.js';
 import { unionInstancedWorldAabb as unionInstanceBounds } from './scene-instance-bounds.js';
 import { DerivedMeshProvenance } from './scene-derived-mesh-provenance.js';
-import { rebuildSceneBatches } from './scene-batch-rebuild.js';
+import { forgetEmptyModelFrames, rebuildSceneBatches } from './scene-batch-rebuild.js';
 import { regroupStreamedBuckets } from './scene-finalize-regroup.js';
+import { perfCount, perfCounters, perfTally } from '@ifc-lite/load-trace';
 import { dropAllPartialCaches as dropAllPartialCachesIn, dropPartialCacheForBatch as dropPartialCacheForBatchIn, retireUnusedAlphaSlots as retireUnusedAlphaSlotsIn, } from './partial-batch-cache.js';
 import { prepareInstancedRender, foldOccurrenceWorldBox, INSTANCE_STRIDE_BYTES, INSTANCE_COLOR_OFFSET, INSTANCE_FLAGS_OFFSET, INSTANCE_FLAG_SELECTED, INSTANCE_FLAG_HIDDEN, INSTANCE_FINISH_FLAGS_MASK, } from './instanced-render.js';
 import { translateInstanceRecord } from './scene-instance-translation.js';
 import { discardSceneGpuResourcesForRecovery, prepareSceneDeviceRecovery, repartitionHydratedRecoveryBucket, restoreSceneGpuResourcesAfterRecovery } from './scene-device-recovery.js';
 const EMPTY_INSTANCED_TEMPLATES = [];
-/**
- * Pure helper: compute the exclusive end index of the next flushPending()
- * append chunk, starting at `readIndex` and bounded by BOTH mesh count
- * (`hardEnd`, computed by the caller) and index volume (`maxIndicesPerAppend`).
- * Always takes at least one mesh past `readIndex` -- a single oversize mesh is
- * split upstream by splitMeshForStreaming, so the volume cap never blocks the
- * first mesh of a chunk.
- *
- * Non-finite-safe by construction: every non-finite `next` (a malformed mesh
- * reporting NaN, +Infinity, or -Infinity for `indices.length`) closes the
- * chunk explicitly instead of being folded into the running `chunkIndices`
- * total. Only NaN would have made a naive cap check `chunkIndices + next >
- * maxIndicesPerAppend` silently `false` forever (`NaN > cap` is always
- * `false`); +Infinity actually made that same check fire immediately
- * (`chunkIndices + Infinity > cap` is `true`), closing the chunk after a
- * single oversize mesh instead of growing it unbounded. The current
- * `!(chunkIndices + next <= maxIndicesPerAppend)` form below rejects both
- * NaN and +Infinity explicitly rather than relying on that asymmetry.
- * -Infinity needed a separate, explicit check: `-Infinity <= cap` is always
- * `true`, so `!(... <= cap)` lets it straight through, and folding it into
- * `chunkIndices` would poison the running total to -Infinity permanently,
- * keeping the cap vacuous for every mesh after it, not just the malformed
- * one.
- */
-export function computeFlushChunkEnd(getIndicesLength, readIndex, hardEnd, maxIndicesPerAppend) {
-    let chunkEnd = readIndex;
-    let chunkIndices = 0;
-    while (chunkEnd < hardEnd) {
-        const next = getIndicesLength(chunkEnd);
-        if (!Number.isFinite(next)) {
-            // A malformed mesh reporting a non-finite indices.length (NaN, +/-Infinity)
-            // must close the chunk here rather than being folded into chunkIndices:
-            // `chunkIndices += -Infinity` would poison the running total to -Infinity
-            // permanently, making `!(chunkIndices + next <= maxIndicesPerAppend)`
-            // false forever and letting the volume cap never fire again for the
-            // rest of this chunk. Always take at least the first mesh past
-            // readIndex (same progress guarantee as the NaN case below).
-            if (chunkEnd === readIndex)
-                chunkEnd++;
-            break;
-        }
-        if (chunkEnd > readIndex && !(chunkIndices + next <= maxIndicesPerAppend)) {
-            break;
-        }
-        chunkIndices += next;
-        chunkEnd++;
-    }
-    return chunkEnd;
-}
+export { computeFlushChunkEnd } from './scene-flush.js';
 export class Scene {
     meshes = [];
     batchedMeshes = []; // flat render array (rebuilt from buckets)
@@ -1199,6 +1153,7 @@ export class Scene {
         }, device, pipeline);
         this.batchedMeshes = [...this.buckets.values()].flatMap(bucket => bucket.batchedMesh ? [bucket.batchedMesh] : []);
         this.pendingBatchKeys.clear();
+        forgetEmptyModelFrames(this.buckets, this.sharedFrameOrigins);
     }
     /**
      * Check if there are pending batch rebuilds
@@ -1782,64 +1737,20 @@ export class Scene {
      * @param budgetMs Time slice per call. The 12 ms default keeps the main
      *   thread returning to the worker-message pump while geometry streams; a
      *   host with nothing else to serve may drain faster (#6436).
+     * @param trace The streaming load's trace (#6979): a call that uploaded
+     *   anything records one `scene.flushPending` span.
+     * @param deterministicUploads Benchmark-only per-mesh fragments with count
+     *   and index-volume bounds. These totals describe a different timing workload.
      * @returns true if any meshes were processed (caller should render)
      */
-    flushPending(device, pipeline, budgetMs = 12) {
-        if (!this.hasQueuedMeshes())
-            return false;
-        // Drain the queue in chunks bounded by BOTH mesh count AND triangle volume,
-        // yielding the frame back at the TOP of the loop. The mesh-count-only chunker
-        // could merge a 512-mesh chunk of high-poly meshes (e.g. 899 Velux roof
-        // windows at 7624 tris each → ~3.9M tris) in ONE indivisible mergeGeometry +
-        // GPU buffer upload copy — hundreds of ms that parked the main thread
-        // past the 16s stream watchdog. Capping each appendToBatches by index volume
-        // keeps every synchronous slice ≈ one bounded fragment merge (~12-15ms).
-        const MAX_MESHES_PER_FLUSH = 4096;
-        const MESHES_PER_APPEND = 512;
-        const MAX_INDICES_PER_APPEND = Scene.STREAMING_FRAGMENT_MAX_INDICES;
-        const start = performance.now();
-        let processed = 0;
-        while (this.meshQueueReadIndex < this.meshQueue.length && processed < MAX_MESHES_PER_FLUSH) {
-            // Yield once the budget is spent (after at least one append) so the main
-            // thread returns to the worker-message pump and the watchdog never trips.
-            if (processed > 0 && performance.now() - start >= budgetMs) {
-                break;
-            }
-            const hardEnd = Math.min(this.meshQueue.length, this.meshQueueReadIndex + MESHES_PER_APPEND, this.meshQueueReadIndex + (MAX_MESHES_PER_FLUSH - processed));
-            const chunkEnd = computeFlushChunkEnd((i) => this.meshQueue[i].indices.length, this.meshQueueReadIndex, hardEnd, MAX_INDICES_PER_APPEND);
-            // Defensive, not reachable today: chunkEnd is provably > meshQueueReadIndex
-            // here because hardEnd is provably > meshQueueReadIndex whenever this outer
-            // loop iterates, via three invariants that hold simultaneously above:
-            //   (1) this.meshQueue.length > this.meshQueueReadIndex -- the outer while
-            //       condition that got us into this iteration;
-            //   (2) this.meshQueueReadIndex + MESHES_PER_APPEND, and MESHES_PER_APPEND
-            //       (512) is a positive constant;
-            //   (3) this.meshQueueReadIndex + (MAX_MESHES_PER_FLUSH - processed), and
-            //       processed < MAX_MESHES_PER_FLUSH -- the other half of the outer
-            //       while condition -- so that term is >= readIndex + 1 too.
-            // hardEnd is the min of all three, so hardEnd >= readIndex + 1, and
-            // computeFlushChunkEnd always advances by at least one past readIndex.
-            // If a future change breaks any one of those three invariants, hardEnd
-            // could collapse to readIndex and the loop would spin the main thread at
-            // 100% CPU doing zero allocation -- the exact signature that made #2379
-            // expensive to diagnose. This break turns that failure mode into "flush
-            // stops early" instead.
-            if (chunkEnd === this.meshQueueReadIndex)
-                break;
-            const chunk = this.meshQueue.slice(this.meshQueueReadIndex, chunkEnd);
-            this.meshQueueReadIndex = chunkEnd;
+    flushPending(device, pipeline, budgetMs = 12, trace, deterministicUploads = false) {
+        const result = flushQueuedMeshes(this.meshQueue, this.meshQueueReadIndex, (chunk, nextReadIndex) => {
+            this.meshQueueReadIndex = nextReadIndex;
             this.appendToBatches(chunk, device, pipeline, true);
-            processed += chunk.length;
-        }
-        if (this.meshQueueReadIndex >= this.meshQueue.length) {
-            this.meshQueue.length = 0;
-            this.meshQueueReadIndex = 0;
-        }
-        else if (this.meshQueueReadIndex >= 8192 && this.meshQueueReadIndex * 2 >= this.meshQueue.length) {
-            this.meshQueue = this.meshQueue.slice(this.meshQueueReadIndex);
-            this.meshQueueReadIndex = 0;
-        }
-        return processed > 0;
+        }, { budgetMs, trace, deterministicUploads, maxIndicesPerAppend: Scene.STREAMING_FRAGMENT_MAX_INDICES });
+        this.meshQueue = result.queue;
+        this.meshQueueReadIndex = result.readIndex;
+        return result.processed > 0;
     }
     /**
      * Create lightweight fragment batches from a single streaming batch.
@@ -1925,6 +1836,7 @@ export class Scene {
         // Save references to old fragments/batches — keep them rendering
         // until the new proper batches are fully built (no visual gap).
         const oldFragments = this.streamingFragments;
+        perfTally('render.finalize', oldFragments.length, 'fragments'); // #6957 fragment rebuilds
         const oldBatches = this.batchedMeshes;
         const fragmentSet = new Set(oldFragments);
         const oldBatchSet = new Set(oldBatches);
@@ -1962,6 +1874,9 @@ export class Scene {
         // already retired by rebuildPendingBatches.
         this.retireFinalizedBatches(oldFragments);
         this.retireFinalizedBatches(regroup?.retired ?? []);
+        // #6957: same batch tally as the time-sliced path (only reached when the rebuild succeeded).
+        if (perfCounters.enabled)
+            perfCount('render.finalize.batches', this.batchedMeshes.filter((b) => !oldBatchSet.has(b)).length);
     }
     /**
      * Time-sliced version of finalizeStreaming.
@@ -1972,15 +1887,21 @@ export class Scene {
      * @param device  GPU device
      * @param pipeline  Render pipeline
      * @param budgetMs  Max milliseconds per chunk (default 8 — half a 60fps frame)
+     * @param trace  The load's trace (#6979): `scene.finalize` from this call
+     *   until the promise settles, with `scene.finalize.regroup` under it
      * @returns Promise that resolves when all batches are rebuilt
      */
-    finalizeStreamingAsync(device, pipeline, budgetMs = 8) {
+    finalizeStreamingAsync(device, pipeline, budgetMs = 8, trace) {
+        const span = trace?.enabled ? trace.begin('scene.finalize', { fragments: this.streamingFragments.length, ephemeral: this.ephemeralStreamingMode }) : -1;
         if (this.ephemeralStreamingMode) {
             this.finishEphemeralStreaming();
+            trace?.end(span);
             return Promise.resolve();
         }
-        if (this.streamingFragments.length === 0)
+        if (this.streamingFragments.length === 0) {
+            trace?.end(span);
             return Promise.resolve();
+        }
         // Mark the rebuild as in-flight: the preamble empties streamingFragments
         // synchronously, so settle-sensitive consumers need this flag until the
         // time-sliced rebuild swaps the new batch array in.
@@ -1989,6 +1910,7 @@ export class Scene {
         // eslint-disable-next-line @typescript-eslint/no-this-alias
         const scene = this;
         const oldFragments = this.streamingFragments;
+        perfTally('render.finalize', oldFragments.length, 'fragments'); // #6957 fragment rebuilds
         const oldBatches = this.batchedMeshes;
         const fragmentSet = new Set(oldFragments);
         const oldBatchSet = new Set(oldBatches);
@@ -2010,6 +1932,7 @@ export class Scene {
             let regroup = null;
             let pendingKeys = [];
             let keyIdx = 0;
+            let chunks = 0;
             function rollback() {
                 for (const { bucket, previous, previousFrameOrigin, batch } of createdOwned) {
                     // Repair the owner BEFORE the free, so no bucket is ever observable
@@ -2031,6 +1954,7 @@ export class Scene {
             function processChunk() {
                 try {
                     const chunkStart = performance.now();
+                    chunks++;
                     while (keyIdx < pendingKeys.length) {
                         const key = pendingKeys[keyIdx++];
                         const bucket = scene.buckets.get(key);
@@ -2070,23 +1994,30 @@ export class Scene {
                         ...scene.streamingFragments,
                     ];
                     scene.retireFinalizedBatches(retired);
+                    perfCount('render.finalize.batches', createdOwned.length);
                     scene.finalizeInProgress = false;
+                    trace?.end(span, { batches: createdOwned.length, chunks });
                     resolve();
                 }
                 catch (err) {
                     rollback();
+                    trace?.end(span, { error: true });
                     reject(err);
                 }
             }
             try {
                 // --- Synchronous preamble: re-group the streamed meshes only ---
                 scene.streamingFragments = [];
+                const regroupStart = performance.now();
                 regroup = scene.regroupStreamed();
+                if (trace?.enabled)
+                    trace.record('scene.finalize.regroup', regroupStart, performance.now(), undefined, span);
                 pendingKeys = Array.from(scene.pendingBatchKeys);
                 scene.pendingBatchKeys.clear();
             }
             catch (err) {
                 rollback();
+                trace?.end(span, { error: true });
                 reject(err);
                 return;
             }