Batch tracer
RtBatchTracer is a compiled kernel that reads rays from a storage buffer and writes one result per ray: a hit record ('closest') or a visibility word ('visible'). Everything is recorded into your command encoder. Nothing is read back, and once a batch's buffers have been seen, a frame does no CPU writes.
Use it when one pass makes the rays and a later pass uses the results, for example shadow rays for a list of light samples, or when the ray count is only known on the GPU. If you are already inside a kernel per pixel, calling rtVisible inline is simpler.
Live example: shadow rays from a buffer.
Tracing a batch
import { RtBatchTracer, buildGpuScene, packRays, readVisibility, type Ray } from '@pmndrs/raytracer';
const scene = await buildGpuScene(device, input);
const tracer = await RtBatchTracer.create(device, caps, { ...scene.format, mode: 'visible' });
const rays: Ray[] = [
{ origin: [0, 0.01, 0], tMin: 0, direction: [0, 1, 0], tMax: 2 },
{ origin: [1, 0.01, 0], tMin: 0, direction: [0, 1, 0], tMax: 2 },
];
const packed = packRays(rays);
const rayBuffer = device.createBuffer({ size: packed.byteLength, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
device.queue.writeBuffer(rayBuffer, 0, packed);
const results = device.createBuffer({ size: rays.length * tracer.resultBytes, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC });
const encoder = device.createCommandEncoder();
tracer.encode(encoder, scene.trace, { rays: rayBuffer, results, count: rays.length });
device.queue.submit([encoder.finish()]);
// Reading back is for tests and tools; a renderer binds `results` in its next pass instead.
const staging = device.createBuffer({ size: results.size, usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST });
const copy = device.createCommandEncoder();
copy.copyBufferToBuffer(results, 0, staging, 0, results.size);
device.queue.submit([copy.finish()]);
await staging.mapAsync(GPUMapMode.READ);
const visible = readVisibility(staging.getMappedRange(), rays.length); // one boolean per ray
staging.unmap();
encode(encoder, trace, batch) opens its own compute pass. dispatch(pass, trace, batch) records into a pass you already have; several batches can share one. destroy() frees the small uniform and argument buffers the tracer made; your buffers are never touched.
Options
RtBatchTracer.create(device, caps, options) compiles one kernel. Everything below is fixed at compile time.
The batch
Buffers smaller than capacity entries throw. The tracer caches a uniform and a bind group per batch shape (its buffers, count and mask), up to 256 shapes. A direct count that changes every frame makes a new shape every frame: use an indirect tracer for that.
Record layouts
A ray is 32 bytes (RAY_BYTES), the same layout as bvh's BvhRay and WGSL RtRay:
A full hit record is 40 bytes (HIT_BYTES); the compact one is the first 24 (HIT_COMPACT_BYTES):
HIT_WORD gives these word offsets in code. resultBytes(mode, hitRecord) gives the stride.
CPU helpers
Building your own pipeline
The tracer is a thin wrapper. If you want the kernel inside your own pipeline setup, rtBatchKernelWgsl(caps, options) returns its WGSL (entry point rtBatch, the walk in group 0, the batch IO in group 1), rtBatchEntries(resolveBatchOptions(options)) its group 1 layout entries, and rtBatchArgsKernelWgsl the one-thread kernel (entry point rtBatchArgs) that writes indirect dispatch arguments.