Schedulers
The path tracer runs the same integrator in two ways. Both take the same options, have the same methods (setScene, setFilm, setCamera, setLimits, setSeed, reset, encode, readImage, destroy) and produce the same image per pixel: they draw the same random numbers for the same pixel and vertex, so they differ only by float rounding. Choosing between them is a speed decision, not a quality one.
Megakernel
PtMegakernel runs one thread per pixel. One compute dispatch is one sample pass, and each thread traces its whole path: camera ray, every bounce, every shadow ray.
- Few dispatches, no queues, nothing in memory between bounces.
- All material, light and walk code is in one kernel. Its size grows with the scene's features, and a large kernel compiles slowly, on Windows in particular.
- Threads of one workgroup wait for the longest path among them.
encode(encoder, passes) records up to 256 passes per call. See Megakernel.
Wavefront
PtWavefront splits a sample pass into small kernels connected by queues of paths in GPU memory. A pass is a camera kernel, then for each depth: intersect (closest hits), shade (materials, next-event estimation, the next ray), args (writes the next dispatch sizes) and shadow (shadow rays). Dispatch sizes are written by the GPU itself (indirect dispatch), so there is no readback and no CPU decision inside a frame.
- Each kernel is small: the shade kernel has no BVH walk, and the walk kernels have no material code. Every kernel stays under about 50 KB of WGSL even with every material feature.
- Only live paths are queued, so finished paths cost nothing in later bounces.
- It costs about four dispatches per bounce. On short paths and small films that overhead dominates.
See Wavefront.
Wavefront options
With refill, encode(encoder, n) asks for n samples per pixel but does not wait for them. Call await pt.finish() before readImage. maxPassesPerEncode() says how many passes one encode can take at the current maxDepth.
Choosing: ptwfAutoPolicy
ptwfAutoPolicy is the recommended way to pick a scheduler and its settings. It is a pure function of facts you know before the first frame:
import { PtMegakernel, PtWavefront, ptMegakernelWgsl, ptSceneOptions, ptwfAutoPolicy } from '@pmndrs/pathtracer';
const options = ptSceneOptions(scene);
const choice = ptwfAutoPolicy({
width: 1280,
height: 720,
maxDepth: 8,
subgroups: caps.subgroups,
kernelBytes: ptMegakernelWgsl(caps, options).length,
});
const { scheduler, reason, ...settings } = choice;
const pt = scheduler === 'megakernel'
? await PtMegakernel.create(device, caps, options)
: await PtWavefront.create(device, caps, { ...options, ...settings });
console.log(reason); // which rule fired
The rules, in order:
Subgroup appends are picked whenever the device has the feature. Sorting and 'ordered' refill are never picked: on the scenes measured they cost more than they saved. The rules come from paired timings on one Apple M5 Pro and are provisional; anything the policy cannot know (many divergent materials, say) is yours to override. Spread the result, then your own fields.
The kernel-size rule exists because shader compile time on Windows (DXC) grows quickly past about 50 KB. A scene with every material feature (layered, fuzz, thin film, coated metal) can push the megakernel over it; pass kernelBytes and such a scene goes to the wavefront.
What runs where
Most options work on both schedulers. The exceptions:
An unsupported combination throws when the kernel is created, with the reason in the message.