@ifc-lite/renderer 1.37.0 → 1.38.1

package/dist/scene.js

@@ -8,6 +8,7 @@ import { sumResidentGpuBytes } from './render-stats.js';
 import { simplifyIndicesByClustering, lodCellSizeForBounds, LOD_MIN_TRIANGLES } from './lod-simplify.js';
 import { quantizeInterleaved } from './quantize.js';
 import { bucketBaseKeyFor } from './chunk-grid.js';
+import { VisibilityEpochTracker } from './visibility-epoch.js';
 import { selectEvictions } from './residency.js';
 import { OPAQUE_ALPHA_CUTOFF } from './overlay-routing.js';
 import { prepareInstancedRender, foldOccurrenceWorldBox, INSTANCE_STRIDE_BYTES, INSTANCE_COLOR_OFFSET, INSTANCE_FLAGS_OFFSET, INSTANCE_FLAG_SELECTED, INSTANCE_FLAG_HIDDEN, } from './instanced-render.js';
@@ -39,8 +40,11 @@ export class Scene {
     instancedHidden = new Set(); // currently hidden instanced express_ids (hide/isolate)
     instancedOverridden = new Set(); // currently colour-overridden instanced express_ids
     instancedHasTransparent = false; // an override made some instanced occurrence translucent
-    lastInstancedHiddenIds = null; // ref-equality guard for setInstancedVisibility
-    lastInstancedIsolatedIds = null;
+    // Content-based change guard for setInstancedVisibility — same contract as
+    // RenderOptions.hiddenIds (in-place mutation and fresh identical Sets both
+    // behave), keeping the instanced path in lockstep with the batched path.
+    instancedVisibilityEpochs = new VisibilityEpochTracker();
+    lastInstancedVisibilityVersion = -1;
     instancedVisibilityDirty = false; // set when a new shard adds occurrences → re-apply visibility
     // Buffer-size-aware bucket splitting: when a single color group's geometry
     // would exceed the GPU maxBufferSize, overflow is directed to a new
@@ -96,6 +100,11 @@ export class Scene {
     // This allows rendering partially visible batches as single draw calls instead of 10,000+ individual draws
     partialBatchCache = new Map();
     partialBatchCacheKeys = new Map(); // sourceBatchKey -> current cache key (for invalidation)
+    // sourceBatchKey -> visibility/override epoch its cached partial batch was
+    // built for. Lets getOrCreatePartialBatch return the cached clone WITHOUT
+    // re-sorting + re-hashing every visible id each frame while the epoch holds
+    // (issue: O(elements) per-frame work under hide/isolate). See render loop.
+    partialBatchCacheVersions = new Map();
     // Color overlay system for lens coloring — NEVER modifies original batches.
     // Overlay batches render on top using depthCompare 'equal', so they only
     // paint where original geometry already wrote depth. Clearing is instant.
@@ -103,6 +112,11 @@ export class Scene {
     // Defensively-typed: the renderer is the sole writer (via setColorOverrides),
     // external readers go through getColorOverrides() and get a ReadonlyMap.
     colorOverrides = null;
+    // Bumped whenever the colour-override set changes. The partial sub-batch's
+    // visible subset depends on override promotion (splitVisibleIdsByPromotion),
+    // so the render loop folds this into the partial-batch cache epoch to keep the
+    // per-frame fast path correct when overrides change with no visibility change.
+    colorOverrideGeneration = 0;
     // Streaming optimization: track pending batch rebuilds
     pendingBatchKeys = new Set();
     // Temporary fragment batches created during streaming for immediate rendering.
@@ -571,7 +585,58 @@ export class Scene {
                 this.partialBatchCache.delete(cacheKey);
             }
             this.partialBatchCacheKeys.delete(sourceBatchKey);
+            this.partialBatchCacheVersions.delete(sourceBatchKey);
+        }
+    }
+    /** Destroy + drop EVERY cached partial sub-batch. The clones built during
+     *  hide/isolate are deliberately excluded from the GPU residency budget and
+     *  are otherwise only freed on clear()/finalize/evict — never when filtering
+     *  ends. The render loop calls this on the transition back to fully-visible so
+     *  the ~model-sized clone VRAM is not pinned until the next model reload. Uses
+     *  the same destroy-then-clear idiom as clear(); safe to call between frames
+     *  because the previous frame is already submitted (WebGPU defers the free
+     *  past in-flight work). */
+    dropAllPartialCaches() {
+        if (this.partialBatchCache.size === 0
+            && this.partialBatchCacheKeys.size === 0
+            && this.partialBatchCacheVersions.size === 0) {
+            return;
         }
+        for (const batch of this.partialBatchCache.values())
+            destroyGpuResources(batch);
+        this.partialBatchCache.clear();
+        this.partialBatchCacheKeys.clear();
+        this.partialBatchCacheVersions.clear();
+    }
+    /** Free the hydrated (pick / selection-highlight) individual meshes that are
+     *  no longer selected, destroying their GPU buffers and dropping them from
+     *  `this.meshes`. A mesh is kept iff its expressId is in `keep` AND it
+     *  matches `keepModelIndex` (undefined = any model) — the same predicate the
+     *  render loop uses to draw selection highlights, so disposal is its exact
+     *  complement. The model scoping matters for federation: models can share
+     *  express ids, and an id-only check would strand the OTHER model's hydrated
+     *  mesh resident and drawing when selection moves across models. Only meshes
+     *  flagged `hydrated` are touched — authored geometry added via addMesh()
+     *  and batch geometry are left untouched. Returns how many were freed. */
+    disposeHydratedMeshesExcept(keep, keepModelIndex) {
+        if (this.meshes.length === 0)
+            return 0;
+        const kept = [];
+        let disposed = 0;
+        for (const mesh of this.meshes) {
+            const keepMesh = keep.has(mesh.expressId)
+                && (keepModelIndex === undefined || mesh.modelIndex === keepModelIndex);
+            if (mesh.hydrated && !keepMesh) {
+                destroyGpuResources(mesh);
+                disposed++;
+            }
+            else {
+                kept.push(mesh);
+            }
+        }
+        if (disposed > 0)
+            this.meshes = kept;
+        return disposed;
     }
     /**
      * Bucket BASE key for a mesh: colour key, prefixed with the mesh's grid
@@ -1718,10 +1783,7 @@ export class Scene {
         this.residencyRestoreQueue.clear();
         this.pendingBatchKeys.clear();
         // Destroy cached partial batches — their colorKeys are now stale
-        for (const batch of this.partialBatchCache.values())
-            destroyGpuResources(batch);
-        this.partialBatchCache.clear();
-        this.partialBatchCacheKeys.clear();
+        this.dropAllPartialCaches();
         // Re-seat the carried cold shells in the fresh bucket map (their GPU
         // shells re-enter the flat array via rebuildPendingBatches below).
         for (const [key, bucket] of carriedCold)
@@ -1799,10 +1861,7 @@ export class Scene {
         this.lastDrawnFrame.clear();
         this.residencyRestoreQueue.clear();
         this.pendingBatchKeys.clear();
-        for (const batch of this.partialBatchCache.values())
-            destroyGpuResources(batch);
-        this.partialBatchCache.clear();
-        this.partialBatchCacheKeys.clear();
+        this.dropAllPartialCaches();
         // Re-seat the carried cold shells in the fresh bucket map.
         for (const [key, bucket] of carriedCold)
             this.buckets.set(key, bucket);
@@ -1924,10 +1983,7 @@ export class Scene {
         this.coldBuckets.clear();
         this.dirtyBuckets.clear();
         this.pendingBatchKeys.clear();
-        for (const batch of this.partialBatchCache.values())
-            destroyGpuResources(batch);
-        this.partialBatchCache.clear();
-        this.partialBatchCacheKeys.clear();
+        this.dropAllPartialCaches();
         this.geometryReleased = true;
         this.ephemeralStreamingMode = false;
     }
@@ -2012,10 +2068,7 @@ export class Scene {
         this.coldBuckets.clear();
         this.dirtyBuckets.clear();
         // 3. Clear partial batch cache (would need mesh data to rebuild)
-        for (const batch of this.partialBatchCache.values())
-            destroyGpuResources(batch);
-        this.partialBatchCache.clear();
-        this.partialBatchCacheKeys.clear();
+        this.dropAllPartialCaches();
         this.geometryReleased = true;
         console.log(`[Scene] Released JS geometry data. ${this.boundingBoxes.size} bounding boxes cached. ` +
             `${this.batchedMeshes.length} GPU batches retained.`);
@@ -2321,10 +2374,25 @@ export class Scene {
      * @param pipeline - Rendering pipeline
      * @returns BatchedMesh containing only visible elements, or undefined if no visible elements
      */
-    getOrCreatePartialBatch(sourceBatchKey, colorKey, visibleIds, device, pipeline) {
+    getOrCreatePartialBatch(sourceBatchKey, colorKey, visibleIds, device, pipeline, visibilityEpoch) {
         // Cannot create partial batches after geometry data has been released
         if (this.geometryReleased)
             return undefined;
+        // Fast path (PERF): while the visibility + colour-override epoch is
+        // unchanged, the visible subset for this sourceBatch is provably identical
+        // to what we cached (the source batch is immutable per id and both hide/
+        // isolate and override promotion are folded into the epoch). Return the
+        // cached clone WITHOUT the O(n) sort + FNV hash below. A rebuilt/evicted
+        // source batch gets a new id → new sourceBatchKey → cache miss here.
+        if (visibilityEpoch !== undefined &&
+            this.partialBatchCacheVersions.get(sourceBatchKey) === visibilityEpoch) {
+            const key = this.partialBatchCacheKeys.get(sourceBatchKey);
+            if (key !== undefined) {
+                const cached = this.partialBatchCache.get(key);
+                if (cached)
+                    return cached;
+            }
+        }
         // Create cache key from colorKey + deterministic hash of all visible IDs
         // Using a proper hash over all IDs to avoid collisions when middle IDs differ
         const sortedIds = Array.from(visibleIds).sort((a, b) => a - b);
@@ -2341,8 +2409,13 @@ export class Scene {
         const currentCacheKey = this.partialBatchCacheKeys.get(sourceBatchKey);
         if (currentCacheKey === cacheKey) {
             const cached = this.partialBatchCache.get(cacheKey);
-            if (cached)
+            if (cached) {
+                // Record the epoch so subsequent frames take the sort-free fast path.
+                if (visibilityEpoch !== undefined) {
+                    this.partialBatchCacheVersions.set(sourceBatchKey, visibilityEpoch);
+                }
                 return cached;
+            }
         }
         // Invalidate old cache for this colorKey if visibility changed
         if (currentCacheKey && currentCacheKey !== cacheKey) {
@@ -2381,6 +2454,9 @@ export class Scene {
         // Cache it
         this.partialBatchCache.set(cacheKey, partialBatch);
         this.partialBatchCacheKeys.set(sourceBatchKey, cacheKey);
+        if (visibilityEpoch !== undefined) {
+            this.partialBatchCacheVersions.set(sourceBatchKey, visibilityEpoch);
+        }
         return partialBatch;
     }
     // ─── Color overlay system ────────────────────────────────────────────
@@ -2399,6 +2475,9 @@ export class Scene {
     setColorOverrides(overrides, device, pipeline) {
         // Destroy previous overlay batches
         this.destroyOverrideBatches();
+        // The override set is changing — invalidate the partial-batch cache epoch so
+        // the render loop rebuilds any promotion-split sub-batches (see render loop).
+        this.colorOverrideGeneration++;
         if (this.geometryReleased) {
             console.warn('[Scene] setColorOverrides called after geometry data was released — skipping.');
             this.colorOverrides = null;
@@ -2452,9 +2531,16 @@ export class Scene {
      */
     clearColorOverrides() {
         this.destroyOverrideBatches();
+        this.colorOverrideGeneration++;
         this.colorOverrides = null;
         this.setInstancedColorOverrides(null);
     }
+    /** Monotonic counter that changes whenever the colour-override set changes.
+     *  The render loop folds it into the partial sub-batch cache epoch so the
+     *  per-frame fast path stays correct across override changes. */
+    getColorOverrideGeneration() {
+        return this.colorOverrideGeneration;
+    }
     /** Get overlay batches for rendering */
     getOverrideBatches() {
         return this.overrideBatches;
@@ -2891,19 +2977,20 @@ export class Scene {
         const device = this.instancedDevice;
         if (!device || this.instancedTemplates.length === 0)
             return;
-        // Called every render frame. The viewer passes stable Set references that only
-        // change when visibility changes, so a reference-equality guard skips the O(N)
-        // set rebuild + allocation during orbit (the common, unchanged case). The dirty
-        // flag forces a recompute after a new shard adds occurrences mid-stream, so an
+        // Called every render frame. Change detection is by CONTENT (the tracker
+        // snapshot-compares), matching the RenderOptions.hiddenIds contract: an
+        // in-place mutation of the caller's Set is seen, a fresh identical Set is
+        // not treated as a change, and the O(occurrences) rebuild below still only
+        // runs on a real visibility change (orbit stays cheap). The dirty flag
+        // forces a recompute after a new shard adds occurrences mid-stream, so an
         // active isolate/hide also applies to geometry that streams in afterwards.
+        const visibilityVersion = this.instancedVisibilityEpochs.update(hiddenIds, isolatedIds);
         if (!this.instancedVisibilityDirty &&
-            hiddenIds === this.lastInstancedHiddenIds &&
-            isolatedIds === this.lastInstancedIsolatedIds) {
+            visibilityVersion === this.lastInstancedVisibilityVersion) {
             return;
         }
         this.instancedVisibilityDirty = false;
-        this.lastInstancedHiddenIds = hiddenIds ?? null;
-        this.lastInstancedIsolatedIds = isolatedIds ?? null;
+        this.lastInstancedVisibilityVersion = visibilityVersion;
         const isHidden = (eid) => (hiddenIds != null && hiddenIds.has(eid)) ||
             (isolatedIds != null && !isolatedIds.has(eid));
         // Recompute the effective hidden set over all instanced occurrences and diff vs
@@ -3121,13 +3208,13 @@ export class Scene {
         this.instancedHidden.clear();
         this.instancedOverridden.clear();
         this.instancedHasTransparent = false;
-        this.lastInstancedHiddenIds = null;
-        this.lastInstancedIsolatedIds = null;
+        // Force the next setInstancedVisibility to recompute against fresh state.
+        this.lastInstancedVisibilityVersion = -1;
         this.instancedVisibilityDirty = false;
         this.instancedDevice = undefined;
-        // Clear partial batch cache
-        for (const batch of this.partialBatchCache.values())
-            destroyGpuResources(batch);
+        // Clear partial batch cache (destroys buffers + drops all cache maps)
+        this.dropAllPartialCaches();
+        this.colorOverrideGeneration++;
         // Destroy streaming fragments (already included in batchedMeshes, but tracked separately)
         this.streamingFragments = [];
         this.destroyOverrideBatches();
@@ -3147,8 +3234,6 @@ export class Scene {
         this.dirtyBuckets.clear();
         this.cachedMaxBufferSize = 0;
         this.pendingBatchKeys.clear();
-        this.partialBatchCache.clear();
-        this.partialBatchCacheKeys.clear();
         this.meshQueue = [];
         this.meshQueueReadIndex = 0;
         this.geometryReleased = false;