Class LuxarLayer

The loaded scene root, or null before load resolves.

Current archive fault, or null before one occurs, once a new load() begins, or after disposal.

Subscribe to archive faults from the current dataset. A fault already latched by the loaded dataset is replayed immediately. Listener exceptions are logged and do not interrupt layer loading or other listeners.

Load a .luxar.zarr scene and add it to the host scene.

Resolves once the first slice has committed, so a caller that awaits this can frame the camera on real bounds rather than an empty group.

Calling it a second time is a dataset switch: the previous root is detached (loadScene has already disposed its loader, so leaving it attached would draw over disposed backing stores). Calling it again while a load is still in flight throws — see the comment in the body.

Per-frame bookkeeping. Call once per host frame, before the host renders.

Cheap and self-gating: it early-outs before a scene is loaded, and both inner evaluations early-out when nothing needs re-sorting or swapping.

Push the host's drawing-buffer size, pixel ratio and projection kind (orthographic or not) into the material manager. Call after a viewport resize, a DPR change, or a swap between a perspective and an orthographic camera. An FOV / ortho-zoom change needs no call: every shader reads its projection terms from the camera's projection matrix per draw, which also makes a camera that is neither perspective nor orthographic (a plain THREE.Camera with its own matrix) render at the right size.

Does NOT push a near-cull distance. SceneManager derives one from its dynamic scene-bounds cache and passes it as a third argument, which fades geometry approaching the near plane; without it the shared near fade stays at its default and elements pop instead. Wiring it here would mean reproducing the bounds cache, so it is a known limitation rather than an oversight — a host that cares can keep its own near plane clear of the data.

Dimension metadata for the loaded scene (cloned), or null if none.

Index of the dimension with this name (case-insensitive), or null.

Convenience for the common host case of mapping its own timeline onto whichever axis the scene calls "time".

Axis names in center-column order, or [] before load.

A host aligning Luxar data to its own frame needs to know which column is which. Producers disagree — a scene may name its axes Z, Y, X or X, Y, Z for the same specimen, and one authored by luxar gsplat convert names them dim0…dimN and says nothing at all. Getting it wrong renders a plausible, silently transposed scene, so hosts should branch on these rather than assume a column order.

Move a non-displayed dimension (time, channel, z) to value.

Updates are coalesced: while one slice is in flight, further calls replace a single queued update rather than queueing each one. A host scrubbing a slider at frame rate would otherwise issue tens of full view updates per second, all but the last of them already stale.

Resolves when the slice this call led to has committed. Callers driving playback should NOT await it — see prefetchDimensionValue.

A no-op before load: the dimension set comes from the scene, and initFromScene would overwrite any pre-load value with the scene's own defaults anyway. Hosts restoring a saved timepoint should apply it after load() resolves.

Warm the cache for a dimension value the host is about to move to, without moving the view. Fire-and-forget; superseded by the next foreground update.

The playback pattern is setDimensionValue(t) (not awaited) plus prefetchDimensionValue(t + 1) on the same tick, so the host's own timeline never stalls waiting on streamed slices.

Resolve once no slice update is in flight.

Show or hide the layer's geometry.

Toggles visible on the root rather than detaching it, so caches and in-flight fetches survive. Lazy LOD loads pause while hidden and resume on the next update() after re-showing; under GPU-budget pressure, resident levels in a hidden layer are evicted before visible ones.

Whether the layer's geometry is currently visible.

Scale the layer's exposure by multiplier, relative to what the scene was authored with. 1 restores the authored appearance.

For the three emissive geometry types this multiplies the opacity uniform, which in additive blending is the amount each element contributes to the accumulation rather than a coverage fraction. For a Mesh in its default opaque mode, the same uniform is cutout coverage: a value below alphaCutoff (0.5 by default) discards the surface, while a value above it does not dim the surviving fragments. Author the mesh with normal blending when this control should produce smooth surface transparency.

A host needs this because a scene's authored exposure was tuned against some post-processing chain, and the host's is a different one — a value that reads well in Luxar's own viewer can land dim or blown out behind a host's bloom and tone mapping, with nothing wrong with the data.

Re-applied by update as geometry streams in, so nodes that arrive later match the ones already on screen.

Current exposure multiplier; 1 means the authored appearance.

World-space bounds of the loaded scene, or null before load.

Place the layer root in the host's world space.

A host whose own data lives in a normalized or otherwise transformed frame uses this to bring Luxar's data coordinates into it. Applied to the root's matrix directly, so nothing downstream (LOD selection reads projected screen area, which is transform-invariant) needs to know.

Order-independent with respect to load: a matrix declared first is remembered and applied when the scene arrives. The host's placement usually comes from its own metadata, which resolves on a schedule unrelated to the scene fetch, so requiring one order would make correctness a race.

Back off Luxar's GPU budget after a host WebGL context-loss event.

Rebuild Luxar-owned GPU resources after the host restores a WebGL context. Call from the host's webglcontextrestored handler after resetting its renderer and rebuilding any host-owned post-processing resources.

Tear down everything the layer owns: the scene group, the loader and its caches, the data-worker pool, and the depth-sort worker.

Awaits loader teardown for real, via destroyAllAsync(): every prefetcher, caching store, and L0 cache is drained before the pools that serve them are torn down. disposeInstance() alone is explicitly fire-and-forget, so a host that awaits this would otherwise get a promise that guarantees nothing and a subsequent load() could race the drain. This is stronger than what LuxarApp does at shutdown, and deliberately so — a host may remount repeatedly within one page lifetime.

The host's renderer, camera, and scene are left untouched.