@onerjs/loaders 8.53.5 → 8.53.7

package/SPLAT/gaussianSplattingResidencyController.js

@@ -0,0 +1,222 @@
+import { GaussianSplattingBlockAllocator } from "./gaussianSplattingBlockAllocator.js";
+/**
+ * Tracks which streamed Gaussian Splatting files are resident in the GPU work buffer and where, evicting
+ * unreferenced files after a cooldown to keep the resident set within a fixed budget.
+ *
+ * Built on {@link GaussianSplattingBlockAllocator}: each resident file owns a contiguous block of the work
+ * buffer's splat-index address space. A file with no remaining references is scheduled for eviction; after
+ * `cooldownFrames` ticks (or sooner, if the space is needed by a new allocation — "evict-to-fit") its block
+ * is freed and reused. Pinned files (e.g. the always-rendered environment and the padding splat) are never
+ * evicted. The {@link onEvict} callback fires for every file the controller evicts so the owner can drop its
+ * own bookkeeping (e.g. mark it no longer decoded).
+ *
+ * This controller owns only memory/residency bookkeeping — it has no knowledge of the scene, GPU, downloads,
+ * or reference counting (the caller decides when a file's reference count reaches zero and calls
+ * {@link scheduleEviction}).
+ * @experimental
+ */
+export class GaussianSplattingResidencyController {
+    /**
+     * Creates a residency controller.
+     * @param capacity total splat-index capacity of the work buffer
+     * @param cooldownFrames number of ticks an unreferenced file stays resident before being evicted
+     * @param onEvict called with the file index whenever the controller evicts a file (via tick or evict-to-fit)
+     */
+    constructor(capacity, cooldownFrames, onEvict) {
+        this._blocks = new Map();
+        // file -> frames remaining before eviction (only present for unreferenced, evictable files).
+        this._cooldown = new Map();
+        this._pinned = new Set();
+        this._allocator = new GaussianSplattingBlockAllocator(capacity);
+        this._cooldownFrames = Math.max(0, cooldownFrames);
+        this._onEvict = onEvict;
+    }
+    /**
+     * Total splat-index capacity.
+     */
+    get capacity() {
+        return this._allocator.capacity;
+    }
+    /**
+     * Number of files currently resident.
+     */
+    get residentCount() {
+        return this._blocks.size;
+    }
+    /**
+     * Total free splat capacity (sum of all gaps, which may be fragmented). After {@link compact} an
+     * allocation of up to this size is guaranteed to fit.
+     */
+    get freeSize() {
+        return this._allocator.freeSize;
+    }
+    /**
+     * Whether the given file currently has a block in the work buffer.
+     * @param file file index
+     * @returns true if resident
+     */
+    has(file) {
+        return this._blocks.has(file);
+    }
+    /**
+     * The work-buffer splat offset of a resident file, or undefined if not resident.
+     * @param file file index
+     * @returns the splat offset, or undefined
+     */
+    offset(file) {
+        return this._blocks.get(file)?.offset;
+    }
+    /**
+     * Allocates a contiguous block for a file about to be decoded. If there is no room, evicts files whose
+     * eviction cooldown is pending (they are unreferenced) and retries once. Returns the splat offset, or null
+     * if it still does not fit (the caller should refuse the decode and keep the node's current LOD).
+     * @param file file index
+     * @param count number of splats the file needs
+     * @returns the allocated splat offset, or null if it cannot fit
+     */
+    allocate(file, count) {
+        const existing = this._blocks.get(file);
+        if (existing) {
+            return existing.offset;
+        }
+        let block = this._allocator.allocate(count);
+        if (!block) {
+            // Evict-to-fit: reclaim every unreferenced (cooldown-scheduled) file, then retry once.
+            this._evictAllCooled();
+            block = this._allocator.allocate(count);
+            if (!block) {
+                return null;
+            }
+        }
+        this._blocks.set(file, block);
+        return block.offset;
+    }
+    /**
+     * Allocates a block for a file that must never be evicted (e.g. the environment or padding splat).
+     * @param file file index (use a sentinel that cannot collide with real file indices)
+     * @param count number of splats
+     * @returns the allocated splat offset, or null if it cannot fit
+     */
+    pin(file, count) {
+        const offset = this.allocate(file, count);
+        if (offset !== null) {
+            this._pinned.add(file);
+        }
+        return offset;
+    }
+    /**
+     * Frees a file's block immediately (e.g. when a decode was cancelled before completing). Does not fire
+     * {@link onEvict}. No-op for pinned or non-resident files.
+     * @param file file index
+     */
+    free(file) {
+        if (this._pinned.has(file)) {
+            return;
+        }
+        const block = this._blocks.get(file);
+        if (!block) {
+            return;
+        }
+        this._allocator.free(block);
+        this._blocks.delete(file);
+        this._cooldown.delete(file);
+    }
+    /**
+     * Compacts the resident blocks to defragment free space (capacity is unchanged), returning every block
+     * that moved so the caller can relocate the corresponding GPU/CPU splat data. Call when an allocation
+     * fails despite sufficient total free space ({@link freeSize}); afterwards that allocation will fit.
+     * @returns the relocations to apply (empty when nothing moved)
+     */
+    compact() {
+        const before = new Map();
+        for (const [file, block] of Array.from(this._blocks)) {
+            before.set(file, block.offset);
+        }
+        this._allocator.defrag(0);
+        const moves = [];
+        for (const [file, block] of Array.from(this._blocks)) {
+            const oldOffset = before.get(file);
+            if (oldOffset !== block.offset) {
+                moves.push({ file, oldOffset, newOffset: block.offset, count: block.size });
+            }
+        }
+        return moves;
+    }
+    /**
+     * Returns the current resident blocks (file index, splat offset, splat count). Used to relocate GPU/CPU
+     * data after {@link compact}.
+     * @returns one entry per resident file
+     */
+    getResidentBlocks() {
+        const result = [];
+        for (const [file, block] of Array.from(this._blocks)) {
+            result.push({ file, offset: block.offset, count: block.size });
+        }
+        return result;
+    }
+    /**
+     * Schedules an unreferenced resident file for eviction after the cooldown. No-op for pinned or
+     * non-resident files.
+     * @param file file index
+     */
+    scheduleEviction(file) {
+        if (this._pinned.has(file) || !this._blocks.has(file)) {
+            return;
+        }
+        this._cooldown.set(file, this._cooldownFrames);
+    }
+    /**
+     * Cancels a pending eviction because the file was referenced again.
+     * @param file file index
+     */
+    cancelEviction(file) {
+        this._cooldown.delete(file);
+    }
+    /**
+     * Advances all eviction cooldowns by one frame, evicting any that expire. Each evicted file fires
+     * {@link onEvict}.
+     * @returns the file indices evicted this tick
+     */
+    tick() {
+        if (this._cooldown.size === 0) {
+            return [];
+        }
+        const evicted = [];
+        for (const [file, frames] of Array.from(this._cooldown)) {
+            if (frames <= 1) {
+                evicted.push(file);
+            }
+            else {
+                this._cooldown.set(file, frames - 1);
+            }
+        }
+        for (const file of evicted) {
+            this._evict(file);
+        }
+        return evicted;
+    }
+    /**
+     * Releases all bookkeeping. The allocator and maps are cleared.
+     */
+    dispose() {
+        this._blocks.clear();
+        this._cooldown.clear();
+        this._pinned.clear();
+    }
+    _evictAllCooled() {
+        const files = Array.from(this._cooldown.keys());
+        for (const file of files) {
+            this._evict(file);
+        }
+    }
+    _evict(file) {
+        const block = this._blocks.get(file);
+        if (block) {
+            this._allocator.free(block);
+            this._blocks.delete(file);
+        }
+        this._cooldown.delete(file);
+        this._onEvict(file);
+    }
+}
+//# sourceMappingURL=gaussianSplattingResidencyController.js.map

package/SPLAT/gaussianSplattingResidencyController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gaussianSplattingResidencyController.js","sourceRoot":"","sources":["../../../../dev/loaders/src/SPLAT/gaussianSplattingResidencyController.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,+BAA+B,EAAkC,MAAM,mCAAmC,CAAC;AAiBpH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,oCAAoC;IAS7C;;;;;OAKG;IACH,YAAmB,QAAgB,EAAE,cAAsB,EAAE,OAA+B;QAb3E,YAAO,GAAG,IAAI,GAAG,EAAqC,CAAC;QACxE,6FAA6F;QAC5E,cAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;QACtC,YAAO,GAAG,IAAI,GAAG,EAAU,CAAC;QAWzC,IAAI,CAAC,UAAU,GAAG,IAAI,+BAA+B,CAAC,QAAQ,CAAC,CAAC;QAChE,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;QACnD,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,IAAW,QAAQ;QACf,OAAO,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;IACpC,CAAC;IAED;;OAEG;IACH,IAAW,aAAa;QACpB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC7B,CAAC;IAED;;;OAGG;IACH,IAAW,QAAQ;QACf,OAAO,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;IACpC,CAAC;IAED;;;;OAIG;IACI,GAAG,CAAC,IAAY;QACnB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,IAAY;QACtB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAC1C,CAAC;IAED;;;;;;;OAOG;IACI,QAAQ,CAAC,IAAY,EAAE,KAAa;QACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,QAAQ,EAAE,CAAC;YACX,OAAO,QAAQ,CAAC,MAAM,CAAC;QAC3B,CAAC;QACD,IAAI,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC5C,IAAI,CAAC,KAAK,EAAE,CAAC;YACT,uFAAuF;YACvF,IAAI,CAAC,eAAe,EAAE,CAAC;YACvB,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YACxC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACT,OAAO,IAAI,CAAC;YAChB,CAAC;QACL,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC9B,OAAO,KAAK,CAAC,MAAM,CAAC;IACxB,CAAC;IAED;;;;;OAKG;IACI,GAAG,CAAC,IAAY,EAAE,KAAa;QAClC,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC1C,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YAClB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC3B,CAAC;QACD,OAAO,MAAM,CAAC;IAClB,CAAC;IAED;;;;OAIG;IACI,IAAI,CAAC,IAAY;QACpB,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,OAAO;QACX,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC,KAAK,EAAE,CAAC;YACT,OAAO;QACX,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC5B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC1B,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAED;;;;;OAKG;IACI,OAAO;QACV,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;QACzC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACnD,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QACnC,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAC1B,MAAM,KAAK,GAAqB,EAAE,CAAC;QACnC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACnD,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAE,CAAC;YACpC,IAAI,SAAS,KAAK,KAAK,CAAC,MAAM,EAAE,CAAC;gBAC7B,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;YAChF,CAAC;QACL,CAAC;QACD,OAAO,KAAK,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACI,iBAAiB;QACpB,MAAM,MAAM,GAA2D,EAAE,CAAC;QAC1E,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACnD,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QACnE,CAAC;QACD,OAAO,MAAM,CAAC;IAClB,CAAC;IAED;;;;OAIG;IACI,gBAAgB,CAAC,IAAY;QAChC,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACpD,OAAO;QACX,CAAC;QACD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC;IACnD,CAAC;IAED;;;OAGG;IACI,cAAc,CAAC,IAAY;QAC9B,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAED;;;;OAIG;IACI,IAAI;QACP,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YAC5B,OAAO,EAAE,CAAC;QACd,CAAC;QACD,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YACtD,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;gBACd,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACvB,CAAC;iBAAM,CAAC;gBACJ,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC,CAAC;YACzC,CAAC;QACL,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;YACzB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;QACD,OAAO,OAAO,CAAC;IACnB,CAAC;IAED;;OAEG;IACI,OAAO;QACV,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QACvB,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;IAEO,eAAe;QACnB,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;QAChD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACvB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;IACL,CAAC;IAEO,MAAM,CAAC,IAAY;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,KAAK,EAAE,CAAC;YACR,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC5B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC9B,CAAC;QACD,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC5B,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;CACJ","sourcesContent":["import { type Nullable } from \"core/types\";\r\nimport { GaussianSplattingBlockAllocator, type GaussianSplattingMemBlock } from \"./gaussianSplattingBlockAllocator\";\r\n\r\n/**\r\n * One resident block relocation produced by {@link GaussianSplattingResidencyController.compact}: the file's\r\n * splat data must be moved from `oldOffset` to `newOffset` (`count` splats) in the work buffer.\r\n */\r\nexport interface IResidencyMove {\r\n    /** File index whose splat data must move. */\r\n    file: number;\r\n    /** The file's previous splat offset in the work buffer. */\r\n    oldOffset: number;\r\n    /** The file's new splat offset after compaction. */\r\n    newOffset: number;\r\n    /** Number of splats in the file. */\r\n    count: number;\r\n}\r\n\r\n/**\r\n * Tracks which streamed Gaussian Splatting files are resident in the GPU work buffer and where, evicting\r\n * unreferenced files after a cooldown to keep the resident set within a fixed budget.\r\n *\r\n * Built on {@link GaussianSplattingBlockAllocator}: each resident file owns a contiguous block of the work\r\n * buffer's splat-index address space. A file with no remaining references is scheduled for eviction; after\r\n * `cooldownFrames` ticks (or sooner, if the space is needed by a new allocation — \"evict-to-fit\") its block\r\n * is freed and reused. Pinned files (e.g. the always-rendered environment and the padding splat) are never\r\n * evicted. The {@link onEvict} callback fires for every file the controller evicts so the owner can drop its\r\n * own bookkeeping (e.g. mark it no longer decoded).\r\n *\r\n * This controller owns only memory/residency bookkeeping — it has no knowledge of the scene, GPU, downloads,\r\n * or reference counting (the caller decides when a file's reference count reaches zero and calls\r\n * {@link scheduleEviction}).\r\n * @experimental\r\n */\r\nexport class GaussianSplattingResidencyController {\r\n    private readonly _allocator: GaussianSplattingBlockAllocator;\r\n    private readonly _blocks = new Map<number, GaussianSplattingMemBlock>();\r\n    // file -> frames remaining before eviction (only present for unreferenced, evictable files).\r\n    private readonly _cooldown = new Map<number, number>();\r\n    private readonly _pinned = new Set<number>();\r\n    private readonly _cooldownFrames: number;\r\n    private readonly _onEvict: (file: number) => void;\r\n\r\n    /**\r\n     * Creates a residency controller.\r\n     * @param capacity total splat-index capacity of the work buffer\r\n     * @param cooldownFrames number of ticks an unreferenced file stays resident before being evicted\r\n     * @param onEvict called with the file index whenever the controller evicts a file (via tick or evict-to-fit)\r\n     */\r\n    public constructor(capacity: number, cooldownFrames: number, onEvict: (file: number) => void) {\r\n        this._allocator = new GaussianSplattingBlockAllocator(capacity);\r\n        this._cooldownFrames = Math.max(0, cooldownFrames);\r\n        this._onEvict = onEvict;\r\n    }\r\n\r\n    /**\r\n     * Total splat-index capacity.\r\n     */\r\n    public get capacity(): number {\r\n        return this._allocator.capacity;\r\n    }\r\n\r\n    /**\r\n     * Number of files currently resident.\r\n     */\r\n    public get residentCount(): number {\r\n        return this._blocks.size;\r\n    }\r\n\r\n    /**\r\n     * Total free splat capacity (sum of all gaps, which may be fragmented). After {@link compact} an\r\n     * allocation of up to this size is guaranteed to fit.\r\n     */\r\n    public get freeSize(): number {\r\n        return this._allocator.freeSize;\r\n    }\r\n\r\n    /**\r\n     * Whether the given file currently has a block in the work buffer.\r\n     * @param file file index\r\n     * @returns true if resident\r\n     */\r\n    public has(file: number): boolean {\r\n        return this._blocks.has(file);\r\n    }\r\n\r\n    /**\r\n     * The work-buffer splat offset of a resident file, or undefined if not resident.\r\n     * @param file file index\r\n     * @returns the splat offset, or undefined\r\n     */\r\n    public offset(file: number): number | undefined {\r\n        return this._blocks.get(file)?.offset;\r\n    }\r\n\r\n    /**\r\n     * Allocates a contiguous block for a file about to be decoded. If there is no room, evicts files whose\r\n     * eviction cooldown is pending (they are unreferenced) and retries once. Returns the splat offset, or null\r\n     * if it still does not fit (the caller should refuse the decode and keep the node's current LOD).\r\n     * @param file file index\r\n     * @param count number of splats the file needs\r\n     * @returns the allocated splat offset, or null if it cannot fit\r\n     */\r\n    public allocate(file: number, count: number): Nullable<number> {\r\n        const existing = this._blocks.get(file);\r\n        if (existing) {\r\n            return existing.offset;\r\n        }\r\n        let block = this._allocator.allocate(count);\r\n        if (!block) {\r\n            // Evict-to-fit: reclaim every unreferenced (cooldown-scheduled) file, then retry once.\r\n            this._evictAllCooled();\r\n            block = this._allocator.allocate(count);\r\n            if (!block) {\r\n                return null;\r\n            }\r\n        }\r\n        this._blocks.set(file, block);\r\n        return block.offset;\r\n    }\r\n\r\n    /**\r\n     * Allocates a block for a file that must never be evicted (e.g. the environment or padding splat).\r\n     * @param file file index (use a sentinel that cannot collide with real file indices)\r\n     * @param count number of splats\r\n     * @returns the allocated splat offset, or null if it cannot fit\r\n     */\r\n    public pin(file: number, count: number): Nullable<number> {\r\n        const offset = this.allocate(file, count);\r\n        if (offset !== null) {\r\n            this._pinned.add(file);\r\n        }\r\n        return offset;\r\n    }\r\n\r\n    /**\r\n     * Frees a file's block immediately (e.g. when a decode was cancelled before completing). Does not fire\r\n     * {@link onEvict}. No-op for pinned or non-resident files.\r\n     * @param file file index\r\n     */\r\n    public free(file: number): void {\r\n        if (this._pinned.has(file)) {\r\n            return;\r\n        }\r\n        const block = this._blocks.get(file);\r\n        if (!block) {\r\n            return;\r\n        }\r\n        this._allocator.free(block);\r\n        this._blocks.delete(file);\r\n        this._cooldown.delete(file);\r\n    }\r\n\r\n    /**\r\n     * Compacts the resident blocks to defragment free space (capacity is unchanged), returning every block\r\n     * that moved so the caller can relocate the corresponding GPU/CPU splat data. Call when an allocation\r\n     * fails despite sufficient total free space ({@link freeSize}); afterwards that allocation will fit.\r\n     * @returns the relocations to apply (empty when nothing moved)\r\n     */\r\n    public compact(): IResidencyMove[] {\r\n        const before = new Map<number, number>();\r\n        for (const [file, block] of Array.from(this._blocks)) {\r\n            before.set(file, block.offset);\r\n        }\r\n        this._allocator.defrag(0);\r\n        const moves: IResidencyMove[] = [];\r\n        for (const [file, block] of Array.from(this._blocks)) {\r\n            const oldOffset = before.get(file)!;\r\n            if (oldOffset !== block.offset) {\r\n                moves.push({ file, oldOffset, newOffset: block.offset, count: block.size });\r\n            }\r\n        }\r\n        return moves;\r\n    }\r\n\r\n    /**\r\n     * Returns the current resident blocks (file index, splat offset, splat count). Used to relocate GPU/CPU\r\n     * data after {@link compact}.\r\n     * @returns one entry per resident file\r\n     */\r\n    public getResidentBlocks(): Array<{ file: number; offset: number; count: number }> {\r\n        const result: Array<{ file: number; offset: number; count: number }> = [];\r\n        for (const [file, block] of Array.from(this._blocks)) {\r\n            result.push({ file, offset: block.offset, count: block.size });\r\n        }\r\n        return result;\r\n    }\r\n\r\n    /**\r\n     * Schedules an unreferenced resident file for eviction after the cooldown. No-op for pinned or\r\n     * non-resident files.\r\n     * @param file file index\r\n     */\r\n    public scheduleEviction(file: number): void {\r\n        if (this._pinned.has(file) || !this._blocks.has(file)) {\r\n            return;\r\n        }\r\n        this._cooldown.set(file, this._cooldownFrames);\r\n    }\r\n\r\n    /**\r\n     * Cancels a pending eviction because the file was referenced again.\r\n     * @param file file index\r\n     */\r\n    public cancelEviction(file: number): void {\r\n        this._cooldown.delete(file);\r\n    }\r\n\r\n    /**\r\n     * Advances all eviction cooldowns by one frame, evicting any that expire. Each evicted file fires\r\n     * {@link onEvict}.\r\n     * @returns the file indices evicted this tick\r\n     */\r\n    public tick(): number[] {\r\n        if (this._cooldown.size === 0) {\r\n            return [];\r\n        }\r\n        const evicted: number[] = [];\r\n        for (const [file, frames] of Array.from(this._cooldown)) {\r\n            if (frames <= 1) {\r\n                evicted.push(file);\r\n            } else {\r\n                this._cooldown.set(file, frames - 1);\r\n            }\r\n        }\r\n        for (const file of evicted) {\r\n            this._evict(file);\r\n        }\r\n        return evicted;\r\n    }\r\n\r\n    /**\r\n     * Releases all bookkeeping. The allocator and maps are cleared.\r\n     */\r\n    public dispose(): void {\r\n        this._blocks.clear();\r\n        this._cooldown.clear();\r\n        this._pinned.clear();\r\n    }\r\n\r\n    private _evictAllCooled(): void {\r\n        const files = Array.from(this._cooldown.keys());\r\n        for (const file of files) {\r\n            this._evict(file);\r\n        }\r\n    }\r\n\r\n    private _evict(file: number): void {\r\n        const block = this._blocks.get(file);\r\n        if (block) {\r\n            this._allocator.free(block);\r\n            this._blocks.delete(file);\r\n        }\r\n        this._cooldown.delete(file);\r\n        this._onEvict(file);\r\n    }\r\n}\r\n"]}