playcanvas
Version:
PlayCanvas WebGL game engine
185 lines (184 loc) • 8.05 kB
TypeScript
export class GSplatOctreeInstance {
/**
* @param {GSplatOctree} octree - The octree.
* @param {GSplatPlacement} placement - The placement.
* @param {GSplatAssetLoaderBase} assetLoader - The asset loader.
*/
constructor(octree: GSplatOctree, placement: GSplatPlacement, assetLoader: GSplatAssetLoaderBase);
/** @type {GSplatOctree} */
octree: GSplatOctree;
/** @type {GSplatPlacement} */
placement: GSplatPlacement;
/** @type {Set<GSplatPlacement>} */
activePlacements: Set<GSplatPlacement>;
/** @type {boolean} */
dirtyModifiedPlacements: boolean;
/** @type {GSplatAssetLoaderBase} */
assetLoader: GSplatAssetLoaderBase;
/**
* Array of current LOD index per node. Index is nodeIndex, value is lodIndex.
* Value -1 indicates node is not visible.
* @type {Int32Array}
*/
nodeLods: Int32Array;
/**
* 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<number>}
*/
pending: Set<number>;
/**
* Map of nodeIndex -> { oldFileIndex, newFileIndex } that needs to be decremented when the
* new LOD resource loads. This ensures we decrement even if the node switches LOD again
* before the new resource arrives.
*
* @type {Map<number, { oldFileIndex: number, newFileIndex: number }>}
*/
pendingDecrements: Map<number, {
oldFileIndex: number;
newFileIndex: number;
}>;
/**
* Files that became unused by this instance this update. Each entry represents a single decRef.
*
* @type {Set<number>}
*/
removedCandidates: Set<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.
*
* @type {Vec3}
*/
previousPosition: Vec3;
/**
* Set when a resource has completed loading and LOD should be re-evaluated.
*
* @type {boolean}
*/
needsLodUpdate: boolean;
/**
* Tracks prefetched file indices that are being loaded without active placements.
* When any completes, we trigger LOD re-evaluation to allow promotion.
*
* @type {Set<number>}
*/
prefetchPending: Set<number>;
/**
* Tracks invisible->visible pending adds per node: nodeIndex -> fileIndex.
* Ensures only a single pending placement exists for a node while it's not yet displayed.
* @type {Map<number, number>}
*/
pendingVisibleAdds: Map<number, number>;
/**
* Destroys this octree instance and clears internal references.
*/
destroy(): void;
/**
* 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[];
/**
* Calculate LOD index for a specific node using pre-calculated local camera position.
* @param {Vec3} localCameraPosition - The camera position in local space.
* @param {Vec3} localCameraForward - The camera forward direction in local space (normalized).
* @param {number} nodeIndex - The node index.
* @param {number} maxLod - The maximum LOD index (lodLevels - 1).
* @param {number[]} lodDistances - Array of distance thresholds per LOD.
* @param {number} lodBehindPenalty - Multiplier for behind-camera distance. 1 disables penalty.
* @returns {number} The LOD index for this node, or -1 if node should not be rendered.
*/
calculateNodeLod(localCameraPosition: Vec3, localCameraForward: Vec3, nodeIndex: number, maxLod: number, lodDistances: number[], lodBehindPenalty: number): number;
/**
* Selects desired LOD index for a node using the underfill strategy. When underfill is enabled,
* it prefers already-loaded LODs within [optimalLodIndex .. optimalLodIndex + lodUnderfillLimit].
* If none are loaded, it selects the coarsest available LOD within the range.
*
* @param {import('./gsplat-octree-node.js').GSplatOctreeNode} node - The octree node.
* @param {number} optimalLodIndex - Optimal LOD index based on camera/distance.
* @param {number} maxLod - Maximum LOD index.
* @param {number} lodUnderfillLimit - Allowed coarse range above optimal.
* @returns {number} Desired LOD index to display.
*/
selectDesiredLodIndex(node: import("./gsplat-octree-node.js").GSplatOctreeNode, optimalLodIndex: number, maxLod: number, lodUnderfillLimit: number): number;
/**
* Prefetch only the next-better LOD toward optimal. This stages loading in steps across all
* nodes, avoiding intermixing requests before coarse is present.
*
* @param {import('./gsplat-octree-node.js').GSplatOctreeNode} node - The octree node.
* @param {number} desiredLodIndex - Currently selected LOD for display (may be coarser than optimal).
* @param {number} optimalLodIndex - Target optimal LOD.
*/
prefetchNextLod(node: import("./gsplat-octree-node.js").GSplatOctreeNode, desiredLodIndex: number, optimalLodIndex: number): void;
/**
* Updates the octree instance when LOD needs to be updated.
*
* @param {GraphNode} cameraNode - The camera node.
* @param {import('./gsplat-params.js').GSplatParams} params - Global gsplat parameters.
*/
updateLod(cameraNode: GraphNode, 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.
*
* @param {Scene} scene - Optional scene for debug rendering.
* @returns {boolean} True if octree instance is dirty, false otherwise.
*/
update(scene: Scene): 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;
}
import type { GSplatOctree } from './gsplat-octree.js';
import { GSplatPlacement } from './gsplat-placement.js';
import type { GSplatAssetLoaderBase } from './gsplat-asset-loader-base.js';
import { Vec3 } from '../../core/math/vec3.js';
import type { GraphNode } from '../graph-node.js';
import type { Scene } from '../scene.js';