Introduction

BVH builders, refits and a ray walk for WebGPU, with no engine inside.

Summary

@pmndrs/bvh builds bounding volume hierarchies (BVHs) for WebGPU. You give it triangles. It gives you trees in one fixed GPU layout, built on the CPU (tinybvh in WebAssembly) or on the GPU (H-PLOC or LBVH), refit on the GPU when things move, and read by a WGSL ray walk that you put in your own shaders.

A BVH is a tree of boxes over a scene's triangles. It lets a ray, or a point, skip almost every triangle on the way to the one that matters. Ray tracing, picking, shadows, collision and distance fields all start from one.

The core imports no engine. three.js support lives behind @pmndrs/bvh/three, Babylon.js support behind @pmndrs/bvh/babylon, and worker builds behind @pmndrs/bvh/worker. The same trees serve a raw compute pass, three's node system, a worker, or another library on the same GPUDevice.

Important

The package is at version 0.0.0 and not on npm yet. The API can still change before 0.1.

What is in it
PartWhat it doesPage
Builderstinybvh (CPU, WebAssembly), H-PLOC and LBVH (GPU, WGSL), and a chooser that picks one. A new method from a paper is one more builderChoosing a builder
One GPU layout64-byte two-child nodes (32-byte quantized ones in scenes, by default), 48-byte triangles, a parent per node, GPU_LAYOUT_VERSIONThe GPU layout
SceneTreesA scene's trees on one device: GPU trees first, tinybvh's swapped in, the GPU top level, runtime changesSceneTrees
RefitsTop-level refit over moving instances, per-mesh refit for deforming meshes, both on the GPURefits
ClusteringBig meshes cut into clusters, each its own top-level leaf (three-mesh-bvh's ClusteredBVH)Clustered top level
The WGSL walkbvhTraceClosest and bvhTraceAny, masks, a triangle filter, a watertight triangle test, ray batchesTracing in WGSL
GPU spatial queriesClosest point, sphere and box tests and your own shapecast in WGSLSpatial queries
Signed distance fieldsA 3D texture or buffer of distances to a scene's triangles, filled on the GPUSDF
CPU queriesRaycast, shapecast, bvhcast and closest point over the same layoutRaycast
Points and linesTrees over points and line segments, on the CPU, with three's raycast thresholdsPoints and lines
Serialization and bakingBuild once (in Node, at build time), save the bytes, load them with no buildSerialization and baking
three.jsScenes from Object3D, GPU skinning, TSL nodes, and three-mesh-bvh's CPU APIthree.js
Babylon.jsPicking with scene.pick's result, scenes from meshes, the walk in a ComputeShader (basic)Babylon.js
WorkersA pool of tinybvh workers that needs no cross-origin isolationWorkers

What it is not
  • It has no WebGL2 path. The CPU queries work anywhere JavaScript runs, but no GPU work targets WebGL2.
  • It is not a renderer. The package ends at the hit: the triangle, instance, barycentrics, face normal and a material number it carries but never reads. What a hit looks like (lights, sampling, textures) is yours.
  • Babylon.js support is "it works", not polish: /babylon has picking that returns scene.pick's PickingInfo, a mesh conversion, and the walk in a ComputeShader on the WebGPUEngine's device, reached through the engine's internals (Babylon.js). It has no scene sync or skinning.
  • Points and lines are primitives on the CPU only (Points and lines): the GPU walk and SceneTrees take triangles.
  • It is not a drop-in for all of three-mesh-bvh. Nearly all of its CPU API is here, and a few things are left out on purpose (Coming from three-mesh-bvh).

Where to start
  1. Installation: the package and a device with subgroups.
  2. First build: a vanilla quick start and two three.js quick starts.
  3. The GPU layout, if you will write your own walk or read the trees yourself.

Users of three-mesh-bvh can start at Coming from three-mesh-bvh.

How the docs are organised

The sections run from first steps to depth, top to bottom in the sidebar:

  • Getting started and Concepts teach the layout and the rules every builder follows.
  • Builders, Scenes, Workers and Engines cover building trees and keeping them current, then sharing a device with three or Babylon.
  • Tracing is the GPU side: the walk, queries and distance fields. CPU queries is the same on the CPU.
  • three.js has the engine pages, including the drop-ins for three-mesh-bvh.
  • Serialization, Performance (how every number was measured), Examples and the API reference close the site.

The repository front page, the README, has the three quick starts side by side, and HISTORY.md tells how the package got here.

Edit this page