3D engine that AI agents drive
Cook (path tracer)
Cook (67js/addons/path-tracer) is the 67js offline path tracer (a nod to both the Cook-Torrance microfacet BSDF and "let it cook"). Alongside Glaze (Renderer67) for real-time WebGL2, Cook draws one still by following light paths on the CPU or GPU. It loads only when a render job asks for it, so a normal scene pays nothing (issue #57).
import { Cook, renderPathTracedImage } from '67js/addons/path-tracer';
const { rgba, linear, report } = await renderPathTracedImage(
{ parts, environment, camera }, // the same objects the rasterizer takes
{ width: 960, height: 540, samples: 64, bounces: 8, seed: 0, denoise: true, threads: 4, maxSeconds: 300, noiseThreshold: 0 },
);
From an agent, submit an image render job with settings.renderer (see render jobs).
What it draws
Unidirectional path tracing against the triangle BVH that the light bake uses, with next-event estimation and the environment map drawn by importance, then a wavelet denoiser. The first hit of every path samples every light. Later hits draw one light at random and divide by its chance, so the average is the same and a scene with eleven lights costs one shadow ray per bounce instead of eleven.
- Surfaces: diffuse, GGX specular with metals, clear coat, glass (
transmission,ior, rough glass), emission, image maps (map, withalphaMode: "mask"cutouts,normalMapwithnormalScale, andmetallicRoughnessMap, whose green channel scales roughness and blue scales metallic as in the rasterizer; box-projected materials read all of them through the UVs of their projection, the same ones the glTF export writes) and vertex colour. Skinned parts are drawn at their current pose. - Lights: the sun (
keyColor,lightDirection, as a 1 degree disk), point lights with a radius (a sphere, as Blender draws it with Soft Falloff off; Blender's default Soft Falloff makes it an oriented disk, which Cook does not model, see Cycles parity), spot lights with a soft cone, rectangular area lights, and the environment map with its rotation. All of them cast soft shadows, whatever theircastShadowsays, as in Cycles. Light linking is honoured: a light withaffects(or the sun withenvironment.keyAffects) adds nothing at a part it skips, as a direct light or as a bounce source, and still shadows the other lights. - Faces on one plane: the trace uses the same cut geometry as the raster view (faces hidden under a face on their plane are removed), and a face the flush pass ranked in front of another instead of cutting it is lifted by 0.1 mm per rank, so the face in front is the one a ray hits (#751).
- Light that bounces between surfaces, and the sky seen in mirrors and through glass.
- Rough metal that keeps its light: the GGX lobe gives back the light that bounces between microfacets (Fdez-Aguera 2019, from a table of the lobe's albedo), and after a bounce that spread the light the glossy lobes are widened the way Cycles does with
filter_glossy1, so a floor lit through a steel surface does not turn into rare, very bright speckles (#959). - Emission:
emissiontimesemissiveColor(the base colour when none is given) times theemissiveMaptexel at the hit, so a screen or a sign glows with its picture and lights what is near it. An emissive surface is found by the paths that hit it, not sampled as a light, so a small bright panel is noisy at low sample counts. - Volume fog:
environment.volumeFogis traced as a homogeneous medium inside its box, with itsdensity,color(the scattering albedo),anisotropy(Henyey-Greenstein) andmaxDistance. The distance to each scattering event is drawn from the exact free-flight distribution, so there is no step count and no banding. Every event is lit by next-event estimation (sun, point, spot, area lights and the sky, with shadow rays) and light reaching a surface through the fog is dimmed by it. Fog events count as bounces.noiseAmount,noiseScale,drift,stepsand theambientglow are rasterizer tricks and are not used.
Subsurface
A part with a material subsurface weight above 0 sends that share of its diffuse light through a bounded random walk, after the Random Walk model of Blender's Principled BSDF (issue #283). The walk starts inward from the hit with a cosine-weighted direction, scatters isotropically with a per-channel mean free path of radius times scale in metres (one channel draws the distance and the other two are weighted by the mean density, so every channel stays unbiased), and leaves where it meets the part's own surface; there the path continues as white diffuse light with the walk's throughput, lit by every light. The colour is the block's color, or the base colour, mapped to a single scattering albedo with the fit Cycles uses, so a colour of 1 gives an albedo of 1 and gains no energy. A walk ends after 32 scattering events (SUBSURFACE_WALK_STEPS) or when it meets another part, and then its path ends. A point with no surface of its own behind it is a card: half of the colour is reflected on the near side and half is transmitted through it. The specular lobe and clear coat stay as they are, and a weight of 0 takes the unchanged code path (the same samples and pixels). The GPU tracer traces the block too (src/path-tracer-gpu-subsurface.js): the walk is compiled into its kernel only for a scene with a part above weight 0, the block sits in its own table of two texels per material, and a scene without one compiles and draws the kernel it always did (foliage and glass drawn by the kernel before and after this change are byte identical). On the subsurface reference scene (960 by 540, 64 samples, FLIP against the Cycles render with subsurface on) the GPU tracer scores 0.0795 with weight 1 and 0.0876 with weight 0, the CPU tracer 0.0795 and 0.0875, and GPU against CPU is 0.0029 and 0.0014 (measured 2026-11-04). The kernel with the walk compiled in cold in 42.8 s against 7.2 s for the plain one, since a second place that traces rays is inlined again.
What it does not draw
report.ignored lists the ones this scene asks for; a render job returns it as metrics.pathTracer.ignored. It names occlusion maps, anisotropy, iridescence, sheen, moss, splat layers, baked lightMaps, tagged materials (foliage, liquid, water and the like, traced as plain surfaces), blended transparency, and the fog fields above.
- The procedural sky when there is no environment map (the sky is black).
- Occlusion maps. Normal and metallic-roughness maps are drawn on UV-mapped and on box-projected materials. Material graphs and patterns are drawn through the colour map they bake.
- Translucent leaves without a
subsurfaceblock (foliage looks darker than in the rasterizer), liquids, foam and blended transparency (traced as plain or opaque surfaces). - Lights seen in mirrors (area lights and spot lights are lit but not visible), caustics, motion blur, bloom and colour grade. Depth of field is drawn only by the native
cycleskernel, for a camera with anfStop(a thin lens with Cycles' aperture, focus distance and blades; see the render-native README); the CPU, GPU and legacy native tracers draw a pinhole. - Multiple-scattering GGX: rough metal is a little darker than in Blender.
Limits
| Option | Default | Range | Meaning |
|---|---|---|---|
width, height |
960, 540 | 16 to 4096 | Output size, at most 2,073,600 pixels. |
samples |
64 | 1 to 1024 | Paths per pixel. Every pixel draws all of them unless noiseThreshold is above 0. |
bounces |
8 | 1 to 16 | Reflections followed by each path. |
seed |
0 | 0 to 2147483647 | Changes the noise. |
threads |
4 | 1 to 8 | Module workers; the pixels are the same for any count. Without Worker it runs on one thread. |
noiseThreshold |
0 | 0 to 1 (render jobs: 0 to 0.1) | 0 draws every sample. Above 0, a pixel stops once the standard error of its mean luminance, relative to that mean plus 0.05, is under this, checked from 16 samples on and after every 8 more. It costs quality on some scenes (see the table below). It reads only the pixel's own samples, so the result is the same on any thread count and band split. report.averageSamples says how many paths a pixel took. |
maxSeconds |
300 | 1 to 1800 | Wall-clock limit. Passing it throws; there is never a partial image. |
denoise |
true | boolean, "wavelet", "oidn", "none" |
true or "wavelet" filters the light with normal, depth and noise guides; false or "none" does not filter. "oidn" is Open Image Denoise: a render job with it defaults to 16 samples. |
backend |
cpu |
cpu, gpu, webgpu |
gpu traces in a WebGL2 shader, webgpu in WGSL compute (see Choosing a backend). |
fireflyClamp |
20 | 1 to 1000 | Largest radiance one bounce may add to a sample. |
Also checked before any ray is traced: samples times pixels times bounces at most 4 billion, 400,000 triangles (the CPU and WebGL tracers; a scene exported to the native tracer takes more, see below), 1,024 parts, 32 lights, and finite numbers and in-range indices in every part. A render job limits maxSeconds to 600: the job runs on workers without blocking the page, and its deadline is maxSeconds plus 60 seconds for the page and the PNG, so a trace that reaches its limit still ends before the job does.
Instanced scenes for the native tracer
buildTraceScene(parts, environment, { instancing: true }) keeps parts that share one geometry object as instances of it, and buildNativeInputV2 packs them as one bottom-level structure per geometry plus one instance record per part, for traceNative with kernel: "cycles". Without the option the scene is flattened as before, and a scene where no two parts share a geometry is flattened too, with output identical to the default.
- Sharing is decided after the trace geometry is resolved. A skinned, flush-lifted or box-mapped part gets a geometry of its own, and a geometry with per-triangle materials is not shared either: those parts are moved into world space once and traced as instances with an identity matrix.
- Limits: 400,000 triangles counted once per shared geometry, 1,024 distinct geometries (the part limit, counted on geometries) and 65,536 instances.
buildTraceScene(parts, environment, { instancing: true, maximumTriangles, maximumInstances })replaces the 400,000 for a scene exported to the native tracer: an integer from 1 to 4,000,000 (MAX_NATIVE_TRACE_TRIANGLES) bounds the unique triangles (all triangles of a flattened scene), and four times that bounds the triangles with every copy counted. A value outside that range is refused, and the CPU and WebGL tracers never pass it, so they keep 400,000 and their error text.maximumInstancesdoes the same for the 65,536 instances: an integer from 1 to 1,000,000 (MAX_NATIVE_TRACE_INSTANCES), counted over the parts of an instanced scene (each part is one instance, and the unique-geometry bound stays 1,024). A value outside that range is refused, and a flattened scene ignores it. A native render job passes 1,500,000 triangles and 1,000,000 instances, and its export also refuses a scene whose tables together exceed 95% of one V8 string (about 299 characters per unique triangle and 214 per instance, 555 for an instance whose material record is not shared with another part, since parts with equal materials share one record: 1,500,000 triangles leave room for about 280,000 instances that share materials; see "Triangle bound of a native scene" and "Instance bound of a native scene" in cycles-parity.md). An instanced scene has no world-space triangle arrays or CPU BVH, so onlybuildNativeInputV2reads it. - A part's material is its own entry in
materials, so copies may differ in material; a multi-material mesh stays one geometry with the materials the part names. buildNativeInput(thelegacykernel) refuses an instanced scene with an error; build the scene withoutinstancingfor that kernel.traceNativewithkernel: "legacy"refuses a FORMAT-v2 input the same way.- Render jobs with
renderer.backend: "native"keep repeated geometry as instances when the job traces with thecycleskernel (the default): the job page exports FORMAT-v2 tables of the unique triangles and one record per part, the job runner rebuilds the input fortraceNative, and the report names theinstancesand countstrianglesonce per shared geometry. WithJS67_NATIVE_KERNEL=legacy,JS67_NATIVE_INSTANCING=off(flattened triangles on thecycleskernel, to compare the two), or a scene where no geometry is shared, the job exports flattened geometry as before; on thecycleskernel the materials are still sent whole (next point), and only the legacy kernel reads the v1 tables. - A job sends the materials of an instanced scene and of a flattened one the same way (
buildJobNativeInputandbuildFlattenedJobNativeInputinpackages/render-native/job-input.mjs): what the v1 material tables carry is read from them, andcarriedMaterialFieldslays blend opacity, sheen, specular, anisotropy, iridescence, attenuation and the layer textures over it. A part looks the same whether or not other geometry in the scene is shared, and a material that sets none of those fields packs to the record the v1 tables gave. Every job on thecycleskernel is exported as FORMAT-v2; the legacy kernel and light bakes keep the v1 tables. A job's maps go from the materials into the FORMAT-v2 texture pool without the v1 atlas (withVirtualAtlasinpackages/render-native/pack-input.mjs), so the pool (TEXTURE_POOL_MAX_BYTES, 1 GiB, mip levels counted) limits them and not the 4096 by 16384 texels of the atlas; a scene that fitted the atlas packs to the same bytes (tests/native-job-texture-pool.test.jsholds the SHA-256 of every table). Over the pool the job throws aTexturePoolFullError(aRangeError,texturePoolFull: true) that says "The texture pool is full" and to pass smaller textures; the page export (exportNativeSceneTables) rethrows it and does not fall back to flattened or v1 tables, which would only fail on the atlas. A map is checked against the pool and against its data length (width * height * 4bytes) before it is read. The packers taketexturePoolMaxBytesto lower the pool limit for a run (never to raise it). When the v1 fallback fails too, its error ends with the reason the FORMAT-v2 export failed first. - Texture mip levels are opt in on the
cycleskernel: passtextureMips: trueto the packer (ormips: trueon one texture) and every linearly filtered texture, RGBA8, sRGB and float, stores a mip chain after level 0 (level 1 integrates the level 0 reconstruction, the rest are 2 x 2 boxes); the kernel then keeps a ray cone per path and reads the level a hit asks for, blended between two levels. Blender Cycles reads level 0 only, so the default stays level 0 and an existing scene packs and renders byte for byte as before. The pool check counts the levels (a third more texels). The estimate, its limits and the measured error of a minified checker are indocs/cycles-parity.md("Texture mip levels"). - When the instanced packer refuses a scene (copies of an emissive mesh that emit different triangles, a singular matrix), the job exports it flattened as before and the report says
instancing: "flattened"andinstancingReason. A scene that fails to export no longer marks the native tracer unusable for the process; only a tracer or adapter failure does. - A part with
shadowOnly: truebecomes an instance that camera rays skip (visibility bits for every other ray kind stay set). An instance whose material differs from the first copy's emits light by its own material: a copy made emissive by its material is sampled as a light, and a copy made non-emissive is not. Triangles of a shared mesh that are emissive keep onelocal_emissive_offsetfor all copies, so a copy scaled to a size that drops an emissive triangle the other copies keep is refused with its index. - Ray visibility (#1054): a part takes
rayVisibility: { camera, diffuse, glossy, transmission, shadow, volumeScatter }, booleans wherefalsehides the part from that ray kind. The names and the bit layout (1, 2, 4, 8, 16, 32) are those of the FORMAT-v2 instance table and of the Cyclesvisible_*object settings the parity bench sets.buildTraceScenevalidates the field at the public boundary (an unknown ray kind, a non-boolean value,shadowOnlywithshadow: false, or an emitter hidden from bounce rays throws and says what to pass) and returns it asinstances[i].visibilityFlagsfor an instanced scene and aspartRayVisibility(one byte per part) for a flattened one; the job packers write both into the instance table. A pane withrayVisibility: { shadow: false }lets the sun and sky be sampled through a window, where the shadow rays would otherwise hit the glass; the pane still shows and refracts for camera and bounce rays. A scene where no part hides from a ray kind (no field,{}or alltrue) packs byte for byte as before.castShadowis deliberately not mapped: library code setscastShadow: falseas a raster optimisation (grass, litter, whitewater, windows, gulls), so honouring it would change how existing scenes path trace. The native tracer ignores it as before; onlyrayVisibilitysets the bits.- An emissive part (
material.emission > 0) may hide fromcamera,shadowandvolumeScatterrays but not fromdiffuse,glossyortransmission: the kernel samples an emitter by next-event estimation with a multiple-importance weight below 1 and weights its bounce hits to match, so culling those hits would lose part of its light (up to about half).buildTraceScenerefuses that combination. Blender Cycles behaviour for such an emitter was not checked here; refusing is the safe choice until a parity run says what Cycles does. - Only the
cycleskernel reads it.buildNativeInput(the v1 tables of thelegacykernel) and a job on thelegacykernel throw when a flattened scene hides a part from a ray kind. The v1 fallback of acyclesjob (after a FORMAT-v2 material build fails) and light bakes draw without the visibility; the job report then saysrayVisibility: "ignored"withrayVisibilityReason, asmaterialsReasondoes for the materials. The CPU tracer, the WebGPU and WebGL tracers and the rasteriser ignorerayVisibilityas before. The MCP scene tools do not exposerayVisibility. - Not done: a Cycles-style option that lets shadow rays through thin clear glass by itself. Set
rayVisibility: { shadow: false }on the pane.
A part whose matrix mirrors (negative determinant) is flattened with its vertex normals kept outward and the last two corners of each triangle swapped, so the cross-product normal of every triangle points outward too. The native cycles kernel derives its geometric normal from that winding, and an instanced mirrored part reaches the same result through its negative-scale flag; a scene without a mirrored part is unchanged byte for byte.
The same scene and options give the same bytes. Random numbers come from a hash of the pixel, the sample and the seed, never from Math.random or the clock, and a pixel does not depend on which thread drew it.
Choosing a backend
backend: "native" is an agent render job setting, not a renderPathTracedImage option: packages/render-native runs the same kernel on Vulkan ray queries. On the demo room at 1920 by 1080 and 64 samples an MCP image job took 25 to 35 s with native against 58 s with gpu (trace alone 2.7 to 3.1 s against 38.8 s; the rest is the page export, the wavelet denoise and the PNG), FLIP 0.0047 between them. A missing package, binary or adapter falls back to gpu with a note in the job report. maxSeconds is honoured: past it the native trace stops and the job fails, as on the other backends, instead of rerunning on gpu; noiseThreshold is too (the kernel applies the CPU stop rule per pixel, so averageSamples falls below samples; the gpu and webgpu backends still draw every sample). Volume fog and subsurface scattering are in the native kernel, compiled in only for a scene that uses them; bench/native-tracer/scenes.mjs draws the reference scenes on native and on the WebGPU megakernel for a FLIP comparison. Alpha cutouts (alphaMode: "mask") work: cutout triangles are their own geometry and the kernel confirms a hit only when the colour map alpha reaches the cutoff, with no step limit. In a dense cutout scene native is the more correct tracer: the CPU and WebGL2 shadow ray takes the first hit the traversal finds, not the nearest, and when that hit is a transparent texel it skips occluders it had not reached yet, so those backends leak light (300 leaf cards: native vs cpu FLIP 0.043, and 0.0002 once the CPU shadow ray takes the nearest hit; bench/native-tracer/cutout-bisect.mjs shows one card agrees exactly). The steps before: up to 8 layers deep (bench/native-tracer/cutout.mjs: 300 masked leaf cards trace in 0.1 s at 640 by 360 and 64 samples). See agent-render-jobs.md.
The native package has two kernels. traceNative keeps legacy, the kernel described above, as its own default, but a render job with backend: "native" (issue #970) traces with the cycles kernel and denoises with OIDN and the albedo and normal guides when denoise is true (the default); JS67_NATIVE_KERNEL=legacy makes the job runner use the legacy kernel again, and without OIDN installed (or when it fails) the GPU a-trous filter of the native tracer runs (denoiser: "atrous", biased: it smooths) with a note in denoiserNote; denoise: "wavelet" picks the CPU filter (on metal, lit-interior and metal-room at 960 by 540, 64 and 256 samples, NVIDIA A10: the a-trous filter took 6 to 8 ms against 3.8 to 4.3 s for the wavelet filter and 0.23 s for OIDN, with the same relMSE as the wavelet filter to six digits and OIDN at 0.5 to 0.9 of it, #1018). The job report names the kernel, the noiseThreshold and the averageSamples. On the metal reference scene (960 by 540, 256 samples, NVIDIA A10, Vulkan, scored against Cycles 5.3 at 4096 samples with relMSE, the 100 worst pixels dropped, and FLIP): the default job frame step (bench/native-tracer/metal-job.mjs) took 1.64 s (1.22 s trace, 0.23 s OIDN) with relMSE 0.00007, against 5.57 s for the wavelet filter (relMSE 0.00014), 1.36 s for no filter (relMSE 0.00019, flat-area grain 0.0076 against 0.0024 filtered) and 1.23 s for the legacy kernel with OIDN (relMSE 0.00093, FLIP 0.039 against 0.009). cycles is the opt-in kernel that follows Blender Cycles 5.3: on six reference scenes at 4096 samples it matches Cycles within 1 percent of the mean and within 1.8 percent on every 8 by 8 tile, and its error at 256 samples on lit-interior is 0.0027 against 0.0198 for the legacy kernel (Cycles: 0.0031). Three options follow Cycles: sampler ('sobol-burley' blue-noise pattern by default, 'white' for the hash sampler), filterType and filterWidth ('box' width 1 by default, 'gaussian' and 'blackman-harris' from the Cycles filter table) and lightSampling ('auto', 'tree' or 'uniform'; the Cycles light tree is used from more than one emitter). It is 2.3 to 3.1 times slower per sample than the legacy kernel before the light tree (0.92 s against 2.86 s on lit-interior, 960 by 540, 256 samples), and the light tree adds 16 to 32 percent per sample on top; at equal error against Cycles 5.3 it is 1.2 times faster on lit-interior and 3 to 6 percent slower on many-lights-500 on an RTX 3060, and 1.5 times faster and level (1.02 to 1.03 times) on an NVIDIA A10G. Tables, method and the equal-error caveat are in cycles-parity.md.
backend: 'cpu' (the default) is the reference: it reuses src/triangle-bvh.js and src/ray-query.js, runs on workers in the job page next to the scene, needs no GPU, and gives the same bytes for the same scene and options. It measured 25 to 238 seconds for a 960 by 540 still at 32 samples on a Ryzen 5 5600X with four threads, while another session also loaded the machine (table in bench/reference/README.md).
backend: 'gpu' (issue #302) runs the same algorithm in a WebGL2 fragment shader (src/path-tracer-gpu.js, loaded only for this backend, so a CPU render and the core bundle do not carry it). The BVH, triangles, materials, maps, lights and the environment table are packed into float textures (src/path-tracer-gpu-pack.js), the random numbers are the same integer hash and PCG stream as the CPU tracer and are drawn in the same order, and each sample adds into four float targets (colour and depth, albedo, normal, luminance and its square) that feed the same denoiser. Float32 maths and a 24-bit random value make the pixels differ a little from the CPU tracer: FLIP (LDR) of GPU against CPU at the same seed was 0.0001 to 0.0018 on the 16 path tracer reference scenes at 480 by 270 and 32 samples. It needs a page with WebGL2, EXT_color_buffer_float and EXT_float_blend, and throws without them, so choose it only where those exist. It traces everything the CPU tracer does (lights with linking, all materials and maps including emissive maps, glass, volume fog, the sky); it does not use noiseThreshold (every pixel draws every sample) or threads, and a sample that produced a NaN or an infinity counts as black. The first still of a page compiles the kernel (13 to 30 s), later ones reuse it.
The 1920 by 1080 still of the demo room at 64 samples took 58.15 s on the GPU (RTX 3060, clean image, including 10.3 s of compiling with a warm shader cache, the BVH build and the denoiser; a cold compile measured 30 s on an earlier version of the kernel, which would have put it over 60 s; remeasured 2026-11-04 below) against 585.9 s on the CPU tracer (measured 2026-11-03; remeasured 2026-11-04 at 38.7 s for a first compile of a kernel text the driver had not seen, 7.0 s of it compiling, and 41.0 s for the same kernel again, 7.3 s compiling, each in a fresh headless Chrome profile, so the 60 s bound holds cold: the compile no longer differs between cold and warm on this machine, and gpuCompileSeconds in the job report records it; a scene with a subsurface part compiles a larger kernel, 42.8 s cold in the same setup, which adds that to its still; see the WebGPU decision for the choice of WebGL2 over WebGPU). Against Cycles (FLIP, 960 by 540, 64 samples, 16 scenes, bench/reference/path-tracer.json for the CPU and path-tracer-gpu.json for the GPU), the two backends scored within 0.0002 of each other on every scene (largest gap 0.0001 to 0.0002 on foliage, glass, character), so each keeps its score within the 0.005 bound (measured 2026-11-04). The GPU run took 4 to 13 s per scene after the first scene's compile. node bench/reference/gpu-compare.mjs <directory> <scene or recipe.json> --backend both draws a scene with both backends, and bench/reference/flip-compare.py scores them against each other and against Cycles. A render job selects it with settings.renderer.backend: "gpu" (see docs/agent-render-jobs.md); the job default stays cpu.
backend: 'webgpu' (issue #625) runs the same algorithm as WGSL compute (src/path-tracer-webgpu.js and src/path-tracer-webgpu-kernel.js, loaded only for this backend). It takes the same packed scene tables as storage buffers, draws the same random numbers in the same order and returns the same buffers, so the denoiser and tone mapping are unchanged. It needs navigator.gpu and an adapter with 10 storage buffers per shader stage; without them it throws an error that names gpu and cpu (the MCP cpu runtime has no WebGPU). Volume fog and subsurface scattering are traced too (src/path-tracer-webgpu-medium.js, the WGSL form of the WebGL2 pieces with the same random numbers): they are compiled into the megakernel only for a scene that uses them, and the subsurface table rides in the materials buffer, so a scene without them compiles the kernel it always did. The wavefront kernel does not trace them and throws a RangeError that names the megakernel. The same kernel starts paths at lightmap texels for the light bake (bakeLightmapsAsync(..., { backend: 'webgpu' }), see docs/light-bake.md). Measured on the RTX 3060 (2026-11-09, docs/webgpu-decision.md): the kernel compiles in 0.5 s cold against 29 s for the WebGL2 kernel, the demo room at 1920 by 1080 and 64 samples traces in 8.0 to 8.5 s against 15.2 s (three alternating runs), and FLIP against the WebGL2 backend is 0.0000 to 0.0019 on 15 of the 16 reference scenes (the sixteenth, fog, was not supported then; with fog and subsurface ported, 480 by 270 at 32 samples without the denoiser, RTX 3060, one run on a loaded machine, 2026-11-09: fog 0.0000 FLIP against WebGL2 in 1.35 s against 33.8 s, subsurface 0.0039 in 2.28 s against 174 s; the WebGL2 numbers are mostly the 17 and 106 s kernel compile, which is 1.0 and 1.9 s on WebGPU). The default kernel is a megakernel; a wavefront kernel (generate, extend, shade, shadow, with optional sorting by material) is built and was slower on this scene (17.3 to 18.1 s), so it is opt-in through traceOnWebGpu only. The default backend stays cpu.
Speed
Where the time went on the 181,708 triangle demo room (issue #129; one thread, CPU time, 640 by 360 band, measured while another session loaded the machine):
| Step | Paths per second per thread |
|---|---|
| Before: generic BVH visitor, every light traced at every bounce | 8,360 (7,955 and 8,576 in two runs) |
| Typed-stack ray query, same pixels bit for bit | 9,756 (1.2 times) |
| One light drawn at random past the first hit (11 light sources) | 23,300 (2.4 times more, 2.8 in all) |
Adaptive sampling, a shadow-ray shortcut and the demo-room still (issue #129, second pass; same 181,708 triangle room, one thread, 160 by 90, seed 7, error is the RMSE of the 8-bit image against a 256 sample render of seed 0, on an idle machine):
| Step | Seconds | Average samples | Error |
|---|---|---|---|
| 64 samples, every pixel | 25.9 | 64 | 4.38 |
| Same, shadow rays skip the surface lookup unless the material is a cutout | 21.0 and 19.1 (1.23 to 1.36 times) | 64 | 4.38, pixels unchanged |
| 24 samples, every pixel | 9.5 | 24 | 5.53 |
noiseThreshold 0.05 |
11.3 | 26.1 | 4.87 |
noiseThreshold 0.03 |
14.1 | 34.4 | 4.77 |
| One light drawn at random at the first hit too | 12.9 | 64 | 7.26 |
Adaptive sampling beats fewer samples at the same cost on this room (4.87 at 11.3 s against 5.53 at 9.5 s), but it is off by default because it costs score against Cycles on other scenes, and quality is why the tracer exists. Score against Cycles (FLIP, lower is better), 64 samples at most, four threads, 960 by 540:
| Scene | noiseThreshold |
Score | Seconds |
|---|---|---|---|
spot-area |
0 (default) | 0.0658 | 37.1 |
spot-area |
0.008 | 0.0748 | 31.3 |
spot-area |
0.015 | 0.0847 | 25.1 |
spot-area |
0.03 | 0.0900 | 21.3 |
lit-interior |
0.03 | 0.2214 | 106.7 |
lit-interior scored 0.1993 at 32 samples before adaptive sampling; it was not re-run with every sample at 64. A render job passes the value as settings.renderer.noiseThreshold, 0 to 0.1.
Fewer samples with the denoiser lose little on some scenes: 24 samples scored within 0.005 of 64 on brick-graph (0.1394 against 0.1370) and character (0.1164 against 0.1116), at about 45 percent of the time. Two scenes are not proof for all. Drawing one light at the first hit halves the time but makes the image noisier than 24 samples cost, so it was not kept.
The 1920 by 1080 still of tests/fixtures/demo-room.recipe.json at samples: 64, through an MCP image job with 8 threads: 246.4 s in the tracer (229.4 s tracing, the rest the filter), 30.7 samples per pixel on average, 257 s for the whole job (measured, once, with noiseThreshold 0.03, the setting at that time). With the default of 0 every pixel draws all 64, so the same still takes 585.9 s in the tracer and 596.1 s for the job (measured 2026-11-01 on 8 threads, machine at 100 percent CPU), inside the 600 s limit with almost no room: lower samples or pass a noiseThreshold for a larger room. That is 6 seconds over the old 240 s job limit, so the limit is now 600. The hair strands were not the cost by themselves: the time was per ray, and every ray was slow.
Open Image Denoise (optional)
settings.renderer.denoise: "oidn" filters the still with Intel Open Image Denoise 2.5.1 (Apache-2.0), the denoiser Cycles uses, fed the colour, albedo and normal images the tracer writes. It is the package @codepawlhq/67js-denoise-oidn (packages/denoise-oidn), not part of the core archive: install it beside 67js and run its fetch script, which downloads the official release binary for the platform after a SHA-256 check. The job runner calls the oidnDenoise tool on the CPU. A source checkout also finds the package in packages/denoise-oidn. On the native backend denoise: true means OIDN when it is installed. Without the package or the binary the job runs the wavelet filter and says why in metrics.pathTracer.denoiserNote; metrics.pathTracer.denoiser always names the filter that ran. Only the native build is shipped. The browser port (denoiser 0.0.11 on tensorflow.js) is a 134 MB install; its scores are not in the table because the GPU it needs was not free for this comparison (bench/reference/denoise-browser.mjs is the script to run it), and the job runner already has Node.
Compared on 960 by 540 captures of six reference scenes, FLIP against Cycles, lower is better (bench/reference/denoise.json, made by denoise-capture.mjs, denoise-compare.mjs and denoise-score.py). The unfiltered tracer, the wavelet filter and OIDN all land within 0.01 of each other on every scene except metal, because most of the score is the difference between the tracer and Cycles, not noise:
| Scene | Wavelet, 64 samples | Wavelet, 16 | OIDN, 16 | OIDN, 8 | OIDN, 32 |
|---|---|---|---|---|---|
brick-graph |
0.0805 | 0.0812 | 0.0812 | 0.0818 | 0.0806 |
character |
0.0287 | 0.0297 | 0.0308 | 0.0324 | 0.0295 |
glass |
0.0385 | 0.0399 | 0.0395 | 0.0407 | 0.0385 |
material-spheres |
0.0449 | 0.0465 | 0.0471 | 0.0487 | 0.0457 |
metal |
0.0439 | 0.0474 | 0.0444 | 0.0457 | 0.0440 |
outdoor-hdri |
0.0226 | 0.0231 | 0.0239 | 0.0250 | 0.0230 |
OIDN at 16 samples does not score at or below the wavelet filter at 64 on any of the six scenes: it is 0.0005 to 0.0022 higher. At 32 samples it equals it on glass and is 0.0001 to 0.0008 higher on the other five. Issue #303's goal (no worse than the wavelet filter at 64 on four scenes with 16 samples or fewer) is therefore not met by this measure. At equal samples OIDN is clearly better only on metal (0.0444 against 0.0474 at 16); on the other scenes the two are within 0.0013 of each other, the wavelet filter ahead on character, material-spheres and outdoor-hdri. So 16 samples is the default for oidn because it costs a quarter of the tracing time for a score about 0.001 to 0.002 higher, not because it matches 64.
Time of the denoise step alone, 1920 by 1080 demo room: 1.6 s for OIDN against about 9 s for the wavelet filter (measured once each, machine loaded by other jobs; the 960 by 540 captures took 0.45 to 0.67 s against 2.1 to 3.2 s). The whole still at 16 samples took 138 s with OIDN (113 s tracing) and 105 s with the wavelet filter (85 s tracing); the tracing times differ because of load, not of the filters. A 64 sample wavelet still of that room took 586 s (above), so 16 samples with OIDN is about four times faster at a FLIP score 0.001 to 0.002 higher on these scenes.
OIDN's output is the same bytes run to run on one machine (the CPU device, two runs on each of the 24 captures, and two identical PNGs from an MCP job); it was not compared across machines or CPU generations, where OIDN does not promise it.
Measured
npm run reference -- --path-tracer [--samples 32] draws each reference scene with the tracer and scores it against the Cycles render of the same scene with FLIP (bench/reference/path-tracer.json). It leaves baseline.json and images/ alone, and it needs the Cycles renders of an earlier npm run reference.
Scores and times are in the table of bench/reference/README.md. Cycles used 256 samples with a denoiser, and the tracer 32 samples with its own filter, so the remaining gap is partly noise and partly the differences listed above.
Progressive preview, blue noise and light choice (issue #623)
67js/addons/path-tracer-progressive (createProgressiveTracer(scene, options)) draws the GPU tracer one sample per pixel per step(). The first two steps draw at a quarter and a half of the size, one sample each, then every step adds a sample at full size; update({ camera, parts, environment }) starts the image over, and snapshot() reads the image back (filtered unless denoise is off). It shares the WebGL2 context of the GPU still, so one render at a time owns it. The core bundle does not carry it.
Three options (samplingPattern: "blue-noise-first" and lightSelection: "importance" need the GPU backend, lightSelection: "tree" runs on the CPU reference, the WebGL2 GPU and the WebGPU tracer). samplingPattern and importance are off by default; lightSelection defaults to "auto", which is "tree" for a scene with more than 8 local lights and "uniform" for the rest, so scenes with a handful of lights draw the same pixels as before:
samplingPattern: "blue-noise-first"uses a 64 by 64 void-and-cluster tile (src/path-tracer-blue-noise.js, same bytes for the same seed) for the pixel jitter and the first two random numbers of sample 0, asSAMPLING_PATTERN_BLUE_NOISE_FIRSTdoes in Cycles. Later samples are random.lightSelection: "importance"replaces the uniform light draw past the first hit: the sun and the sky keep their uniform share, and the local lights split theirs by power over squared distance, surface cosine and spot cone, mixed 10 percent with a uniform part. It ignores shadows and is a flat sum over the lights, not a tree (that islightSelection: "tree") nor ReSTIR; a scene with one local light or none draws the same pixels as before.lightSelection: "tree"is the light tree of Conty and Kulla (2018) as Cycles builds it (src/kernel/light/tree.h), insrc/path-tracer-light-tree.js, the same code and table on the CPU reference and in the GLSL kernel. The point, spot and area lights are leaves of a binary tree built with the surface area orientation heuristic of the paper (12 buckets per axis, cost = energy times box area times orientation measure of both sides, as Cycles builds it). Each node keeps its box, an orientation cone (merged as in the paper) and the sum of its energy. A shading point walks down from the root and picks a child at each step by the importance of its box and cone: energy times the cosine of the best angle the box and cone allow, times the surface cosine, over the squared distance to the nearest point of the box. The step takes the chance 0.9 of the child's share of the maximum measure plus 0.1 of its share of a minimum measure (energy over the squared farthest distance, no angles; Cycles mixes them half and half), so a node the angle test culls keeps a chance and the image stays unbiased while little of the draw goes to lights that cannot reach the point; the chance of the whole path is divided out. The sun and the sky are the distant emitters and keep their uniform share of the emitter draw. It ignores shadows and spot blend. On a part with light linking that leaves some local light out, the tree is skipped and the draw is uniform among the lights the part is linked to (the tree weighs a node by every light under it, so it would spend draws on lights the part cannot see). With more than 16 local lights the first hit draws one light by the tree too, where every other selection traces a shadow ray to each light there. A scene with one local light or none draws the same pixels as the uniform choice.
Measured on the RTX 3060, 960 by 540, FLIP against Cycles of the denoised image, machine shared with other jobs (times are ranges of repeated runs: GPU steps only, without the first step's kernel compile and without the read back, which took 1.8 to 2.6 s with the filter):
| Scene | Still, 64 samples | Random, 64 steps | Importance, 32 steps | Importance, 64 steps |
|---|---|---|---|---|
lit-interior |
0.0769 | 0.0769 in 2.2 s | 0.0671 in 1.3 s | 0.0572 in 2.6 s |
spot-area |
0.0262 | 0.0262 in 0.9 s | 0.0274 in 0.5 s | 0.0224 in 0.9 s |
The still of spot-area took 60.5 s including 29.9 s of kernel compile. Blue noise alone scored the same as random within 0.0003 at every count on both scenes (it helps the 1 sample image only by 0.001 to 0.002). Median frame time of one sample per pixel, 200 frames, 960 by 540: demo room 69 ms (67 to 71) random and 71 to 73 ms with both options; lit-interior 32 ms; spot-area 14 ms.
The light choice was first measured when the importance draw and the tree were new, against an older Cycles render of brick-room and with an earlier version of the tree. Those figures (for example brick-room 0.2587 to 0.2692 at 64) and the verdict drawn from them, that the option stays off, are replaced by the table of the proof below: it scores uniform, importance and the tree of the current code against one set of Cycles renders in one pass, and is the only table to read. The two Cycles renders of brick-room are not the same image (uniform scores 0.2587 at 64 against the old one and 0.1166 against the current one, which is why the old and the new figures cannot be compared). Why the older render differed is not known, and the claim that a later change (#813) removed the loss is dropped, since nothing here tests it. light-linking ignores its light masks when it picks. bench/reference/progressive-compare.mjs and progressive-score.py made the numbers.
The scene that shows the gain is many-lights (bench/reference/scenes.js, issue #623): a 36 m corridor lit only by 24 ceiling lamps, 16 point and 8 spot. FLIP against Cycles (the Blender 5.2 Cycles render of the same scene, many-lights-cycles.npy) at 960 by 540, 16 and 64 samples: uniform 0.1926 and 0.1471, importance 0.0594 and 0.0688, tree 0.0753 and 0.0593. The tree scores here were 0.0710 and 0.0617 in an earlier measurement; uniform and importance repeat to four digits, so the Cycles file and the noise did not change and the tree code did (inferred: the tree was tuned after that run). The default (auto) picks the tree on this scene, and its images are byte-identical to the forced tree's (the proof script prints that). One full size sample (median of 20 on the RTX 3060, shared machine, measured before the tree tuning) takes 72 ms with the uniform draw, 88 ms with importance (it sums every light at every hit) and 38 ms with the tree, because the first hit traces one shadow ray instead of 24; 64 steps took 15.7 s, 11.5 s and 12.4 s including the kernel compile and the read back of the checkpoints. Importance wins at 16 samples, the tree at 64, and the tree costs about half the time per sample.
Proof of the three checks of issue #623 on 2026-11-11 (node bench/reference/progressive-proof.mjs <directory> --cycles <directory with the Cycles .npy files> [--runs 3], behind the GPU lock; it prints the tables below from progressive-compare.mjs and progressive-score.py). RTX 3060, 960 by 540, denoised, two runs, machine shared with other jobs, times are ranges. The Cycles renders are the five files of brick-room, light-linking, lit-interior, many-lights and spot-area, rendered by the Blender reference script between 2026-11-09 and 2026-11-11; the other 12 scenes have none. Every kernel is compiled by a warm-up draw before anything is timed, because the GPU kernels are cached in the page: the first draw of a page pays the compile, and the earlier timing of this proof did not account for that. Progressive time is the setup, the steps and one denoised read back (3.4 s of it); the still time is the whole renderReferencePathTraced call and the traced time its GPU part.
| Scene | Light choice | Still FLIP | Progressive FLIP | Samples reached | Progressive s | Still s | Still traced s |
|---|---|---|---|---|---|---|---|
lit-interior |
default (uniform) | 0.0769 | 0.0769 | 64 | 5.7 to 6.2 | 5.5 to 6.2 | 2.1 |
lit-interior |
forced tree | 0.0769 | 0.0724 | 24 | 4.3 to 4.4 | 5.5 to 6.2 | 2.1 |
spot-area |
default (uniform) | 0.0262 | 0.0262 | 64 | 4.3 to 4.5 | 4.1 to 4.4 | 0.9 |
spot-area |
forced tree | 0.0262 | 0.0239 | 48 | 4.0 to 4.7 | 4.1 to 4.4 | 0.9 |
Item 1 is not met. With the kernels compiled on both sides, the default progressive draw reaches the still's score only at the still's 64 samples and takes the same time within the noise (
lit-interior5.7 to 6.2 s against 5.5 to 6.2 s,spot-area4.3 to 4.5 s against 4.1 to 4.4 s). The earlier 5.7 s against 82 to 166 s forlit-interiorcompared unlike things: the still ran first in the page and paid the kernel compile (a one sample still, the warm-up, took 106.8 s in the first run, of which the kernel compile was 60.0 s and the rest of the first call, about 47 s, was not isolated; the compile was 44.2 s in the second run), and the progressive draw that followed reused the cached kernel. At the same 64 samples and the same score the still path is not faster or slower than the progressive path. With the tree forced the progressive draw reaches the still's score earlier in samples (24 onlit-interior, 48 onspot-area) and is faster onlit-interior(4.3 to 4.4 s against 5.5 to 6.2 s; the ranges do not overlap in two runs), inside the noise onspot-area. That gain needs the tree kernel, which compiled in 56.0 to 58.4 s in the warm-up of each run, once per page, and is not the default.Frame time at 1 sample per pixel on the demo room (
tests/fixtures/demo-room.recipe.json), median of 200 frames, two runs: 79.3 to 80.3 ms (fastest frame 76.2 to 77.5 ms, slowest 84.0 to 84.4 ms).Item 3 is met on the five scenes that have a Cycles render and by identical pixels on the other 12. Light choice at equal samples, FLIP against Cycles (one pass, 16 and 64 samples, all 17 path tracer scenes including
many-lights, uniform, tree and importance forced, and the defaultauto):Scene Samples Default Uniform Tree Importance Default equals uniform Default equals tree Tree equals uniform brick-room16 0.1699 0.1699 0.1409 0.142 yes no no brick-room64 0.1166 0.1166 0.0985 0.0991 yes no no light-linking16 0.0291 0.0291 0.022 0.0273 yes no no light-linking64 0.0213 0.0213 0.0212 0.0217 yes no no lit-interior16 0.1318 0.1318 0.0854 0.0884 yes no no lit-interior64 0.0769 0.0769 0.0569 0.0572 yes no no spot-area16 0.0415 0.0415 0.034 0.0345 yes no no spot-area64 0.0262 0.0262 0.0221 0.0224 yes no no many-lights16 0.0753 0.1926 0.0753 0.0594 no yes no many-lights64 0.0593 0.1471 0.0593 0.0688 no yes no The default draws the same bytes as forced uniform on every scene but
many-lights, which has 24 lamps (more than 8) and picks the tree; there the default and the forced tree are byte-identical and the scores agree (0.0753 and 0.0593), which is the one figure for the default and the tree. With the tree forced, no scene with a Cycles render scores worse than uniform at either count (light-linkingat 64 is 0.0212 against 0.0213, a tie). The 12 scenes without a Cycles render (brick-flat,brick-graph,brushed-film,car-paint,character,fog,foliage,glass,long-street,material-spheres,metal,outdoor-hdri) have no score; the script compared the image files of the forced tree and the forced uniform draw at 16 and 64 samples and they are byte-identical on all 12, as are the default and the forced uniform draw. "Better on the scene with the most lights" rests onmany-lightsagainst its Cycles render (0.0593 against 0.1471 at 64). Thebrick-roomloss of the earlier measurement (0.2587 to 0.2692) does not show against the current Cycles render; the two renders differ, so the old figures are not comparable and are not read as fixed.
Real-time hybrid view (issue #624)
67js/addons/path-tracer-realtime (createRealtimeTracer(scene, { width, height, bounces, ... }), then frame(camera) for every picture) draws the WebGL2 tracer fast enough to move the camera. It shares the WebGL2 context of the GPU still, so one render at a time owns it, and it draws to canvas (an OffscreenCanvas or a canvas element, 8 bit, ACES view transform). readFrame() returns the same picture as bytes. The pieces, each in its own module so they can move to the WebGPU backend:
- Half-size tracing. One path per pixel and frame at half the output size (
resolutionDivisor, 2), two bounces (bounces, 2). The first hit picks one light by importance instead of tracing a shadow ray to every light, which the denoiser averages over frames. - Radiance cache (
src/path-tracer-radiance-cache.js, SHaRC style). A cell is the quantized position (cells double in size each time the distance from the eye doubles past 64 cells) and the quantized normal of a surface point, hashed into 2^20 slots with no collision check (about 0.4% of 7,500 test cells collided). The last hit of a path reads its cell instead of tracing on; the hit before it writes what the rest of the path brought back, and a point pass adds the records into the cells with additive blending (WebGL2 has no atomics), as a running average of up to 128 records. The cache reads as diffuse. It needs the scene to rest: a new scene empties it. - Temporal denoiser and upsampler (
src/path-tracer-temporal-denoise.js,src/path-tracer-reprojection.js, SVGF style). The light is divided by the albedo, reprojected history (bilinear, rejected where distance or normal differ) is blended in over up to 48 frames, the variance comes from the history of the luminance (from the 3 by 3 neighbours while the history is short), four a-trous passes filter with plane distance, normal and variance guided luminance weights, and a joint bilateral upsample to the output size multiplies the albedo history back in. A sample far above its neighbours is clamped while the history is short.
What it is not (the issue asked for more): primary hits are traced, not taken from a raster G-buffer (the tracer's first hit already writes albedo, normal and distance; sharing the rasterizer's depth pass would save a ray per pixel and is left open), and the WebGL2 backend's motion vectors come from the camera's move only, so a moving part would ghost there (the WebGPU backend follows moved parts, below). Material ids are not used for history rejection on the WebGL2 backend (the WebGPU backend uses them, below). The upsample is a joint bilinear filter over half-size data with jittered rays averaged over time, not a full-size accumulation.
WebGPU backend (createRealtimeTracer(scene, { backend: 'webgpu' }), src/path-tracer-realtime-webgpu.js, -kernel.js and -passes.js). The same frame as WGSL compute in one command buffer. The megakernel of src/path-tracer-webgpu.js gets the cache pieces through buildMegakernelSource({ realtime: true }): the last hit reads the cache table, the hit before it writes a record, the first hit also picks one light by importance, and the entry point writes radiance with distance, albedo, normal and the material of the first hit to a frame buffer. The cache update is two dispatches: records are summed per cell with atomic adds on fixed point numbers (1/1024, a record clamped at 32), then every cell folds its sum into its running average (up to 128 records) and empties the sum. The denoiser (accumulate, four a-trous steps, upsample with tone mapping) is the same maths as the WebGL2 passes, with one addition: history is rejected where the material at the first hit differs, which stops the light of one surface from bleeding into a neighbour it passes behind. The result is packed into a buffer and copied to canvas (the tracer's own, or options.canvas). Without navigator.gpu, an adapter or 10 storage buffers per stage, backend: 'webgpu' falls back to WebGL2 and the tracer reports backend and fallbackReason. Differences to the WebGL2 object: frame(camera, { wait: true }) returns { frame, done } (await done to time a frame), readFrame() and update() return promises, and it does not share the WebGL2 context, so it can run beside a WebGL2 render. bench/realtime-tracer/run.mjs --backend webgpu measures it (one output directory per backend).
Measured on the RTX 3060 with bench/realtime-tracer/run.mjs (1920 by 1080 output, 960 by 540 traced, median of 200 frames, three runs of a fresh tracer, the card held by the job): lit-interior 20.0 to 20.1 ms orbiting and 20.1 to 20.5 ms resting; the demo room (tests/fixtures/demo-room.recipe.json) 20.2 ms orbiting 0.5 degrees per frame (it turns away from the heavy view) and 36.2 to 36.3 ms at the scene's own camera, 27.6 frames per second, 3 ms over the 33 ms target. With bounces: 1 the demo room at its own camera took 24.5 ms (one run of 100 frames). On a shared card the same runs took up to 62 ms, so time it behind the GPU lock. FLIP of the frame after one second of rest (51 frames) against Cycles, lit-interior: 0.0637, against 0.0769 for the 64 sample still (the demo room has no Cycles render). bench/realtime-tracer/score.py scores it and sheet.py makes the contact sheet of a camera move: no trails behind the sphere, box or sign in either scene, but a fast move leaves visible speckle in dark parts of the demo room, where one sample per pixel and a cold cache are not enough.
WebGPU backend, second round (issue #624, bench/realtime-tracer/run.mjs --backend webgpu, same card, a loaded machine, so compare rows of one run only). Tried and not kept: a temporal history at the output size (each output pixel gathering the traced samples by their jittered positions) cost 6 to 7 ms on the demo room (21.4 to 27.7 ms at rest) and did not lower FLIP against Cycles on lit-interior (0.0579 against 0.0597 after 60 frames), so the remaining error is the lighting, not the resolution of the history. Moving parts: update({ parts }) with the same part count keeps the history and cache, and a per-part motion table (partMotionTable in src/path-tracer-reprojection.js, indexed by the material id the kernel already writes) reprojects history on a part that moved or turned and rejects it on a part whose geometry changed. In the sliding box bench (--mode ghost) the trail left behind is the same with and without the table (1.69 levels in both), because the material id test already rejects the empty floor; what the table adds is history kept on the moving surface, which that bench does not measure. A scene update still rebuilds the BVH and the kernel (about 0.5 s), so this is not yet a per-frame animation path. Primary hits from a raster G-buffer are not done.
WebGPU backend, same setup (2026-11-09, --backend webgpu, median of 200 frames, three runs of a fresh tracer, card held through the GPU lock, awaiting onSubmittedWorkDone after every frame): lit-interior 10.6 to 11.0 ms orbiting and 12.1 to 12.2 ms resting (WebGL2 in the same session: 20.1 to 20.3 ms and 20.1 to 20.3 ms); the demo room 12.0 to 12.5 ms orbiting and 19.6 to 19.9 ms at the scene's own camera (WebGL2: 20.4 to 31.9 ms and 36.3 ms), so the 33 ms target holds with 13 ms to spare, at 1920 by 1080 output and 960 by 540 traced. The kernel compiles in 0.46 s against 10.8 s. FLIP of the frame after one second of rest against Cycles, lit-interior: 0.0504 (84 frames) against 0.0637 on WebGL2 (51 frames), the gain mostly from the frames that fit in the second. The contact sheet of a camera move on the demo room (8 frames, 2 degrees each) shows no trails; speckle in the dark floor is as on WebGL2. Left open: primary hits from a raster G-buffer, per-object motion vectors, and full-size accumulation instead of the joint bilinear upsample.
Cold first draw (issue #861)
The first path traced draw of a fresh page on the gpu backend took 108 s for one sample of lit-interior (960 by 540, RTX 3060, ANGLE on Direct3D 11, a profile with no shader cache, bench/reference/cold-draw.mjs). All of it was the driver building the kernel: scene load, BVH, packing and texture upload together took 0.15 s, linking took 73.9 s and the first dispatch another 34.1 s (the driver finishes its work on first use), while every later draw took 7 to 35 ms. The compiler inlines each call, and addLights called the emitter sampling and the shadow ray from four places, so the traversal was built five times. addLights now has one loop for "every emitter" and "one chosen emitter" and the kernel holds one shadow ray (tests/path-tracer-gpu-kernel-size.test.js counts the call sites of each variant and the size of the plain kernel). After the change three cold runs on the loaded machine took 27.4, 35.6 and 46.6 s (15.6 to 25.4 s linking, 11.6 to 21.1 s first dispatch), and the old and new kernels compiled side by side in one page took 36 and 7.8 s, 23 and 6.5 s. The progressive tracer at 320 by 180 first step with the random, importance and tree kernels went from 22.9, 18.5 and 38.7 s to 10.3, 9.2 and 14.1 s. That run was not yet reliably under 30 s, and merging the two copies of the traversal (the camera path and the shadow ray) was planned as the next cut; the measurement below supersedes that verdict. The images of lit-interior and spot-area at 1, 4 and 8 samples with the random, importance and tree kernels are byte for byte the same as before (18 PNGs, MD5). A second page of the same browser session starts in 0.14 s, since the driver program cache is shared, and the compiled kernel is kept per page by getKernel. The webgpu backend compiles its kernel in about 0.5 s.
Measured later with the same kernel source (the only changes since are to the bench and its test), three cold runs of lit-interior at 960 by 540, each in a fresh browser behind the GPU lock (bench/reference/cold-draw.mjs lit-interior --runs 3; the bench starts one browser per run, since pages of one browser share the driver program cache and a later page starts in 0.1 s): the wall time of the call was 9.56, 9.54 and 10.17 s. The 27 to 47 s runs above were taken on the loaded machine, the runs here behind the GPU lock on an otherwise idle card; this PR did not isolate which of load or the browser setup explains the gap, so read the 9.5 to 10.2 s range as the idle-card cold time and 27 to 47 s as the loaded one. Link and wait for completion took 4.06 to 4.32 s, the first dispatch with its readback 5.35 to 5.76 s, and every other named phase (scene load, module import, trace scene and BVH, context, source, compile and link submit, scene and texture upload, uniforms and targets) added up to 0.04 s. The named phases cover the wall time to within 0.06 s (the bench prints wallSeconds and unexplainedSeconds). The kernel is 45 KB, one program per scene. tests/path-tracer-gpu-kernel-size.test.js now holds a source size limit for each of the eight kernel variants, one main per kernel and one place that builds a program, so a larger kernel or a second program fails the test.
Metal against Cycles (issue #959)
Two things made Cook's metal scene differ from Cycles outside the fireflies, and both are fixed in the shared WGSL of the native and the webgpu backend:
- Rough metal lost energy. Single scattering GGX drops the light that bounces between microfacets, 8 percent head on at roughness 0.5 and more at grazing angles. The specular lobe now carries the multiple scattering factor of Fdez-Aguera (2019) from a table of the lobe's white albedo (
specularWhiteAlbedo, integrated over the hemisphere with this kernel's Smith masking), also applied to dielectric highlights. - Sparse bright speckle on the floor near glossy metal came from diffuse, glossy, light paths. After a bounce Cook now widens the glossy lobes the way Cycles'
filter_glossy = 1does: the smallest sampling density met on the path sets a floor of0.5 * sqrt(1 - pdf)for the lobe's alpha.
Measured on the metal scene at 960 by 540, 256 samples, 8 bounces, firefly clamp 1000, against Cycles 5.3 at 4096 samples (Modal, A10 and L40S, seed 1; Cycles itself at 256 samples for the same scene):
| relMSE without the 100 worst pixels | mean against Cycles (R, G, B) | |
|---|---|---|
| Cycles 256 samples | 0.00038 | 0.99988, 0.99975, 0.99963 |
| Cook before | 0.00386 (10.1 times) | 0.99434, 0.99643, 0.99639 |
| Cook after | 0.00071 (1.85 times) | 0.99794, 0.99717, 0.99628 |
The mean is still 0.2 to 0.4 percent low, so the 0.1 percent target is not met; the part that is left is not the metal lobe's energy, since the multiple scattering on its own overshoots red. The same four seeds gave means within 0.01 percent of each other, so the remainder is a bias and not noise.