export class GSplatOctreeInstance { /** * @param {GraphicsDevice} device - The graphics device. * @param {GSplatOctree} octree - The octree. * @param {GSplatPlacement} placement - The placement. */ constructor(device: GraphicsDevice, octree: GSplatOctree, placement: GSplatPlacement); /** @type {GSplatOctree} */ octree: GSplatOctree; /** @type {GSplatPlacement} */ placement: GSplatPlacement; /** @type {Set} */ activePlacements: Set; /** @type {boolean} */ dirtyModifiedPlacements: boolean; /** * Set to true when placements are added or removed, signaling that the manager needs to * create a new world state and trigger a full work buffer rebuild. */ dirtyPlacementSetChanged: boolean; /** @type {GraphicsDevice} */ device: GraphicsDevice; /** * Array of NodeInfo instances, one per octree node. * * @type {NodeInfo[]} */ nodeInfos: NodeInfo[]; /** * Array of current placements per file. Index is fileIndex, value is GSplatPlacement or null. * Value null indicates file is not used / no placement. * * @type {(GSplatPlacement|null)[]} */ filePlacements: (GSplatPlacement | null)[]; /** * Set of pending file loads (file indices). * * @type {Set} */ pending: Set; /** * Files that became unused by this instance this update. Each entry represents a single decRef. * * @type {Set} */ removedCandidates: Set; /** * Minimum allowed LOD index for this instance, clamped to valid octree bounds. */ rangeMin: number; /** * Maximum allowed LOD index for this instance, clamped to valid octree bounds. */ rangeMax: number; /** * Previous node position at which LOD was last updated. This is used to determine if LOD needs * to be updated as the octree splat moves. */ previousPosition: Vec3; /** * Set when a resource has completed loading and LOD should be re-evaluated. */ needsLodUpdate: boolean; /** * Tracks prefetched file indices that are being loaded without active placements, rebuilt on * every LOD update. When any completes, we trigger LOD re-evaluation to allow promotion. * * @type {Set} */ prefetchPending: Set; /** * Files this instance waits for, mapped to their load priority. Rebuilt on every LOD update * and submitted to the octree, which combines the requests of all its instances. * * @type {Map} * @private */ private _fileRequests; /** * Camera position and forward in octree local space, everything that scales a node's distance * squared, and the behind-camera penalty, as {@link GSplatOctreeInstance#prepareDistances} set * them for the current LOD update. * * @type {Vec3} * @private */ private _cameraPos; /** * @type {Vec3} * @private */ private _cameraFwd; /** @private */ private _distanceScaleSq; /** @private */ private _penalty; /** * Number of the current cut through the octree, chosen by GSplatBudgetBalancer#balance. The * per-node state of a cut is valid for the nodes stamped with it, so nothing has to be cleared * between cuts. * * @type {number} */ treeStamp: number; /** * Per node, the {@link GSplatOctreeInstance#treeStamp} of the last cut that refined it. * * @type {Uint32Array|null} */ treeRefined: Uint32Array | null; /** * Per node, its position on the allocator's scale axis in the last cut that reached it, see * GSplatBudgetBalancer. * * @type {Float64Array|null} */ treePosition: Float64Array | null; /** * The size of a band and this instance's offset on the allocator's scale axis, for the * current cut. * * @type {number} */ treeStep: number; /** @type {number} */ treeOffset: number; /** * Where on the scale axis the current cut stopped: the switch points before it are taken. * * @type {number} */ treeCutStop: number; /** * Memoized per-node answers of the current cut's walk - whether a node is loaded, can render its * region from loaded data, or can render it within the underfill limit - each valid where its * stamp is the current {@link GSplatOctreeInstance#treeStamp}. * * @type {Uint32Array|null} * @private */ private _treeLoadedStamp; /** @private */ private _treeLoaded; /** @private */ private _treeCoverStamp; /** @private */ private _treeCover; /** @private */ private _treeWithinStamp; /** @private */ private _treeWithin; /** * Stack of the cut's walk, its nodes and how the walk reached them, one of the CUT_* values. * * @type {Int32Array|null} * @private */ private _treeStack; /** @private */ private _treeStackState; /** * The nodes the last cut rendered, and those the current one renders, so applying a cut only * touches the nodes it changes. * * @type {Int32Array|null} * @private */ private _drawn; /** @private */ private _drawnCount; /** @private */ private _drawnNext; /** * The nodes the last cut asked for whose data is not loaded yet, drawn by the node AABB debug * view. Recorded in debug builds only. * * @type {Int32Array|null} * @private */ private _debugWaiting; /** @private */ private _debugWaitingCount; /** * Per node, the {@link GSplatOctreeInstance#treeStamp} of the last cut that rendered it. * * @type {Uint32Array|null} * @private */ private _drawStamp; /** * The loaded files the last cut holds a reference to without rendering them: the finer data * of a region a coarser node renders in place of until the rest of that data loads. So data * that loads first is not unloaded by its cooldown while it waits for the rest. * * @type {Int32Array|null} * @private */ private _retained; /** @private */ private _retainedCount; /** @private */ private _retainedNext; /** @private */ private _retainedNextCount; /** * Per file, the {@link GSplatOctreeInstance#treeStamp} of the last cut that retained it. * * @type {Uint32Array|null} * @private */ private _retainStamp; /** * Per file, 1 while this instance holds a reference to it in {@link GSplatOctreeInstance#_retained}. * * @type {Uint8Array|null} * @private */ private _retainHeld; /** * Returns the count of resources pending load or prefetch, including environment if loading. * * @type {number} */ get pendingLoadCount(): number; /** * Environment placement. * * @type {GSplatPlacement|null} */ environmentPlacement: GSplatPlacement | null; /** * Event handle for device lost event. * * @type {EventHandle|null} * @private */ private _deviceLostEvent; /** * Destroys this octree instance and clears internal references. * * @param {boolean} [skipRefCounting] - When true, skip decrementing file ref counts * on the octree. Used when the caller handles ref counting externally via pendingReleases * (e.g. during world state updates where decrements must be deferred). */ destroy(skipRefCounting?: boolean): void; /** * Handles device lost event by releasing all loaded resources. * * @private */ private _onDeviceLost; /** * Returns the file indices currently referenced by this instance that should be decremented * when the instance is destroyed. * * @returns {number[]} Array of file indices to decRef. */ getFileDecrements(): number[]; /** * Requests the file of a node, and watches it so that the cut is chosen again once it loads. * * @param {number} nodeIndex - The node. * @param {number} tier - The load tier, one of the LOAD_TIER_* values. * @private */ private _requestCutNode; /** * Starts a cut through this instance's octree, chosen by GSplatBudgetBalancer#balance for the * current LOD update. * * @param {number} step - The size of a band on the allocator's scale axis. * @param {number} offset - This instance's offset on the scale axis. */ beginTreeCut(step: number, offset: number): void; /** * Measures and records the squared world distance from the camera to one node, with the FOV * compensation and the behind-camera penalty folded in. It is the only way camera position * influences LOD selection, and what orders the loads of one LOD level. Distance is measured to * the nearest point of the node's bounds, the same way under both projections - an orthographic * footprint carries no depth term, so this is what gives it a distance ordering at all. * * A node is never nearer than its parent, which the cut measures first: the allocator relies on * a child never asking for more detail than its parent. Nested bounds give that on their own, * but the behind-camera penalty depends on direction, so it can raise a parent above its child. * * @param {number} n - The node. * @returns {number} The squared distance. */ measureTreeNode(n: number): number; /** * Whether a node reached by the current cut is loaded, or has no data to load. Polls the * loader, so a file that finished loading is seen. * * @param {number} n - The node. * @returns {boolean} True when the node can render. * @private */ private _isTreeNodeLoaded; /** * Whether a node's region can render from any loaded data right now - its own, or that of nodes * below it. Skips the subtrees with nothing loaded, see GSplatOctree#loadedBelow. * * @param {number} n - The node. * @returns {boolean} True when the region is coverable. * @private */ private _isTreeCoverable; /** * Whether a node's region can render from loaded data no finer than the current cut asks for, * and no more than `underfillLimit` levels coarser than its distance asks for. Only follows the * nodes the cut refines, which it has measured. * * @param {number} n - A node the cut reached. * @param {number} underfillLimit - See GSplatParams#lodUnderfillLimit. * @returns {boolean} True when the region is within the limit. * @private */ private _isTreeWithinLimit; /** * The LOD band the current cut gives a node it measured: the level its distance asks for at the * scale the cut stopped at. * * @param {number} n - The node. * @returns {number} The band, an absolute LOD index within the range. * @private */ private _treeBand; /** * Renders the cut GSplatBudgetBalancer#balance chose, walking only the nodes it reached and the * loaded data below them it falls back on, and applies it to the nodes whose state it changes - * the cost follows the size of the cut, not of the octree. * * A node the allocator refines hands its region to its children, and the walk from the top * level down renders the first node on each path it does not refine. The nodes rendered this * way cover the scene exactly once. * * Only loaded data is ever rendered, so a change of the cut takes effect at once, in one world * state, with no frame showing a region twice or not at all. While the cut streams in, a region * whose nodes are not loaded renders other loaded data instead, preferring coarser data: * - A node coarser than asked for renders while the nodes it refines to load, when it is no more * than `underfillLimit` levels coarser than its distance asks for. So when the cut gets coarser, * a loaded ancestor of the nodes it moves to renders until they load, and the splat count stays * within the plan. * - Otherwise the finer loaded data below the region renders until the nodes it moves to load, * as when no coarser data within the limit is loaded, or the limit is 0. * - A node renders however much coarser than asked for when nothing finer is loaded, so the * view streams in coarse to fine one level at a time. Only the parts of the scene with nothing * loaded at all, as at the start, render nothing. * * @param {number} underfillLimit - See GSplatParams#lodUnderfillLimit. * @private */ private _applyTreeCut; /** * Retains the loaded data of a region a coarser node renders in place of until the rest of the * region loads: every loaded node the cut reaches in it. Once the rest loads, the cut can render * any of them - the nodes it refines to, or coarser ones in place of those still loading. * * @param {number} n - A node the cut reached. * @private */ private _retainRegion; /** * Releases the files the cut retains. * * @param {number} cooldownTicks - See GSplatOctree#decRefCount. * @private */ private _releaseRetained; /** * Requests a file for this LOD update, unless it is already loaded. A file requested more than * once keeps its highest priority. * * The priority is ranked by tier first. Within a tier, coarser LOD levels load first, so the * whole view refines one level at a time instead of the nearest nodes refining all the way * before farther ones get their first step. Within a level, nearer loads first. * * @param {number} fileIndex - The file index. * @param {number} tier - The load tier, one of the LOAD_TIER_* values. * @param {number} distanceRank - The requesting node's distance mapped monotonically into * [0, 1), higher is nearer. * @returns {boolean} True if the file is already loaded. */ requestFile(fileIndex: number, tier: number, distanceRank: number): boolean; /** * Resolves the configured LOD range against the octree. Called before the budget allocator, so * it sees the current range. */ resolveLodRange(): void; /** * Prepares the camera terms of a LOD update: the camera position and forward in octree local * space, everything that scales a node's distance squared, and the behind-camera penalty. The * cut uses them to measure only the nodes it reaches, see * {@link GSplatOctreeInstance#measureTreeNode}. * * @param {GraphNode} cameraNode - The camera node. * @param {import('./gsplat-params.js').GSplatParams} params - Global gsplat parameters. */ prepareDistances(cameraNode: GraphNode, params: import("./gsplat-params.js").GSplatParams): void; /** * Applies the cut the budget allocator chose, see {@link GSplatOctreeInstance#_applyTreeCut}, * and manages file placements. This is Pass 2 of the LOD update process. * * Also requests every file this instance waits for, with a load priority. The priority is * ranked by tier first - a region that shows nothing yet, then a node waiting for the nodes it * switches to - and within a tier by LOD level, coarsest first, and then by the node's * {@link NodeInfo#worldDistanceSq}. So the view fills with coarse data first and then refines one * level at a time across the whole view, each level nearest the camera first. A file shared by * several nodes takes the highest priority of them. The requests are submitted to the octree, * which combines them with those of its other instances and issues them in * {@link GSplatOctree#flushRequests}. * * @param {import('./gsplat-params.js').GSplatParams} params - Global gsplat parameters. */ applyLodChanges(params: import("./gsplat-params.js").GSplatParams): void; /** * Increments reference count for a file and creates placement immediately. * * @param {number} fileIndex - The file index. * @param {number} nodeIndex - The octree node index. * @param {number} lodIndex - The LOD index for this node. */ incrementFileRef(fileIndex: number, nodeIndex: number, lodIndex: number): void; /** * Decrements reference count for a file and removes placement if needed. * * @param {number} fileIndex - The file index. * @param {number} nodeIndex - The octree node index. */ decrementFileRef(fileIndex: number, nodeIndex: number): void; /** * Updates existing placement with loaded resource and adds to manager. * * @param {number} fileIndex - The file index. * @returns {boolean} True if placement was updated and added to manager, false otherwise. */ addFilePlacement(fileIndex: number): boolean; /** * Tests if the octree instance has moved by more than the provided LOD update distance. * * @param {number} threshold - Distance threshold to trigger an update. * @returns {boolean} True if the octree instance has moved by more than the threshold, false otherwise. */ testMoved(threshold: number): boolean; /** * Updates the previous position of the octree instance. */ updateMoved(): void; /** * Updates the octree instance each frame. * * @returns {boolean} True if octree instance is dirty, false otherwise. */ update(): boolean; /** * Consumes and returns whether the active placement set membership changed (add/remove). * * @returns {boolean} True if placements were added or removed since last call. */ consumePlacementSetChanged(): boolean; debugRender(scene: any): void; /** * Returns true if this instance requests LOD re-evaluation and resets the flag. * * @returns {boolean} True if LOD should be re-evaluated. */ consumeNeedsLodUpdate(): boolean; /** * Polls prefetched file indices for completion and updates state. */ pollPrefetchCompletions(): void; } /** * Stores LOD state for a single octree node. * * @ignore */ export class NodeInfo { /** * Current LOD index being rendered. -1 indicates node is not visible. */ currentLod: number; /** * Squared world-space distance from the camera to this node, with the FOV compensation and * the behind-camera penalty folded in. The only way camera position influences LOD selection, * and what orders loads of the same LOD level within a priority tier. Kept squared so the * per-node pass needs no square root - every consumer works in squared or log space. */ worldDistanceSq: number; /** * Accumulated camera translation for SH color update threshold tracking. */ colorAccumulatedTranslation: number; /** * Back-reference to owning GSplatOctreeInstance. * * @type {GSplatOctreeInstance|null} */ inst: GSplatOctreeInstance | null; /** * Unique allocation identifier for persistent work buffer allocation tracking. * * @type {number} */ allocId: number; /** * Resets the rendered LOD to -1 (invisible). */ resetLod(): void; } import type { GSplatOctree } from './gsplat-octree.js'; import { GSplatPlacement } from './gsplat-placement.js'; import type { GraphicsDevice } from '../../platform/graphics/graphics-device.js'; import { Vec3 } from '../../core/math/vec3.js'; import type { GraphNode } from '../graph-node.js';