/** * Stable Gaussian splat product API. * * The exported constructors are the runtime engine constructors. Their public * declaration shape deliberately omits storage buffers, TSL nodes, compute * passes, caches, and authoring codecs so those implementation details can * remain private behind the stable product contract. * * @module three-blocks/gaussian-splats */ import type * as THREE from 'three/webgpu'; /** Full-quality rendering, the sole preset used by the asynchronous load helpers. */ export type GaussianSplatsQuality = 'quality'; /** Intentional appearance controls applied after a splat asset is loaded. */ export interface GaussianSplatsAppearanceOptions { /** Whether the splats are unlit or participate in scene lighting. */ mode?: 'unlit' | 'lit' | undefined; /** Global opacity multiplier in the inclusive range from zero to one. */ opacity?: number | undefined; /** Image exposure adjustment applied by the default material. */ exposure?: number | undefined; /** Image contrast adjustment applied by the default material. */ contrast?: number | undefined; /** Image saturation adjustment applied by the default material. */ saturation?: number | undefined; /** Perceptual saturation adjustment that favors muted colors. */ vibrance?: number | undefined; /** Roughness used when lit rendering is enabled. */ roughness?: number | undefined; /** Metalness used when lit rendering is enabled. */ metalness?: number | undefined; } /** Construction controls for a manually populated {@link GaussianSplats} object. */ export interface GaussianSplatsOptions { /** Maximum number of source splats accepted by the renderer. */ maxSplats?: number | undefined; /** Maximum byte size permitted for one GPU storage allocation. */ maxBufferBytes?: number | undefined; /** Whether spherical-harmonic view-dependent color is enabled. */ enableSH?: boolean | undefined; /** Spherical-harmonic degree from zero through three. */ shDegree?: number | undefined; /** Whether GPU frustum culling is enabled. */ frustumCulling?: boolean | undefined; /** Whether transparent splats are depth sorted. */ sortEnabled?: boolean | undefined; /** Sort-key interpretation used for transparent ordering. */ sortMode?: 'radial' | 'depth' | undefined; /** Sort-key precision used by the GPU sorter. */ sortPrecision?: 'float16' | 'float32' | undefined; /** GPU sorting strategy. */ sortAlgorithm?: 'radix' | 'bitonic' | undefined; /** Whether an unchanged camera may reuse the previous projection and sort. */ temporalStability?: boolean | undefined; /** Coordinate convention used by the loaded source data. */ coordinateSystem?: 'threejs' | 'source' | undefined; /** Source-attribute storage policy. */ attributeMode?: 'expanded' | 'compact' | 'sog' | 'auto' | undefined; /** Preferred renderer path, with `auto` selecting a supported path. */ rendererMode?: 'auto' | 'raster' | 'compute-tiles' | undefined; /** Alpha representation expected by the default material. */ alphaMode?: 'straight' | 'premultiplied' | undefined; /** Initial lighting behavior of the default material. */ lightingMode?: 'unlit' | 'lit' | undefined; /** * Unlit blend space. `faithful` (default) blends the stored display colors as trained inside a * color-managed renderer; `display` writes them raw and requires `NoToneMapping` with * `LinearSRGBColorSpace` output; `linear` blends in linear light and lifts translucent stacks. */ compositing?: 'faithful' | 'display' | 'linear' | undefined; /** Application-managed render-scale recommendation reported in diagnostics. */ recommendedRenderScale?: number | undefined; /** Optional application-provided material. */ material?: THREE.Material | null | undefined; /** Whether {@link GaussianSplats.dispose} also disposes an application-provided material. */ ownsMaterial?: boolean | undefined; } /** Options shared by URL loading and in-memory parsing. */ export interface GaussianSplatsLoaderOptions extends GaussianSplatsOptions { /** Whether input rows are Morton ordered before upload. */ mortonOrdering?: boolean | undefined; /** Whether parsing uses a worker, or `auto` to use one only for large inputs. */ worker?: boolean | 'auto' | undefined; /** Minimum source byte length at which automatic worker parsing begins. */ workerThreshold?: number | undefined; /** Whether worker parsing may detach the caller-owned source buffer. */ transferSourceBuffer?: boolean | undefined; /** Optional cancellation signal for network and processing work. */ signal?: AbortSignal | undefined; /** Receives deterministic processing-stage progress snapshots. */ onProcessProgress?: (progress: GaussianSplatsProcessingProgress) => void; } /** High-level options for {@link GaussianSplats.load} and {@link GaussianSplats.parse}. */ export interface GaussianSplatsLoadOptions extends GaussianSplatsLoaderOptions { /** Rendering preset; `quality` is the default and only supported value. */ quality?: GaussianSplatsQuality | undefined; /** SH degree, `false` to disable SH, or `auto` to use the asset default. */ sh?: number | boolean | 'auto' | undefined; /** Appearance controls applied after the source is uploaded. */ appearance?: GaussianSplatsAppearanceOptions | undefined; /** Whether scene rendering automatically performs the per-frame update. */ autoUpdate?: boolean | undefined; /** Optional Three.js loading manager used by URL loading. */ manager?: THREE.LoadingManager | undefined; /** Receives network transfer progress for URL loading. */ onProgress?: (event: ProgressEvent) => void; } /** Expanded in-memory attributes accepted by {@link GaussianSplats.setData}. */ export interface GaussianSplatsData { /** Number of valid splats represented by the attribute arrays. */ count: number; /** Three source-space position floats per splat. */ positions: Float32Array; /** Three log-scale floats per splat. */ scales: Float32Array; /** Four quaternion floats per splat. */ rotations: Float32Array; /** Four linear RGBA floats per splat. */ colors: Float32Array; /** Optional flattened spherical-harmonic coefficients. */ shCoefficients?: Float32Array | null | undefined; /** Highest spherical-harmonic degree present in the data. */ shDegree?: number | undefined; /** Optional three-float normals used by lit rendering. */ normals?: Float32Array | null | undefined; /** Human-readable source format included in diagnostics. */ sourceFormat?: string | undefined; } /** Timing snapshot produced while parsing and uploading one source. */ export interface GaussianSplatsLoadTimings { /** Total parsing and preprocessing time in milliseconds. */ parseMilliseconds?: number | undefined; /** Source-format decoding time in milliseconds. */ sourceParseMilliseconds?: number | undefined; /** Attribute sanitization time in milliseconds. */ sanitizeMilliseconds?: number | undefined; /** Morton ordering time in milliseconds. */ mortonMilliseconds?: number | undefined; /** Hierarchical bounds construction time in milliseconds. */ chunkBoundsMilliseconds?: number | undefined; /** Worker round-trip time in milliseconds when a worker was used. */ workerMilliseconds?: number | undefined; /** Initial GPU upload time in milliseconds. */ uploadMilliseconds?: number | undefined; } /** Optional GPU timestamp results from the most recently resolved frame. */ export interface GaussianSplatsGPUTimings { /** Whether the active renderer provides timestamp results. */ readonly available: boolean; /** CPU time spent submitting the current frame's source upload, or `null`. */ readonly uploadMilliseconds: number | null; /** Video/source unpack compute time, or `null` when that stage is inactive. */ readonly unpackMilliseconds: number | null; /** Projection time, or `null` when unavailable. */ readonly projectionMilliseconds: number | null; /** Sorting time, or `null` when unavailable. */ readonly sortMilliseconds: number | null; /** Compute-tile time, or `null` when that path is inactive or unavailable. */ readonly tilesMilliseconds: number | null; /** Sum of available stage timings, or `null` when unavailable. */ readonly totalMilliseconds: number | null; } /** Read-only renderer diagnostic snapshot. */ export interface GaussianSplatsStats { /** Number of source splats accepted by the renderer. */ readonly sourceSplats: number; /** GPU-visible chunk count, or `null` until an explicit readback. */ readonly visibleChunks: number | null; /** Splats covered by visible chunks, or `null` until readback. */ readonly intervalSplats: number | null; /** Compacted splat count, or `null` until readback. */ readonly compactedSplats: number | null; /** Projected splat count, or `null` until readback. */ readonly projectedSplats: number | null; /** Sorted splat count, or `null` when sorting is inactive or unread. */ readonly sortedSplats: number | null; /** Current draw count visible to the CPU. */ readonly drawSplats: number; /** Estimated bytes owned by all Gaussian GPU resources. */ readonly gpuBytes: number; /** Bytes retained by CPU-side source attributes. */ readonly sourceCpuBytes: number; /** Bytes occupied by source attributes on the GPU. */ readonly sourceGpuBytes: number; /** Active source-attribute storage mode. */ readonly attributeMode: string | null; /** Active spherical-harmonic storage mode. */ readonly shStorageMode: string | null; /** Bytes retained by CPU-side spherical-harmonic data. */ readonly shCpuBytes: number; /** Bytes occupied by spherical-harmonic data on the GPU. */ readonly shGpuBytes: number; /** Source format reported by the loader. */ readonly sourceFormat: string | null; /** Total parsing time in milliseconds. */ readonly parseMilliseconds: number | null; /** Initial upload time in milliseconds. */ readonly uploadMilliseconds: number | null; /** Detailed load timings, or `null` for manually created data. */ readonly loadTimings: Readonly | null; /** Suggested application-managed render scale. */ readonly recommendedRenderScale: number; /** Renderer path selected for the snapshot. */ readonly rendererMode: string; /** Whether SH color is evaluated directly or through a cache. */ readonly shColorMode: 'cached' | 'direct'; /** Number of SH color refreshes performed by this object. */ readonly shRefreshes: number; /** Most recently resolved GPU stage timings. */ readonly gpuTimings: Readonly; /** Number of registered shadow lights. */ readonly shadowLights: number; /** Number of active shadow proxy instances. */ readonly shadowInstances: number; /** Number of completed Gaussian shadow renders. */ readonly shadowRenders: number; } /** Controls cancellation and timeout behavior for {@link GaussianSplats.waitForRender}. */ export interface GaussianSplatsWaitOptions { /** Resolve only after a render newer than this version. */ afterVersion?: number | undefined; /** Optional cancellation signal. */ signal?: AbortSignal | undefined; /** Timeout in milliseconds; zero or omission disables the timeout. */ timeout?: number | undefined; } /** Completion payload for a non-shadow Gaussian render. */ export interface GaussianSplatsRenderEvent { /** Event discriminator. */ readonly type: 'rendercomplete'; /** Monotonically increasing completed-render version. */ readonly version: number; /** Renderer responsible for the completed render when dispatched by a scene. */ readonly renderer?: THREE.Renderer | undefined; /** Scene responsible for the completed render when available. */ readonly scene?: THREE.Scene | undefined; /** Camera used by the completed render when available. */ readonly camera?: THREE.Camera | undefined; } /** Application-managed resolution recommendation for the active camera and target. */ export interface GaussianSplatsRenderRecommendation { /** Suggested multiplier for the application's render target dimensions. */ readonly scale: number; /** Suggested upper bound for the shortest render-target dimension. */ readonly minDimensionCap: number; /** Stable diagnostic reason for the recommendation. */ readonly reason: string; /** Renderer path used to make the recommendation. */ readonly rendererMode: string; } interface GaussianSplatsEventMap extends THREE.Object3DEventMap { beforeupdate: { renderer: THREE.Renderer; camera: THREE.Camera; }; rendercomplete: Omit; dispose: Record; } /** * Renderable Gaussian scene facade. * * Add the object itself to a Three.js scene. Automatic updates are enabled by * the load helpers. When `autoUpdate` is disabled, call `update()` once after * camera transforms are current and before `renderer.render()` each frame. * `dispose()` releases resources owned by this object but does not remove it * from its parent scene. */ export interface GaussianSplats extends THREE.Object3D { /** Runtime type guard. */ readonly isGaussianSplats: true; /** Number of source splats accepted from the most recent data set. */ readonly count: number; /** Allocated splat capacity. */ readonly maxSplats: number; /** CPU-visible draw count, which may trail the GPU until a readback. */ readonly visibleCount: number; /** Number of completed non-shadow renders. */ readonly renderVersion: number; /** Default material, or the application-provided material. */ readonly material: THREE.Material | null; /** Whether scene rendering performs the per-frame update automatically. */ autoUpdate: boolean; /** Whether spherical-harmonic color is enabled. */ enableSH: boolean; /** Active spherical-harmonic degree from zero through the source maximum. */ shDegree: number; /** Highest spherical-harmonic degree present in the current source. */ readonly maxDataSHDegree: number; /** Alpha representation used by the default material. */ alphaMode: 'straight' | 'premultiplied'; /** Maximum rendered Gaussian extent in standard deviations. */ maxStdDev: number; /** Cheap CPU-visible diagnostic snapshot without GPU synchronization. */ readonly stats: Readonly; /** * Replace the source attributes and upload them. * * The renderer retains the arrays for the lifetime of the data set. Treat * them as immutable until another call or disposal; call `invalidate()` * after an intentional supported in-place mutation. */ setData(data: GaussianSplatsData): void; /** * Perform culling, projection, and sorting for one camera. * * Call after camera/world matrices are updated and before scene rendering. * Do not call manually while `autoUpdate` is enabled. */ update(renderer: THREE.Renderer, camera: THREE.Camera): void; /** Wait for a later non-shadow render or reject on cancellation/disposal. */ waitForRender(options?: GaussianSplatsWaitOptions): Promise; /** Force projection and sorting to run on the next update. */ invalidate(): this; /** Return a resolution recommendation without resizing the renderer. */ getRenderRecommendation(renderer: THREE.Renderer, camera: THREE.Camera): GaussianSplatsRenderRecommendation; /** Read current GPU-visible counts and timings; avoid calling every frame. */ readStats(): Promise; /** Release owned GPU resources, listeners, and any explicitly owned material. */ dispose(): void; } interface GaussianSplatsConstructor { /** Construct an empty renderer; call `setData()` before rendering it. */ new (options?: GaussianSplatsOptions): GaussianSplats; /** Runtime prototype. */ readonly prototype: GaussianSplats; /** Load, process, and upload a supported splat URL. */ load(url: string, options?: GaussianSplatsLoadOptions): Promise; /** Process and upload a supported in-memory splat payload. */ parse(buffer: ArrayBuffer, url: string, options?: GaussianSplatsLoadOptions): Promise; } /** * Runtime Gaussian constructor with a deliberately narrowed stable * declaration surface. This is the backing constructor, not a wrapper. */ export declare const GaussianSplats: GaussianSplatsConstructor; /** Deterministic progress snapshot emitted while a source is processed. */ export interface GaussianSplatsProcessingProgress { /** Progress payload discriminator. */ readonly type: 'processing'; /** Active processing stage. */ readonly stage: 'source-parse' | 'sanitize' | 'morton-ordering' | 'chunk-bounds' | 'complete'; /** Completed work units for the active stage. */ readonly loaded: number; /** Total work units for the active stage. */ readonly total: number; /** Normalized progress from zero through one. */ readonly progress: number; } /** * Three.js-style loader facade for PLY, SPLAT, SPLATS, and SOG assets. * * The loader owns transient network/worker resources only. The returned * {@link GaussianSplats} owns its uploaded resources and must be disposed by * the application. */ export interface GaussianSplatsLoader extends THREE.Loader { /** Load a URL and deliver the owned renderable to a callback. */ load(url: string, onLoad?: (splats: GaussianSplats) => void, onProgress?: (event: ProgressEvent) => void, onError?: (error: unknown) => void, options?: GaussianSplatsLoaderOptions): void; /** Load a URL and resolve with an owned renderable. */ loadAsync(url: string, onProgress?: (event: ProgressEvent) => void, options?: GaussianSplatsLoaderOptions): Promise; /** Parse a buffer synchronously except for formats that require image decoding. */ parse(buffer: ArrayBuffer, url: string, options?: GaussianSplatsLoaderOptions): GaussianSplats | Promise; /** Parse a buffer and always resolve asynchronously. */ parseAsync(buffer: ArrayBuffer, url: string, options?: GaussianSplatsLoaderOptions): Promise; } interface GaussianSplatsLoaderConstructor { /** Construct a loader using the supplied Three.js loading manager. */ new (manager?: THREE.LoadingManager): GaussianSplatsLoader; /** Runtime prototype. */ readonly prototype: GaussianSplatsLoader; } /** Runtime loader constructor with worker protocol and parser internals hidden. */ export declare const GaussianSplatsLoader: GaussianSplatsLoaderConstructor; /** LOD selection overrides for streamed Gaussian scenes. */ export interface GaussianSplatsStreamLODOptions { /** Camera distance at which the first lower-detail band begins. */ baseDistance?: number | undefined; /** Geometric distance multiplier between consecutive LOD bands. */ multiplier?: number | undefined; /** Distance penalty applied to cells behind the camera. */ behindPenalty?: number | undefined; } /** Construction controls for the renderer owned by a stream. */ export interface GaussianSplatsStreamRendererOptions { /** Whether GPU frustum culling is enabled. */ frustumCulling?: boolean | undefined; /** Whether transparent splats are depth sorted. */ sortEnabled?: boolean | undefined; /** Sort-key interpretation used for transparent ordering. */ sortMode?: 'radial' | 'depth' | undefined; /** Sort-key precision used by the GPU sorter. */ sortPrecision?: 'float16' | 'float32' | undefined; /** GPU sorting strategy. */ sortAlgorithm?: 'radix' | 'bitonic' | undefined; /** Whether an unchanged camera may reuse the previous projection and sort. */ temporalStability?: boolean | undefined; /** Coordinate convention used by the stream source data. */ coordinateSystem?: 'threejs' | 'source' | undefined; /** Maximum rendered Gaussian extent in standard deviations. */ maxStdDev?: number | undefined; /** Screen-space antialiasing variance. */ blurAmount?: number | undefined; /** Alpha representation expected by the renderer. */ alphaMode?: 'straight' | 'premultiplied' | undefined; /** Initial lighting behavior of the renderer. */ lightingMode?: 'unlit' | 'lit' | undefined; /** Preferred renderer path, with `auto` selecting a supported path. */ rendererMode?: 'auto' | 'raster' | 'compute-tiles' | undefined; /** Application-managed render-scale recommendation reported in diagnostics. */ recommendedRenderScale?: number | undefined; } /** Loading, residency, and renderer options for {@link GaussianSplatsStream}. */ export interface GaussianSplatsStreamOptions { /** Maximum resident splat budget. */ budget?: number | undefined; /** Splat count per residency page, rounded to the stream chunk granularity. */ pageSize?: number | undefined; /** Maximum number of concurrent cell fetches. */ concurrency?: number | undefined; /** Fractional LOD-band hysteresis used to avoid camera-edge thrashing. */ hysteresis?: number | undefined; /** Minimum residency duration in milliseconds before refinement or eviction. */ evictionCooldown?: number | undefined; /** Optional overrides for the manifest's LOD selection policy. */ lod?: GaussianSplatsStreamLODOptions | undefined; /** Safe controls forwarded to the renderer owned by the stream. */ splats?: GaussianSplatsStreamRendererOptions | undefined; } /** Residency progress payload dispatched after a streamed scene changes. */ export interface GaussianSplatsStreamProgressEvent { /** Event discriminator. */ readonly type: 'streamprogress'; /** Number of splats currently resident. */ readonly residentSplats: number; /** Number of cells with a resident LOD. */ readonly residentCells: number; /** Number of wanted cells at their target LOD. */ readonly satisfied: number; /** Number of cells currently wanted by the camera policy. */ readonly wanted: number; /** Number of cell requests in flight. */ readonly inflight: number; } interface GaussianSplatsStreamEventMap extends THREE.Object3DEventMap { streamprogress: Omit; streamidle: Record; } /** Read-only residency and rendering diagnostic snapshot for a streamed scene. */ export interface GaussianSplatsStreamStats extends GaussianSplatsStats { /** Total splat capacity of the residency arena. */ readonly streamCapacity: number; /** Splat count in one residency page. */ readonly streamPageSize: number; /** Number of currently unused residency pages. */ readonly streamFreePages: number; /** Number of currently resident splats. */ readonly streamResidentSplats: number; /** Number of cell requests in flight. */ readonly streamInflight: number; /** Number of cell requests waiting for a concurrency slot. */ readonly streamQueued: number; /** Number of spatial cells in the stream manifest. */ readonly streamCells: number; } /** * Budgeted streaming Gaussian scene. * * Use `load()` as the construction boundary, add the returned object to a * scene, and render normally. It drives residency immediately before its owned * renderer updates. `dispose()` aborts pending fetches and disposes that owned * renderer; callers must still remove the object from its parent scene. */ export interface GaussianSplatsStream extends THREE.Object3D { /** Runtime type guard. */ readonly isGaussianSplatsStream: true; /** Cheap read-only residency and renderer diagnostic snapshot. */ readonly stats: Readonly; /** Abort pending work and release the stream's owned Gaussian renderer. */ dispose(): void; } interface GaussianSplatsStreamConstructor { /** Runtime prototype. */ readonly prototype: GaussianSplatsStream; /** Load a USS manifest or bundle and return a ready-to-add streamed scene. */ load(source: string | ArrayBuffer, options?: GaussianSplatsStreamOptions): Promise; } /** Runtime stream constructor with manifest and residency internals hidden. */ export declare const GaussianSplatsStream: GaussianSplatsStreamConstructor; /** Stable Gaussian visualization helpers and render primitives. */ export { GaussianSplatsHelper } from './GaussianSplatting/GaussianSplatsHelper.js'; export { GaussianSplatsPoints } from './GaussianSplatting/GaussianSplatsPoints.js'; export { SplatClip } from './GaussianSplatting/SplatClip.js'; export { SplatMesh } from './GaussianSplatting/GaussianSplats.js'; export { SplatSequence } from './GaussianSplatting/SplatSequence.js'; export { SplatSkin } from './GaussianSplatting/SplatSkin.js'; export type { SplatSkinOptions } from './GaussianSplatting/SplatSkin.js'; export { SplatVoxelCollider } from './GaussianSplatting/SplatVoxelCollider.js'; export type { SplatVoxelColliderOptions } from './GaussianSplatting/SplatVoxelCollider.js'; export { VoxelCharacterController } from './GaussianSplatting/VoxelCharacterController.js'; export type { VoxelCharacterControllerOptions } from './GaussianSplatting/VoxelCharacterController.js'; export { gaussianAAFactor, gaussianAlphaUV, gaussianColor, gaussianDepth, gaussianHue, gaussianLuminance, gaussianNormal, gaussianPower, gaussianSH, gaussianSHColor, gaussianUV, } from './GaussianSplatting/GaussianSplatsNodes.js';