@babylonjs/loaders 9.13.0 → 9.14.0

package/SPLAT/gaussianSplattingDownloadManager.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Options for {@link GaussianSplattingDownloadManager}.
+ */
+export interface IGaussianSplattingDownloadManagerOptions {
+    /** Maximum number of downloads allowed to run at the same time. PlayCanvas default `2`. */
+    maxConcurrent?: number;
+    /** Number of times a failed download is retried before rejecting. PlayCanvas default `2` (3 attempts total). */
+    maxRetries?: number;
+}
+/** Identifies a group of related downloads so they can be cancelled together. */
+export type DownloadGroupId = string | number;
+/**
+ * Throttles the file downloads issued while streaming a Gaussian Splatting LOD scene.
+ *
+ * Mirrors the PlayCanvas gsplat asset loader: at most {@link maxConcurrent} downloads run at once, the
+ * rest wait in a FIFO queue, each failed download is retried up to {@link maxRetries} times, and requests
+ * are idempotent — concurrent (queued or in-flight) requests for the same URL share a single download.
+ *
+ * Downloads can be tagged with a group id and cancelled together via {@link cancelGroup}: when a node's
+ * target LOD changes before its file finishes loading, the streamer cancels that file's now-unneeded
+ * downloads. Cancellation aborts the underlying HTTP request (a queued download is dropped before it
+ * starts; an in-flight download is aborted and its concurrency slot freed), so no bandwidth is wasted on
+ * data that is no longer needed.
+ *
+ * Without this throttling, every on-demand LOD decode fans out into many parallel image fetches, so the
+ * browser opens dozens of simultaneous connections that compete for bandwidth and delay the splats the
+ * camera actually needs.
+ * @experimental
+ */
+export declare class GaussianSplattingDownloadManager {
+    /** Maximum number of downloads allowed to run at the same time. */
+    readonly maxConcurrent: number;
+    /** Number of times a failed download is retried before rejecting. */
+    readonly maxRetries: number;
+    private _activeCount;
+    private readonly _queue;
+    private readonly _pending;
+    private readonly _groups;
+    private _disposed;
+    /**
+     * Creates a download manager.
+     * @param options concurrency and retry limits
+     */
+    constructor(options?: IGaussianSplattingDownloadManagerOptions);
+    /**
+     * Whether there are no downloads queued or in flight.
+     */
+    get isIdle(): boolean;
+    /**
+     * Downloads a file as an `ArrayBuffer`, queued behind the concurrency cap and retried on failure.
+     * Concurrent requests for the same URL resolve from a single shared download.
+     * @param url the file URL to download
+     * @param groupId optional group tag so related downloads can be cancelled together via {@link cancelGroup}
+     * @returns a promise resolving with the downloaded bytes
+     */
+    loadFileAsync(url: string, groupId?: DownloadGroupId): Promise<ArrayBuffer>;
+    /**
+     * Cancels a single pending download by URL. A queued download is dropped before it starts; an in-flight
+     * download has its underlying HTTP request aborted and its concurrency slot freed. No-op if the URL is
+     * not currently pending.
+     * @param url the URL to cancel
+     */
+    cancel(url: string): void;
+    /**
+     * Cancels every pending download tagged with the given group id.
+     * @param groupId the group whose downloads should be cancelled
+     */
+    cancelGroup(groupId: DownloadGroupId): void;
+    /**
+     * Cancels every queued download and aborts every in-flight download, preventing new downloads from
+     * starting.
+     */
+    dispose(): void;
+    /**
+     * Aborts a task: drops it from the queue (if not started), aborts its in-flight HTTP request (if started),
+     * unwinds its current attempt, settles its promise, and frees its concurrency slot.
+     * @param task the task to abort
+     * @param reason the rejection reason
+     */
+    private _abort;
+    /**
+     * Settles a task exactly once, removing it from the pending map and its group.
+     * @param task the task to settle
+     * @param settleFn resolves or rejects the task's promise
+     */
+    private _settle;
+    /**
+     * Releases a task's concurrency slot exactly once and pumps the queue.
+     * @param task the task whose slot to release
+     */
+    private _releaseSlot;
+    /**
+     * Starts as many queued downloads as the concurrency cap allows.
+     */
+    private _pump;
+    /**
+     * Runs a single download with retries, settling the task's shared promise. The idempotency entry is
+     * removed the moment the task settles so a later request for the same URL starts a fresh download.
+     * @param task the queued download to run
+     */
+    private _runTaskAsync;
+    /**
+     * Performs one download attempt, exposing the request handle (for abort) and an attempt-rejecter on the
+     * task so cancellation can both abort the HTTP request and unwind this awaited attempt.
+     * @param task the download task
+     * @returns a promise resolving with the downloaded bytes
+     */
+    private _downloadAttemptAsync;
+}

package/SPLAT/gaussianSplattingDownloadManager.js

@@ -0,0 +1,241 @@
+import { Tools } from "@babylonjs/core/Misc/tools.js";
+/**
+ * Throttles the file downloads issued while streaming a Gaussian Splatting LOD scene.
+ *
+ * Mirrors the PlayCanvas gsplat asset loader: at most {@link maxConcurrent} downloads run at once, the
+ * rest wait in a FIFO queue, each failed download is retried up to {@link maxRetries} times, and requests
+ * are idempotent — concurrent (queued or in-flight) requests for the same URL share a single download.
+ *
+ * Downloads can be tagged with a group id and cancelled together via {@link cancelGroup}: when a node's
+ * target LOD changes before its file finishes loading, the streamer cancels that file's now-unneeded
+ * downloads. Cancellation aborts the underlying HTTP request (a queued download is dropped before it
+ * starts; an in-flight download is aborted and its concurrency slot freed), so no bandwidth is wasted on
+ * data that is no longer needed.
+ *
+ * Without this throttling, every on-demand LOD decode fans out into many parallel image fetches, so the
+ * browser opens dozens of simultaneous connections that compete for bandwidth and delay the splats the
+ * camera actually needs.
+ * @experimental
+ */
+export class GaussianSplattingDownloadManager {
+    /**
+     * Creates a download manager.
+     * @param options concurrency and retry limits
+     */
+    constructor(options) {
+        this._activeCount = 0;
+        this._queue = [];
+        // Idempotency: maps a URL to its task while the download is queued or in flight. The entry is removed
+        // once the download settles so a later request (after the bytes were consumed) downloads again.
+        this._pending = new Map();
+        // Maps a group id to the set of URLs currently downloading (or queued) under it, for bulk cancellation.
+        this._groups = new Map();
+        this._disposed = false;
+        this.maxConcurrent = Math.max(1, options?.maxConcurrent ?? 2);
+        this.maxRetries = Math.max(0, options?.maxRetries ?? 2);
+    }
+    /**
+     * Whether there are no downloads queued or in flight.
+     */
+    get isIdle() {
+        return this._pending.size === 0;
+    }
+    /**
+     * Downloads a file as an `ArrayBuffer`, queued behind the concurrency cap and retried on failure.
+     * Concurrent requests for the same URL resolve from a single shared download.
+     * @param url the file URL to download
+     * @param groupId optional group tag so related downloads can be cancelled together via {@link cancelGroup}
+     * @returns a promise resolving with the downloaded bytes
+     */
+    async loadFileAsync(url, groupId) {
+        if (this._disposed) {
+            throw new Error("GaussianSplattingDownloadManager has been disposed.");
+        }
+        const existing = this._pending.get(url);
+        if (existing) {
+            return await existing.promise;
+        }
+        const task = {
+            url,
+            groupId,
+            settled: false,
+            cancelled: false,
+            started: false,
+            slotReleased: false,
+        };
+        task.promise = new Promise((resolve, reject) => {
+            task.resolve = resolve;
+            task.reject = reject;
+        });
+        this._pending.set(url, task);
+        if (groupId !== undefined) {
+            let urls = this._groups.get(groupId);
+            if (!urls) {
+                urls = new Set();
+                this._groups.set(groupId, urls);
+            }
+            urls.add(url);
+        }
+        this._queue.push(task);
+        this._pump();
+        return await task.promise;
+    }
+    /**
+     * Cancels a single pending download by URL. A queued download is dropped before it starts; an in-flight
+     * download has its underlying HTTP request aborted and its concurrency slot freed. No-op if the URL is
+     * not currently pending.
+     * @param url the URL to cancel
+     */
+    cancel(url) {
+        const task = this._pending.get(url);
+        if (!task) {
+            return;
+        }
+        this._abort(task, new Error(`GaussianSplattingDownloadManager: download cancelled (${url}).`));
+    }
+    /**
+     * Cancels every pending download tagged with the given group id.
+     * @param groupId the group whose downloads should be cancelled
+     */
+    cancelGroup(groupId) {
+        const urls = this._groups.get(groupId);
+        if (!urls) {
+            return;
+        }
+        // Copy first: cancel() mutates the group set as each URL settles.
+        for (const url of Array.from(urls)) {
+            this.cancel(url);
+        }
+        this._groups.delete(groupId);
+    }
+    /**
+     * Cancels every queued download and aborts every in-flight download, preventing new downloads from
+     * starting.
+     */
+    dispose() {
+        if (this._disposed) {
+            return;
+        }
+        this._disposed = true;
+        this._queue.length = 0;
+        for (const task of Array.from(this._pending.values())) {
+            this._abort(task, new Error("GaussianSplattingDownloadManager has been disposed."));
+        }
+    }
+    /**
+     * Aborts a task: drops it from the queue (if not started), aborts its in-flight HTTP request (if started),
+     * unwinds its current attempt, settles its promise, and frees its concurrency slot.
+     * @param task the task to abort
+     * @param reason the rejection reason
+     */
+    _abort(task, reason) {
+        if (task.settled) {
+            return;
+        }
+        task.cancelled = true;
+        const queueIndex = this._queue.indexOf(task);
+        if (queueIndex !== -1) {
+            this._queue.splice(queueIndex, 1);
+        }
+        // Abort the underlying HTTP request (no-op for a queued task whose request has not been created).
+        task.request?.abort();
+        // abort() does not fire the error callback, so unwind the awaited attempt explicitly.
+        task.cancelAttempt?.(reason);
+        this._settle(task, () => task.reject(reason));
+        if (task.started) {
+            this._releaseSlot(task);
+        }
+    }
+    /**
+     * Settles a task exactly once, removing it from the pending map and its group.
+     * @param task the task to settle
+     * @param settleFn resolves or rejects the task's promise
+     */
+    _settle(task, settleFn) {
+        if (task.settled) {
+            return;
+        }
+        task.settled = true;
+        this._pending.delete(task.url);
+        if (task.groupId !== undefined) {
+            const urls = this._groups.get(task.groupId);
+            if (urls) {
+                urls.delete(task.url);
+                if (urls.size === 0) {
+                    this._groups.delete(task.groupId);
+                }
+            }
+        }
+        settleFn();
+    }
+    /**
+     * Releases a task's concurrency slot exactly once and pumps the queue.
+     * @param task the task whose slot to release
+     */
+    _releaseSlot(task) {
+        if (task.slotReleased) {
+            return;
+        }
+        task.slotReleased = true;
+        this._activeCount--;
+        this._pump();
+    }
+    /**
+     * Starts as many queued downloads as the concurrency cap allows.
+     */
+    _pump() {
+        while (!this._disposed && this._activeCount < this.maxConcurrent && this._queue.length > 0) {
+            const task = this._queue.shift();
+            if (task.settled) {
+                continue;
+            }
+            task.started = true;
+            this._activeCount++;
+            void this._runTaskAsync(task).finally(() => {
+                this._releaseSlot(task);
+            });
+        }
+    }
+    /**
+     * Runs a single download with retries, settling the task's shared promise. The idempotency entry is
+     * removed the moment the task settles so a later request for the same URL starts a fresh download.
+     * @param task the queued download to run
+     */
+    async _runTaskAsync(task) {
+        let lastError;
+        // attempt 0 is the initial try; attempts 1..maxRetries are retries (PlayCanvas retries immediately).
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            if (this._disposed || task.cancelled) {
+                return;
+            }
+            try {
+                // eslint-disable-next-line no-await-in-loop
+                const buffer = await this._downloadAttemptAsync(task);
+                this._settle(task, () => task.resolve(buffer));
+                return;
+            }
+            catch (e) {
+                task.cancelAttempt = undefined;
+                if (this._disposed || task.cancelled) {
+                    // The task was already settled by cancel()/dispose(); just stop retrying.
+                    return;
+                }
+                lastError = e;
+            }
+        }
+        this._settle(task, () => task.reject(lastError));
+    }
+    /**
+     * Performs one download attempt, exposing the request handle (for abort) and an attempt-rejecter on the
+     * task so cancellation can both abort the HTTP request and unwind this awaited attempt.
+     * @param task the download task
+     * @returns a promise resolving with the downloaded bytes
+     */
+    async _downloadAttemptAsync(task) {
+        return await new Promise((resolve, reject) => {
+            task.cancelAttempt = reject;
+            task.request = Tools.LoadFile(task.url, (data) => resolve(data), undefined, undefined, true, (_request, exception) => reject(exception instanceof Error ? exception : new Error(`GaussianSplattingDownloadManager: failed to load ${task.url}.`)));
+        });
+    }
+}
+//# sourceMappingURL=gaussianSplattingDownloadManager.js.map

package/SPLAT/gaussianSplattingDownloadManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gaussianSplattingDownloadManager.js","sourceRoot":"","sources":["../../../../dev/loaders/src/SPLAT/gaussianSplattingDownloadManager.ts"],"names":[],"mappings":"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","sourcesContent":["import { Tools } from \"core/Misc/tools\";\r\nimport { type IFileRequest } from \"core/Misc/fileRequest\";\r\n\r\n/**\r\n * Options for {@link GaussianSplattingDownloadManager}.\r\n */\r\nexport interface IGaussianSplattingDownloadManagerOptions {\r\n    /** Maximum number of downloads allowed to run at the same time. PlayCanvas default `2`. */\r\n    maxConcurrent?: number;\r\n    /** Number of times a failed download is retried before rejecting. PlayCanvas default `2` (3 attempts total). */\r\n    maxRetries?: number;\r\n}\r\n\r\n/** Identifies a group of related downloads so they can be cancelled together. */\r\nexport type DownloadGroupId = string | number;\r\n\r\n/**\r\n * A queued, concurrency-capped download task.\r\n */\r\ninterface IDownloadTask {\r\n    url: string;\r\n    groupId?: DownloadGroupId;\r\n    promise: Promise<ArrayBuffer>;\r\n    resolve: (data: ArrayBuffer) => void;\r\n    reject: (reason: any) => void;\r\n    // Set once the task is settled (resolved/rejected/cancelled) so it is never settled twice.\r\n    settled: boolean;\r\n    // Set when the task has been cancelled so an in-flight download discards its eventual result.\r\n    cancelled: boolean;\r\n    // True once the task has been pulled from the queue and counted against the concurrency cap.\r\n    started: boolean;\r\n    // True once the task's concurrency slot has been released (so it is released exactly once).\r\n    slotReleased: boolean;\r\n    // The in-flight HTTP request for the current attempt, used to abort the download on cancellation.\r\n    request?: IFileRequest;\r\n    // Rejects the current attempt's promise so an aborted download unwinds immediately (abort() does not\r\n    // fire the error callback, so the awaited attempt would otherwise hang).\r\n    cancelAttempt?: (reason: any) => void;\r\n}\r\n\r\n/**\r\n * Throttles the file downloads issued while streaming a Gaussian Splatting LOD scene.\r\n *\r\n * Mirrors the PlayCanvas gsplat asset loader: at most {@link maxConcurrent} downloads run at once, the\r\n * rest wait in a FIFO queue, each failed download is retried up to {@link maxRetries} times, and requests\r\n * are idempotent — concurrent (queued or in-flight) requests for the same URL share a single download.\r\n *\r\n * Downloads can be tagged with a group id and cancelled together via {@link cancelGroup}: when a node's\r\n * target LOD changes before its file finishes loading, the streamer cancels that file's now-unneeded\r\n * downloads. Cancellation aborts the underlying HTTP request (a queued download is dropped before it\r\n * starts; an in-flight download is aborted and its concurrency slot freed), so no bandwidth is wasted on\r\n * data that is no longer needed.\r\n *\r\n * Without this throttling, every on-demand LOD decode fans out into many parallel image fetches, so the\r\n * browser opens dozens of simultaneous connections that compete for bandwidth and delay the splats the\r\n * camera actually needs.\r\n * @experimental\r\n */\r\nexport class GaussianSplattingDownloadManager {\r\n    /** Maximum number of downloads allowed to run at the same time. */\r\n    public readonly maxConcurrent: number;\r\n    /** Number of times a failed download is retried before rejecting. */\r\n    public readonly maxRetries: number;\r\n\r\n    private _activeCount = 0;\r\n    private readonly _queue: IDownloadTask[] = [];\r\n    // Idempotency: maps a URL to its task while the download is queued or in flight. The entry is removed\r\n    // once the download settles so a later request (after the bytes were consumed) downloads again.\r\n    private readonly _pending = new Map<string, IDownloadTask>();\r\n    // Maps a group id to the set of URLs currently downloading (or queued) under it, for bulk cancellation.\r\n    private readonly _groups = new Map<DownloadGroupId, Set<string>>();\r\n    private _disposed = false;\r\n\r\n    /**\r\n     * Creates a download manager.\r\n     * @param options concurrency and retry limits\r\n     */\r\n    public constructor(options?: IGaussianSplattingDownloadManagerOptions) {\r\n        this.maxConcurrent = Math.max(1, options?.maxConcurrent ?? 2);\r\n        this.maxRetries = Math.max(0, options?.maxRetries ?? 2);\r\n    }\r\n\r\n    /**\r\n     * Whether there are no downloads queued or in flight.\r\n     */\r\n    public get isIdle(): boolean {\r\n        return this._pending.size === 0;\r\n    }\r\n\r\n    /**\r\n     * Downloads a file as an `ArrayBuffer`, queued behind the concurrency cap and retried on failure.\r\n     * Concurrent requests for the same URL resolve from a single shared download.\r\n     * @param url the file URL to download\r\n     * @param groupId optional group tag so related downloads can be cancelled together via {@link cancelGroup}\r\n     * @returns a promise resolving with the downloaded bytes\r\n     */\r\n    public async loadFileAsync(url: string, groupId?: DownloadGroupId): Promise<ArrayBuffer> {\r\n        if (this._disposed) {\r\n            throw new Error(\"GaussianSplattingDownloadManager has been disposed.\");\r\n        }\r\n        const existing = this._pending.get(url);\r\n        if (existing) {\r\n            return await existing.promise;\r\n        }\r\n        const task: IDownloadTask = {\r\n            url,\r\n            groupId,\r\n            settled: false,\r\n            cancelled: false,\r\n            started: false,\r\n            slotReleased: false,\r\n        } as IDownloadTask;\r\n        task.promise = new Promise<ArrayBuffer>((resolve, reject) => {\r\n            task.resolve = resolve;\r\n            task.reject = reject;\r\n        });\r\n        this._pending.set(url, task);\r\n        if (groupId !== undefined) {\r\n            let urls = this._groups.get(groupId);\r\n            if (!urls) {\r\n                urls = new Set<string>();\r\n                this._groups.set(groupId, urls);\r\n            }\r\n            urls.add(url);\r\n        }\r\n        this._queue.push(task);\r\n        this._pump();\r\n        return await task.promise;\r\n    }\r\n\r\n    /**\r\n     * Cancels a single pending download by URL. A queued download is dropped before it starts; an in-flight\r\n     * download has its underlying HTTP request aborted and its concurrency slot freed. No-op if the URL is\r\n     * not currently pending.\r\n     * @param url the URL to cancel\r\n     */\r\n    public cancel(url: string): void {\r\n        const task = this._pending.get(url);\r\n        if (!task) {\r\n            return;\r\n        }\r\n        this._abort(task, new Error(`GaussianSplattingDownloadManager: download cancelled (${url}).`));\r\n    }\r\n\r\n    /**\r\n     * Cancels every pending download tagged with the given group id.\r\n     * @param groupId the group whose downloads should be cancelled\r\n     */\r\n    public cancelGroup(groupId: DownloadGroupId): void {\r\n        const urls = this._groups.get(groupId);\r\n        if (!urls) {\r\n            return;\r\n        }\r\n        // Copy first: cancel() mutates the group set as each URL settles.\r\n        for (const url of Array.from(urls)) {\r\n            this.cancel(url);\r\n        }\r\n        this._groups.delete(groupId);\r\n    }\r\n\r\n    /**\r\n     * Cancels every queued download and aborts every in-flight download, preventing new downloads from\r\n     * starting.\r\n     */\r\n    public dispose(): void {\r\n        if (this._disposed) {\r\n            return;\r\n        }\r\n        this._disposed = true;\r\n        this._queue.length = 0;\r\n        for (const task of Array.from(this._pending.values())) {\r\n            this._abort(task, new Error(\"GaussianSplattingDownloadManager has been disposed.\"));\r\n        }\r\n    }\r\n\r\n    /**\r\n     * Aborts a task: drops it from the queue (if not started), aborts its in-flight HTTP request (if started),\r\n     * unwinds its current attempt, settles its promise, and frees its concurrency slot.\r\n     * @param task the task to abort\r\n     * @param reason the rejection reason\r\n     */\r\n    private _abort(task: IDownloadTask, reason: any): void {\r\n        if (task.settled) {\r\n            return;\r\n        }\r\n        task.cancelled = true;\r\n        const queueIndex = this._queue.indexOf(task);\r\n        if (queueIndex !== -1) {\r\n            this._queue.splice(queueIndex, 1);\r\n        }\r\n        // Abort the underlying HTTP request (no-op for a queued task whose request has not been created).\r\n        task.request?.abort();\r\n        // abort() does not fire the error callback, so unwind the awaited attempt explicitly.\r\n        task.cancelAttempt?.(reason);\r\n        this._settle(task, () => task.reject(reason));\r\n        if (task.started) {\r\n            this._releaseSlot(task);\r\n        }\r\n    }\r\n\r\n    /**\r\n     * Settles a task exactly once, removing it from the pending map and its group.\r\n     * @param task the task to settle\r\n     * @param settleFn resolves or rejects the task's promise\r\n     */\r\n    private _settle(task: IDownloadTask, settleFn: () => void): void {\r\n        if (task.settled) {\r\n            return;\r\n        }\r\n        task.settled = true;\r\n        this._pending.delete(task.url);\r\n        if (task.groupId !== undefined) {\r\n            const urls = this._groups.get(task.groupId);\r\n            if (urls) {\r\n                urls.delete(task.url);\r\n                if (urls.size === 0) {\r\n                    this._groups.delete(task.groupId);\r\n                }\r\n            }\r\n        }\r\n        settleFn();\r\n    }\r\n\r\n    /**\r\n     * Releases a task's concurrency slot exactly once and pumps the queue.\r\n     * @param task the task whose slot to release\r\n     */\r\n    private _releaseSlot(task: IDownloadTask): void {\r\n        if (task.slotReleased) {\r\n            return;\r\n        }\r\n        task.slotReleased = true;\r\n        this._activeCount--;\r\n        this._pump();\r\n    }\r\n\r\n    /**\r\n     * Starts as many queued downloads as the concurrency cap allows.\r\n     */\r\n    private _pump(): void {\r\n        while (!this._disposed && this._activeCount < this.maxConcurrent && this._queue.length > 0) {\r\n            const task = this._queue.shift()!;\r\n            if (task.settled) {\r\n                continue;\r\n            }\r\n            task.started = true;\r\n            this._activeCount++;\r\n            void this._runTaskAsync(task).finally(() => {\r\n                this._releaseSlot(task);\r\n            });\r\n        }\r\n    }\r\n\r\n    /**\r\n     * Runs a single download with retries, settling the task's shared promise. The idempotency entry is\r\n     * removed the moment the task settles so a later request for the same URL starts a fresh download.\r\n     * @param task the queued download to run\r\n     */\r\n    private async _runTaskAsync(task: IDownloadTask): Promise<void> {\r\n        let lastError: any;\r\n        // attempt 0 is the initial try; attempts 1..maxRetries are retries (PlayCanvas retries immediately).\r\n        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {\r\n            if (this._disposed || task.cancelled) {\r\n                return;\r\n            }\r\n            try {\r\n                // eslint-disable-next-line no-await-in-loop\r\n                const buffer = await this._downloadAttemptAsync(task);\r\n                this._settle(task, () => task.resolve(buffer));\r\n                return;\r\n            } catch (e) {\r\n                task.cancelAttempt = undefined;\r\n                if (this._disposed || task.cancelled) {\r\n                    // The task was already settled by cancel()/dispose(); just stop retrying.\r\n                    return;\r\n                }\r\n                lastError = e;\r\n            }\r\n        }\r\n        this._settle(task, () => task.reject(lastError));\r\n    }\r\n\r\n    /**\r\n     * Performs one download attempt, exposing the request handle (for abort) and an attempt-rejecter on the\r\n     * task so cancellation can both abort the HTTP request and unwind this awaited attempt.\r\n     * @param task the download task\r\n     * @returns a promise resolving with the downloaded bytes\r\n     */\r\n    private async _downloadAttemptAsync(task: IDownloadTask): Promise<ArrayBuffer> {\r\n        return await new Promise<ArrayBuffer>((resolve, reject) => {\r\n            task.cancelAttempt = reject;\r\n            task.request = Tools.LoadFile(\r\n                task.url,\r\n                (data) => resolve(data as ArrayBuffer),\r\n                undefined,\r\n                undefined,\r\n                true,\r\n                (_request, exception) => reject(exception instanceof Error ? exception : new Error(`GaussianSplattingDownloadManager: failed to load ${task.url}.`))\r\n            );\r\n        });\r\n    }\r\n}\r\n"]}

package/SPLAT/gaussianSplattingResidencyController.d.ts

@@ -0,0 +1,133 @@
+import { type Nullable } from "@babylonjs/core/types.js";
+/**
+ * One resident block relocation produced by {@link GaussianSplattingResidencyController.compact}: the file's
+ * splat data must be moved from `oldOffset` to `newOffset` (`count` splats) in the work buffer.
+ */
+export interface IResidencyMove {
+    /** File index whose splat data must move. */
+    file: number;
+    /** The file's previous splat offset in the work buffer. */
+    oldOffset: number;
+    /** The file's new splat offset after compaction. */
+    newOffset: number;
+    /** Number of splats in the file. */
+    count: number;
+}
+/**
+ * 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 declare class GaussianSplattingResidencyController {
+    private readonly _allocator;
+    private readonly _blocks;
+    private readonly _cooldown;
+    private readonly _pinned;
+    private readonly _cooldownFrames;
+    private readonly _onEvict;
+    /**
+     * 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: number, cooldownFrames: number, onEvict: (file: number) => void);
+    /**
+     * Total splat-index capacity.
+     */
+    get capacity(): number;
+    /**
+     * Number of files currently resident.
+     */
+    get residentCount(): number;
+    /**
+     * 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(): number;
+    /**
+     * Whether the given file currently has a block in the work buffer.
+     * @param file file index
+     * @returns true if resident
+     */
+    has(file: number): boolean;
+    /**
+     * 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: number): number | undefined;
+    /**
+     * 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: number, count: number): Nullable<number>;
+    /**
+     * 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: number, count: number): Nullable<number>;
+    /**
+     * 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: number): void;
+    /**
+     * 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(): IResidencyMove[];
+    /**
+     * 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(): Array<{
+        file: number;
+        offset: number;
+        count: number;
+    }>;
+    /**
+     * Schedules an unreferenced resident file for eviction after the cooldown. No-op for pinned or
+     * non-resident files.
+     * @param file file index
+     */
+    scheduleEviction(file: number): void;
+    /**
+     * Cancels a pending eviction because the file was referenced again.
+     * @param file file index
+     */
+    cancelEviction(file: number): void;
+    /**
+     * 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(): number[];
+    /**
+     * Releases all bookkeeping. The allocator and maps are cleared.
+     */
+    dispose(): void;
+    private _evictAllCooled;
+    private _evict;
+}