Choosing a builder

import { createMeshLayoutBuilder, type MeshInput } from '@pmndrs/bvh';

const builder = await createMeshLayoutBuilder(device); // compiles the GPU kernels once
console.log(builder.kind, builder.fallbackReason); // 'gpu-hploc' and null, or 'tinybvh' and why

const results = await builder.buildLayouts(meshes, { maxLeafPrimitives: 8 });
for (const { layout, builtBy, fallbackReason } of results) {
    // layout.nodes, layout.triangles and layout.parents are ArrayBuffers in the GPU layout.
    console.log(builtBy, fallbackReason, layout.nodeCount, layout.maxDepth);
}

const lbvhFirst = await createMeshLayoutBuilder(device, { prefer: 'gpu-lbvh' });
const cpuOnly = await createMeshLayoutBuilder(device, { prefer: 'tinybvh' }); // for comparisons
const capped = await createMeshLayoutBuilder(device, { maxBatchBytes: 256 * 1024 * 1024 }); // lower build peak
// cpuOnly.fallbackReason is 'the CPU builder was asked for', but cpuOnly.fallback is false: show only real fallbacks.
const shown = cpuOnly.fallback ? cpuOnly.fallbackReason : null;

const builder = await createMeshLayoutBuilder(device, { prepare: false });
const setupStart = performance.now();
await builder.prepare(); // the pipelines, once: timed apart from any build
console.log(`setup ${(performance.now() - setupStart).toFixed(0)} ms`);

const results = await builder.buildLayouts(meshes, {
    // Once per GPU batch, when its trees are on the GPU (before the readback): never for tinybvh.
    onGpuBatch: ({ meshes: inBatch, gpuMs, wallMs }) => console.log(`${inBatch.length} meshes: ${gpuMs ?? 'no timestamp-query'} ms on the GPU, ${wallMs} ms submit to done`),
});

import { createTinyBvhBuilder } from '@pmndrs/bvh';

const tiny = await createTinyBvhBuilder(); // loads the WebAssembly once
const { layout, buildMs } = tiny.buildLayout({ positions, indices }, { maxLeafPrimitives: 8 });

import { GpuHplocBuilder, planGpuHplocBatches, type GpuMeshGeometry } from '@pmndrs/bvh';

const builder = new GpuHplocBuilder(device);
await builder.prepare(); // compiles the kernels, asynchronously

// One batch builds many meshes with the same dispatches. planGpuHplocBatches splits
// a scene that doesn't fit the device's buffers (or maxBatchBytes) into several.
const { batches, tooBig } = planGpuHplocBatches(device, meshes, { maxBatchBytes: 256 * 1024 * 1024 });
for (const batch of batches) {
    const trees = await builder.buildMany(batch.map((index) => meshes[index]));
    // trees.nodes, trees.triangles and trees.parents are GPU buffers the batch's meshes share.
    for (const mesh of trees.meshes) {
        if (mesh.problem) continue; // refused (too deep, for example): build this one with tinybvh
        // mesh.nodeOffset and mesh.triangleOffset say where its tree sits in those buffers.
    }
    trees.destroy(); // when nothing reads them any more
}
console.log('for tinybvh:', tooBig);

import { GpuLbvhBuilder } from '@pmndrs/bvh';

if (GpuLbvhBuilder.isSupported(device)) {
    const builder = new GpuLbvhBuilder(device);
    await builder.prepare();
    const trees = await builder.buildMany(meshes);
    const layouts = await builder.readLayouts(trees); // CPU copies, for a refit's setTree or a file
    trees.destroy();
    console.log(layouts.map((layout) => layout?.nodeCount));
}