Runtime changes
Adding, moving, hiding and removing meshes and instances while the scene runs.
Every change goes through the SceneTrees API and takes effect at the next update(encoder).
const lampMesh = trees.addMesh(lamp);
const lampInstance = trees.addInstance({ mesh: lampMesh, objectToWorld: matrix, mask: 0x02, material: 7 });
trees.setTransform(lampInstance, moved); // the GPU top level is refit at the next update
trees.setInstance(lampInstance, { visible: false }); // or mask, material, contributesToGi
trees.removeInstance(lampInstance);
trees.removeMesh(lampMesh); // a mesh no instance uses; its build is cancelled or ignored
- New meshes go through the same path as the load: a GPU tree first (in a batch with the other new meshes of that update), then tinybvh's. Meshes with instances wait for their first tree; until then their instances are not in the top level.
- Moves (
setTransform) refit the GPU top level at the next update. A new top-level shape is built in a worker now and then, when the refit tree's cost has drifted (TOP_LEVEL_REBUILD_COST_RATIO, 1.25). 10,000 moving instances refit in about 0.09 ms of GPU time (RTX 3060, two measurements on the refit's own page). setInstancechangesvisible,contributesToGi,maskormaterial.- Removing an instance frees its record. Removing a mesh that no instance uses frees its tree's range and cancels or ignores its build.
Without subgroups, the top level is the CPU one, rebuilt on the calling thread when something changed.
Merged instances can't change
An instance merged by mergeStaticInstances is baked into a world-space mesh. Moving, hiding, re-masking or removing
it throws. Leave instances that may change out of the merge (static: false). See Merged static instances.
Bind groups
A new mesh may grow the node or triangle buffer, which bumps trees.version. Rebind after the update that grew it
(Rebinding). With three, BvhTraceNodes.update() does it.