docsby gkjohnson

BVHComputeData

Packs one or more scene objects into GPU-accessible BVH buffers (TLAS + BLAS) for use in WebGPU compute shaders via the Three.js TSL node system. After construction, call BVHComputeData#update to populate the storage buffers, then reference this.storage and this.fns in your compute shader nodes.

Ray tracing a mesh's BVH in a compute shader
On this page

Methods

constructor

new BVHComputeData(
	// Scene objects to include. A single item or array of Object3D, BufferGeometry, or GeometryBVH instances are all accepted and wrapped automatically in a BVH.
	objects: Object3D | BufferGeometry | GeometryBVH | Array,
	options?: {
		// WGSL type map for the interleaved per-vertex attribute buffer. Keys are geometry attribute names; values are WGSL type strings (e.g. `'vec3f'`, `'vec4f'`).
		attributes: Record<string, string> = { position: 'vec4f' },

		// When true, a MeshBVH is automatically built for any object that does not already have `geometry.boundsTree` set.
		autogenerateBvh: boolean = true
	}
)

getRootObject

getRootObject(): Object3D

Returns the representative root object for the scene to be constructed.

getShapecastFn

getShapecastFn(
	options: {
		// Function name. Defaults to a random identifier.
		name?: string,

		// TSL struct or definition describing the query shape.
		shapeStruct: StructTypeNode,

		// TSL struct for the accumulated result, or null.
		resultStruct?: StructTypeNode | null,

		// function node that runs before the bvh traversal - useful for resetting or initializing necessary module variables.
		prefixFn?: function | null,

		// function node controlling left/right child traversal order.
		boundsOrderFn?: function | null,

		// function node testing the shape against a BVH node's bounds.
		intersectsBoundsFn: function,

		// function node testing the shape against a leaf triangle range.
		intersectRangeFn: function,

		// function node that transforms the shape into object local space.
		transformShapeFn?: function | null,

		// function node that transforms a hit result back to world space.
		transformResultFn?: function | null,

		// function node called after each BLAS traversal to reset any per-object state set by `transformShapeFn`.
		resetShapeFn?: function | null
	}
): function

Builds a WGSL shapecast function that traverses the TLAS and per-cluster BLAS in a single merged stack/loop for a custom shape type. The returned function signature is: fn name( shape: ShapeStruct[, result: ptr<function, ResultStruct>] ) -> bool

update

update(): void

Rebuilds all GPU storage buffers from the current scene state. Must be called at least once before using this.storage or this.fns in a shader, and again whenever the scene topology changes (objects added/removed, geometry modified).

updateTransforms

updateTransforms(): void

Refits the clustered BVH and rewrites every entry in the transform buffer from the objects' current world matrices. Call this when object transforms or visibility change but the scene topology does not. The transform slots are derived from the clustered BVH's primitive buffer, so they match those written by BVHComputeData#update.

dispose

dispose(): void

Releases GPU resources held by this instance.