Overview

The trace core, for renderers that need rays but do their own shading.

@pmndrs/raytracer traces rays against a triangle BVH on WebGPU. Rays go in, hits come out. What you do with a hit is up to you.

Use it when your renderer already exists and needs rays for one job:

  • Reflections: trace from the G-buffer, shade the hit with your own lighting or with rtShade.
  • Shadows: one visibility ray per light sample.
  • Ambient occlusion: a few short visibility rays per pixel.
  • GI probes and caches: rays from probe positions, or from surfaces, with radiance at the hit.
  • Baking: lightmaps or probe data, offline or at load time.

If you want a rendered image instead, use @pmndrs/pathtracer, which is built on this package.

Three ways to trace

WayWhat it isUse it when
Inline WGSLrtModuleWgsl returns WGSL functions (rtVisible, rtClosest, rtSurface) to paste into your own compute shader.You already have a kernel per pixel or per probe and want to trace from inside it.
Batch tracerRtBatchTracer traces a GPU buffer of rays into a GPU buffer of results.Rays are generated by one pass and consumed by another, or the count lives on the GPU.
Interval queries (experimental)Closest hit and visibility inside a half-open range (t0, t1], inline or batched.Radiance cascades and other probe tracing that splits a ray into segments.

All three run the same WGSL walk over the same buffers, so a scene uploaded once serves all of them.

What it is built on

  • @pmndrs/bvh builds the trees and provides the WGSL walk. Its WGSL names start with bvh; everything this package adds starts with rt, Rt or RT_.
  • @pmndrs/downsampler fills texture mip levels on the GPU when a scene has textures.

Both are regular dependencies; Installation has the bundler note for bvh's workers.

The pieces

A scene on the GPU has two halves:

  • The trace buffers (bvh): nodes, triangles and the top level. This is all rtVisible and rtClosest need.
  • The scene copy: instance transforms, vertex attributes, materials, lights and textures. rtSurface, rtMaterial, light sampling and rtShade read it.

buildGpuScene builds and uploads both from one input. See Your first render and Loading glTF for how to get there from triangles or a .glb.

import { buildGpuScene, detectCaps, requestDeviceForCaps } from '@pmndrs/raytracer';

const adapter = await navigator.gpu.requestAdapter();
const { device, caps } = await requestDeviceForCaps(adapter!, detectCaps(adapter!));
const scene = await buildGpuScene(device, input);
// scene.trace: bvh buffers. scene.buffers: the scene copy. scene.format, scene.packing: what kernels compile for.

Pages in this section

Page
Inline WGSLrtModuleWgsl, the WGSL it gives you, bind groups, masks, compiler errors.
Batch tracerRtBatchTracer, ray and hit record layouts, CPU helpers.
Interval queriesrtClosestInterval, RtIntervalTracer, boundary rules. Experimental.
Scene copyMaterials, lights, light sampling and textures from the shader's side.
ShadingrtShade: one-bounce lighting at a hit.
CapabilitiesdetectCaps, requestDeviceForCaps, enable lines.
API referenceEvery public export, grouped by area.

Examples