3D engine that AI agents drive
Cook (path tracer)
Cook (crucible/addons/path-tracer) is the Crucible offline path tracer (a nod to both the Cook-Torrance microfacet BSDF and "let it cook"). Alongside Glaze (CrucibleRenderer) 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 'crucible/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 (
keyColortimeskeyIntensity,lightDirection, as a 1 degree disk; no sun when that is 0), point lights with a radius (a sphere, as Blender draws it with Soft Falloff off; a point or spot light takessoftFalloff: truefor the oriented disk of Blender's default Soft Falloff on the nativecycleskernel, and the other tracers ignore it, 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.Light portals (native
cycleskernel, the CPU tracer and the WebGPU tracer): an area light withportal: trueemits nothing and marks a window. While the scene has a portal and an environment map, sky light is sampled through the portals (a point drawn on a portal, the pdf of the solid angle it covers, and the same pdf in the MIS weight of a BSDF ray that escapes), not over the whole map, so a room lit only through a window converges instead of flickering. It is the Cycles portal, and unbiased: the picture keeps its mean. A portal must be a rect light; itsdirectionpoints into the room,widthandheightare the opening, and it needs nocolororintensity. Put it on the window plane, over the opening, and use one per opening:environment.areaLights = [{ position: [-2, 1.5, 0], direction: [1, 0, 0], up: [0, 1, 0], width: 2, height: 1, portal: true }];A shading point behind the portal (outside) is lit by BSDF samples only, and a ray that reaches the sky by another way than a portal still counts in full. The CPU tracer samples the sky through the portals in the same way (
src/path-tracer-portal.js: a portal chosen uniformly, a point uniform on it, the pdf summed over the portals the direction crosses), and its next-event light for the sky is drawn through them. The WebGPU tracer does the same in its megakernel and wavefront kernels (the portals sit at the end of the environment table buffer), and the real-time WebGPU tracer does not use them yet. The WebGL tracer draws no light from a portal and names it inreport.ignored. The agent scene tools take it:environment.areaLights[].portalin a recipe orset-environment(a boolean;trueneeds a rect light withwidthandheightabove 0, anything else is rejected with the field name). A render job passes the portal to the trace scene Cook reads; the rasterizer draws no light from it (the light emits nothing there) andscene_inspectlists aportal-ignored-by-rasterdiagnostic.scene_capabilitiestopiclightPortalsnames the field.
Exposure (#1833): a render job's
effects.exposuremultiplies the traced linear picture before the view transform, on the CPU, WebGL and WebGPU backends and on a native frame;renderPathTracedImageandtoneMapToRgba8take it asexposure(a number above 0, default 1), and the linear pixels it returns are not scaled. A scene with no sun, sky or lamp traces black.ambientIntensitymultiplies the environment map strength, as it scales the rasterizer's environment light (Cycles: the World Background strength;src/path-trace-terms.js); a camera ray still sees the sky at the unscaled strength on the native kernel.fillIntensity(two fixed unshadowed lights) andworld: true(outdoor haze shading) are rasterizer only, and the render report says so when a recipe sets them.daylightandskyTop/skyBottomchange nothing in the rasterizer while an environment map lights the scene, which every recipe has, so the trace agrees.world: falsehides nothing from the trace: a camera ray sees the environment map, where the rasterizer draws a flat background. Light the shadow side with a point or area light orenvironmentIntensity.
Raster against tracer on a daylit interior (#1334, bench/reference/interior-exposure.mjs: an 8 x 6.5 m room with one window, physical sky, sun bounce 2, AgX, 960 x 540, GPU tracer, 48 samples, no denoiser). Before #1833 the tracer ignored effects.exposure, so the room looked about 3 stops darker than the raster at exposure 3.6. Now both apply it, and the tracer is the brighter one, because it carries the light that bounces around the room and the raster fill is lower (raising sunBounce to 8 lifts the raster mean only from 31.9 to 47.6 of 255):
effects.exposure |
Raster mean (display, linear) | Tracer mean (display, linear) | Tracer over raster, linear |
|---|---|---|---|
| 1 | 16.7, 0.0143 | 33.5, 0.0278 | 1.9 |
| 3.6 | 31.9, 0.0385 | 73.1, 0.1042 | 2.7 |
The sunlit floor patch agrees to within a stop (158.8, 127.2, 82.1 against 134.2, 106.0, 74.2 at exposure 1); the gap sits on the walls and ceiling in shade (display 37 against 17 on the back wall at exposure 1). A sealed room still traces black (0.0006 linear), so the extra light is not leaking sky. Since #1334 the raster adds the bounced sky light of a closed room (docs/lighting.md), which brings this probe from 2.6 times darker than the tracer to 1.34 times; the tracer is still the brighter one. To match a raster look with the tracer, lower effects.exposure (about 1 where the raster used 3.6 in this room) rather than raising it past its cap of 16.
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.Sky strength seen by the camera (native
cycleskernel only, #1121):environment.cameraIntensity(a number of 0 or more, in the units ofmap.intensity; left out, the camera sees the sky at the lighting intensity and nothing changes) is the strength of the sky for a camera ray and for a ray that reaches it from the camera through a cutout, a transparent surface or smooth glass, while the sky keeps lighting the scene atmap.intensity. It is what Cycles does with a Light Path 'Is Camera Ray' mix in the world, and it replaces a second trace with the opaque surfaces black. The strength applies until the path first bounces off a diffuse or glossy surface, reflects (also off glass), crosses rough glass or a translucent surface, or scatters in fog; sun disks and emissive surfaces are not scaled. The CPU, WebGL and WebGPU tracers ignore it andreport.ignoredsays so.
// A room lit by the sky at full strength; the view through its window is drawn at 0.2 of it, in one pass. const environment = { map: createEnvironmentMap({ width, height, data, intensity: 1 }), cameraIntensity: 0.2 };
Light and texture inputs (issue #1259)
- An area light with no
up, aimed along the y axis, takes the x axis as its across axis; an explicitupparallel todirectionis refused. - A point, spot or area light without
colororintensitygets white and 1, as the rasterizer does. A colour that is not three finite numbers from 0 up, or an intensity below 0 or not finite, is refused with the field name. - A map's
wrapSandwrapTapply to U and V on their own: repeat (10497), clamp to edge (33071) and mirrored repeat (33648). Any other value is refused. The CPU, WebGL2 and WebGPU tracers read the two codes from the texture flags (value 1 both axes repeat, 2 for sRGB, 4 to 12 for U, 16 to 48 for V), and the native tracer getswrapUandwrapV. - A skinned part's normals use the inverse transpose of the blended joint matrix, so a joint that scales unevenly no longer bends them; pixels of such rigs change, rigid and uniformly scaled joints do not.
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. The block is checked with validateSubsurface when the scene is built, so a radius that is not three numbers in range throws and names the field.
Dispersion (issue #1714)
A glass part with a material dispersion above 0 splits white light into colour fringes when you look through it (a prism, a gem). dispersion is 20 divided by the Abbe number, from 0 to 10, the same scale as Blender 5.3 and glTF KHR_materials_dispersion (diamond is about 0.36), and ior stays the index at 587.6 nm. The native tracer (Cook) gives each path a hero wavelength from 400 to 700 nm and bends it with a Cauchy index. 0 turns it off and draws the same pixels as before. The glTF loader reads the extension into the same field.
- It shows when the camera sees through the glass. A rainbow cast by the glass on a diffuse floor is not resolved yet and needs caustics (#1715).
- It is a path tracer feature: the rasterizer and the other tracers ignore the field. The
dispersionof the lens distortion pass is a different, post-process effect. - Dispersive glass keeps signed spectral weights, as Cycles does (codepawl/cook#53), so the fringes match Cycles' saturation: the prism view fringe is 0.94 times Cycles' and its mean colour is within 0.2%. The most saturated fringe pixels can hold small negative values;
rawLinearand the returned linear film keep them, and Crucible clamps them to zero only before OIDN and the display transform. - Measured on an RTX 3060 at 256 samples, a prism or gem view takes Cook 3.1 to 4.5 s against Cycles 1.0 to 1.8 s. Those timings and the 1 to 9% mean colour gap are from before the signed weights, which raised the fringe saturation from 0.67 to 0.90 times Cycles' to the figure above.
- At 1080p Cook takes 8.6 s at 64 samples, 34.1 s at 256 and 138 s at 1024.
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.
postPasses(user post-process passes): the tracer writes the lit frame only and has no first-hit depth, normal or object ID buffer for a pass to read, so a render job returns the plain traced frame. The job completes andmetrics.diagnosticscarries apost-passes-skippedwarning naming the passes (#2226; user-passes.md). Render the look with a raster job.- The procedural sky when there is no environment map (the sky is black).
The native cycles kernel reads an environment map as it is, as Blender Cycles does: a sun stored at tens of thousands lights the scene with all of it. Until #1172 its packer capped every texel at 16, which left a sunlit scene (Pavilion) at 0.77 of its Cycles brightness; without the cap it is at 1.01 (numbers). A caller of the Cook package can still pass hdriRadianceLimit to cap the texels and trade that energy for less noise at low sample counts.
- 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 Cook README); the CPU, GPU and legacy native tracers draw a pinhole. - Clip start (CPU, WebGPU and native
cyclestracers, #1159):camera.clipStartis a distance in scene units along the view axis, like the clip start of a Blender camera. A camera ray starts where it has gone that far along the axis, so a wall between the eye and the clip start is not drawn and the room behind it shows. Leave it out and rays start at the eye, as before; it is separate from thenearplane the rasterizer uses (default 0.1), which would otherwise change every existing render. AclipStartat or pastcamera.faris refused, since nothing would be drawn. The nativecycleskernel reads it as thecamera_nearword of its parameter block (createCamerasetsnearto it), so its rays start at the same distance. The WebGL tracer ignores it and names it inreport.ignored, and so do both real-time tracers, which list the note in theirignoredarray after the first frame with a clip start. - 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; the luminance guide is the pixel's light averaged over its 3 by 3 neighbours on the same surface, so a lone noisy pixel does not decide how much of its neighbours it takes (bench/reference/wavelet-grain.mjs, flat-walled room at 256 samples against an 8192 sample reference: flat-wall grain 0.0073 to 0.0027 with the reference at 0.0033, error 0.00414 to 0.00359); 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 on the cpu backend, and on gpu and webgpu whatever the device holds up to 2,000,000 (MAX_GPU_TRACE_TRIANGLES): the triangle table takes 160 bytes a triangle (ten texels: both UV sets are kept), so a WebGL2 context with a 16384 texel MAX_TEXTURE_SIZE has room for 3,355,443 and one with 2048 for 419,430, and a WebGPU storage buffer of maxStorageBufferBindingSize bytes for that many over 160; the tracer asks the device and an oversized scene is refused with the count, the limit and what to do, the same text for a still, the real-time tracer (WebGL2 and WebGPU) and the GPU light bake (backend: "gpu" or "webgpu"; a bake with a texelTracer of its own keeps the default bound) (a scene exported to the native tracer takes more, see below), 1,024 parts (the CPU and WebGL tracers; a native trace takes more, see below), 32 lights, and finite numbers (positions, normals, uvs, colors) and whole-number, 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.
Instances count per copy on the cpu backend and on the progressive and real-time views (the still gpu and webgpu backends keep a shared mesh once, see "Instanced scenes on the gpu backend"): they copy every placed node into one triangle buffer, so nine nodes that share three 300,000 triangle GLBs count as 2.7 million triangles, not 0.9 million. Over the bound, the error says N triangles after expanding M instanced nodes (U unique) and suggests fewer copies, a simpler GLB or the Glaze renderer. Only the native Cook backend with instancing counts each shared geometry once. The submit-time estimate (scripts/agent-render-estimate.mjs) counts every placed node the same way.
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 unless maximumParts is passed). A value outside that range is refused, and a flattened scene ignores it. A native render job andrender:file-cookread the export from the page as one Blob over the DevTools stream, so no single message bounds the scene: they pass 4,000,000 triangles and 1,000,000 instances, and a scene the adapter cannot hold fails in the tracer.maximumParts(an integer from 1 to 1,000,000,MAX_NATIVE_TRACE_PARTS) replaces the 1,024 parts of a flattened scene and the 1,024 distinct geometries of an instanced one; a native render job andrender:file-cookpass 1,000,000, so a scene of thousands of separate meshes no longer needs instancing to get past the part count, and a scene past it is refused with the count and "merge small meshes". A bound reported by the adapter's memory comes from the engine: before a native job orrender:file-cookreads the scene tables from the page, it asks Cook forreadAdapterCapacity()and compares the unique triangles, instances and texture texels of the export withmaxUniqueTriangles,maxInstancesandmaxTextureTexels(nativeCapacityProbleminscripts/native-capacity.mjs). A scene over one fails with one error that names the count, the limit and what to drop, and the job fails with it instead of running on the gpu backend; a count equal to its limit fits. The report carriesnativeCapacity(each count used with its limit, the adapter and its device-local memory, or why that is missing). This is a different check from the Node memory guard, which watches this process while a job runs. The capacity counts the packed tables only, not the acceleration structure the driver builds, so a scene under every limit can still be refused by the tracer. An engine withoutreadAdapterCapacity, or an addon built before it, skips the check and the tracer stays the last guard. An export that travels as one message (exportNativeSceneTableswith its defaulttransport: "message", which the benches use) passes 1,500,000 triangles and 1,000,000 instances and 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 (
buildJobNativeInputandbuildFlattenedJobNativeInputinjob-input.mjsof@codepawlhq/cook): 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 (withVirtualAtlasinpack-input.mjsof@codepawlhq/cook), 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 set it as a node field (#1081); see "Emitters" below. - Thin clear glass (#1081): a mesh node takes
rayVisibility: 'glass', the shorthand for{ shadow: false }, throughscene_createandscene_apply, and the object form works there too. The tool path validates it (unknown ray kind, non-boolean, group node, orshadowOnlywith shadow off throws and says what to pass) and drops an empty or all-true object, so a scene without a hidden ray kind packs as before. Glass is not detected from the material: a pane that should not block sun and sky says so. - Emitters (#1081): an emissive part hidden from diffuse, glossy or transmission rays is still refused. The kernel samples an emitter by next-event estimation with a multiple-importance weight and weights its bounce hits to match, so culling those hits drops part of its light. Matching Cycles would mean changing that weighting in the kernel, which is not small, so the refusal stays;
camera: falseandshadow: falseremain allowed. This is the reasoned choice, not a measured parity result.
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.
Instanced scenes on the gpu backend (issue #2239)
On backend: "gpu" (stills and the GPU light bake; the progressive and real-time views still flatten) and on the megakernel of backend: "webgpu" (stills and its light bake), parts that share one geometry object stay instances instead of being flattened into one triangle table. buildTraceSceneForDevice asks for instancing when the backend module exports supportsInstancing; a scene where no two parts share a geometry is still flattened, and its tables are the same bytes as before. The packer (src/path-tracer-gpu-instance-pack.js) keeps one copy of each distinct mesh in the triangle table with its own bottom-level BVH, builds a top-level BVH over the world box of every copy, and writes one record per copy (the matrix both ways, the root of its mesh's BVH, its material). The kernel (src/path-tracer-gpu-instancing.js) walks the top level, moves the ray into the mesh space of each copy it reaches without normalising it, so a distance there is a world distance, and moves the normals and edges of the hit back; the instanced variant is a separate compile of the kernel and a flattened scene keeps the kernel it had.
- The GPU triangle limit counts a shared mesh once. The error for a scene that does not fit still says how many triangles it holds; for an instanced scene it counts the unique ones.
- A part that cannot share its geometry (skinned, flush-lifted, box-mapped) is moved into world space once and traced as an instance with an identity matrix, as for the native tracer.
- The WebGPU megakernel reads the same tables (
src/path-tracer-webgpu-instancing.jsholds its WGSL). It keeps its ten storage bindings: the instance records follow the BVH nodes in the node buffer, behind one header vector that names the top-level root, and the parameter wordshadowSlots.wholds the vector index of that header. A scene with no shared mesh compiles the same WGSL as before. The node buffer is bounded by one storage binding (maxStorageBufferBindingSize); a scene over it fails with the byte count, the instance count and "Remove copies or merge small meshes". - The WebGPU wavefront kernel and the real-time WebGPU tracer do not read instances. The real-time tracer asks for a flattened scene and keeps the flattened triangle limit;
traceOnWebGpuwithkernel: "wavefront"andprepareRealtimeKernelrefuse an instanced scene with an error that says so. - The normal of a copy with a non-uniform scale is moved by the inverse transpose and made unit length at each corner before the corners are blended, which is what a flattened copy stores; a flattened and an instanced scene match to float precision (RMSE of the linear image below 1e-6 on translated, rotated, mirrored and stretched copies).
- The report's
trianglesis the unique count.
Choosing a backend
backend: "native" is an agent render job setting, not a renderPathTracedImage option: Cook runs the same kernel on Vulkan ray queries (the render engines guide says how the native backend is found and what happens when it is missing). 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). A grid local volume (environment.localVolumes with shape: "grid", issue #1789) is in the native kernel too, through Cook's gridVolumes: the frame the volume time selects, its box (center, size), density, absorption, scatter (the share of the extinction that scatters, the same for the three colour channels), anisotropy, emission, emissionStrength, temperatureScale and blackbodyIntensity (times emissionStrength, as Blender's Principled Volume takes it) carry over one for one, and the kernel traces the grid with delta and ratio tracking, so the sun, the sky and every light shade it and the fire lights the floor with its own radiance. At most 8 grids and 256 voxels an axis, 8 bytes a voxel, in the texel pool with the textures. Not drawn natively: box, sphere and mesh volumes (the export throws an error that names the kind and says to use cpu or webgpu), emissionRamp (throws), castShadow and lightsScene (Cook shades the grid with the real lights, so they have nothing to switch), and environment.volumeShutter (the velocity channel is skipped: the job report says the blur is ignored). The grid is exported after the materials, so a scene whose materials fall back to the v1 tables throws instead of dropping the volume. On the #1735 blast at its 0.375 s frame (640 by 360, floor and sun, no sparks, no motion blur) Cook at 256 samples takes 15.6 s and has a mean luminance of 0.2148 against 0.2149 for Blender Cycles at 48 samples, a linear RMSE of 0.0233 (display RMSE 0.0096); Glaze is 0.0411 (0.0193) from the same Cycles frame. 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.
The cycles kernel takes clampDirect and clampIndirect in Cycles' unit (Blender's "Clamp Direct" and "Clamp Indirect", 0 = off) and sends three times the value to the kernel, which compares it with the sum of the three colour channels of one contribution; a grey contribution of v per channel is limited when v is above the option you passed. Pick the largest per-channel radiance one bounce may add, in scene radiance units (linear, before exposure). Why 3, what direct and indirect cover, and a starting value: Cook README. The depth guide of the same kernel is the distance to the first surface along the camera ray, also for a sample that scatters in fog before it (#1122); the albedo and normal guides describe the first event, so a sample that scatters first writes the fog's albedo and the view direction (README, first paragraph).
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.
The native backend
The native backend needs the optional Cook package (@codepawlhq/cook) with its built binary and a Vulkan ray query adapter. An npm install of Crucible does not bring it, COOK_DISABLE=1 and JS67_NATIVE_TRACER=off switch it off, and a tracer or adapter failure marks it unusable for the rest of the run.
When a job asks for backend: "native" and it is not available, the job runs on the gpu backend (cpu on a runtime without a GPU) and the report says so: pathTracer.backendNote has the sentence, and pathTracer.backendFallback has { requestedBackend, usedBackend, fallbackReason }. If that fallback then fails, for example on the gpu limit of 2000000 triangles, the error ends with the same reason, what to install and what to pass instead. A job that ran on native, or asked for gpu or cpu itself, has neither field.
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.
Display bytes on the GPU for native film frames
A native session frame (scripts/agent-native-sequence.mjs) with no JavaScript denoiser and no temporal blend asks Cook for its post stage (post: { viewTransform, exposure }, mapped by scripts/native-post-look.mjs), so the 8-bit picture comes from the card instead of the per-pixel loop in toneMapToRgba8. Cook documents 2/255 per channel against that helper, which stays the reference; tests/native-post.test.js checks aces, agx and neutral against it on the real addon. Every other frame (the OIDN or wavelet denoiser, a temporal blend, a 3D look table, a view transform Cook lacks, such as standard, no session) uses the helper, and report.display names the path and the reason. Grain, bloom, vignette, saturation, contrast and temperature are not part of a native film frame today (listIgnoredFrameEffects), so they are not mapped. PNG encoding of these frames goes through scripts/native-png.mjs (Node's zlib does the checksums).
Measured once on the RTX 3060, 1920 by 1080, traced film to encoded PNG, median of 7 (node scripts/benchmark-native-post.mjs): 276 ms with the helper and the portable encoder, 22 ms with Cook post and the Node encoder (post 13 ms, encode about 9 ms; the encode part is a gain for the helper path too).
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/crucible-denoise-oidn (packages/denoise-oidn), not part of the core archive: npm install @codepawlhq/crucible-denoise-oidn, then run node node_modules/@codepawlhq/crucible-denoise-oidn/fetch-oidn.mjs, 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 project that only installed @codepawlhq/crucible gets the wavelet filter. 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, so check it before you judge grain on a job that asked for "oidn"; the note gives the install step above. 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.
What the albedo image holds
The CPU tracer and Cook's cycles kernel write different albedo images today, so their albedo sums do not agree and must not be compared directly (issue #1911):
- Sky. The CPU tracer writes 1 for a pixel whose camera ray escapes. Cook writes the escaped sky radiance clamped to 0 to 1, so a black environment gives 0.
- Surfaces. The CPU tracer writes the base colour of the first hit, or 1 for glass. Cook writes the sum of the lobe weights at the first hit (
closure_eval_albedo): the diffuse weight, plus the specular and coat weights times their Fresnel term.
On the 200-copy scene of tests/native-albedo-reference.test.js (128 by 96, seed 1), Cook's sum is 2489.36 on an RTX 3060. The CPU tracer gives 35042.39 at 64 samples, because about 10,500 sky pixels add 3 each. With its sky set to 0 it gives 2300.81, 7.6 percent below Cook, which is the surface difference. The CPU sum moves 0.2 percent between 16 and 64 samples, so the gap is the definition, not noise (measured 2026-11-17). One shared definition is tracked in #1941.
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.
Path trace a GLB file with Cook
One command turns a GLB, an HDRI and a camera, written as a scene.json file scene, into a path traced picture on the GPU, with the PNG, the raw linear light and a report of what the run cost. It needs the built native addon (npm run cook:build) and a Vulkan ray query card; without the addon it stops with exit code 2 and says so.
npm run render:file-cook -- --config scene.json --out out/frame --width 1280 --height 720 --samples 256 --camera camera.json
scene.json is the file scripts/render-media.mjs --scene file reads. A headless Chrome page loads the GLB with its textures, the command packs the scene into the native tables the render jobs use and Cook traces them with the cycles kernel. The camera of the scene description is used unless --camera names a file like { "eye": [0, 1.6, 6], "target": [0, 1, 0], "verticalFovDegrees": 40 }.
| Option | Default | Meaning |
|---|---|---|
--config <scene.json>, --out <prefix> |
required | The scene and the prefix of every file written. |
--width, --height |
800, 450 | Picture size, 16 to 8192. |
--samples |
128 | Paths per pixel, 1 to 100000. |
--bounces |
8 | 1 to 16. |
--seed |
1 | 0 to 2147483647. |
--max-seconds |
600 | Wall-clock limit of the trace, 1 to 86400. Passing it fails; there is no partial picture. |
--denoise |
oidn |
oidn, atrous or none. Without OIDN installed oidn falls back to atrous. |
--write-raw |
off | With a denoiser, also write the picture before denoising. |
--camera <camera.json> |
scene camera | eye, target and verticalFovDegrees (or fov) replace the camera. |
--instancing |
off | Keep repeated geometry as instances (needed for scenes with many copies). |
--chrome <path>, --software-gl |
Chrome executable for the loader page, and SwiftShader for it. | |
--list-parts <regex>, --hide-parts <regex> |
Write <prefix>.parts.json for matching parts, or leave them out. A pattern is tested against <part name> material:<material name>. |
|
--patch-materials "<regex>={json}" |
Change the matching materials before packing (repeatable), to test a scene fix such as "glass={\"alphaMode\":\"OPAQUE\"}". |
|
--help |
Print the options. |
Files written: <prefix>.png (ACES tone map and gamma, the Crucible view transform), <prefix>.linear.f32 (width x height x 3 little-endian floats, after the denoiser), <prefix>.raw.png and <prefix>.raw.linear.f32 (before the denoiser, with --write-raw), <prefix>.parts.json (with --list-parts) and <prefix>.json, the report, which is also printed as one FILE_NATIVE {json} line.
The report holds everything traceFrameNative reports (adapter, kernel, samples, tracedSeconds, denoiser, triangles, instances, ignored) plus:
loadSeconds(Chrome loads the GLB and textures),packSeconds(the native tables),setupSeconds(both) andsamplingSeconds(the trace). The tracer's own set-up time istracerSetupSeconds.- Kernel compile, apart from trace time: Cook compiles one kernel per scene variant (a scene with no emitter is a different variant from a lit one), so the first trace of a variant in a process spends seconds in
compileSecondswhilegpuTraceSecondsstays the trace itself (tracedSecondsis the whole call, compile included). A compile over one second addskernelCompileNote. On an RTX 3060 a new variant compiled in 5 to 26 s, against 0.02 s to trace it. triangleCount(unique triangles) andinstanceCount(nullwhen the scene is flattened).lightCount: the sun, point, spot and area lights packed for the kernel (emissive meshes are not counted), ornullwhen the packer reports none.peakGpuMemoryMiB: the highestmemory.usedthatnvidia-smishowed, sampled every 250 ms during the trace. It is the whole card, so other programs count; it isnullwithpeakGpuMemoryNotewhennvidia-smiis missing.ignoredFrameEffects: frame effects of the scene description that the traced picture does not get, such asexposure,saturation,contrast,temperature,vignette,grain,bloom,monochrome,fadeandcinematic. The traced picture is only tone mapped.
Exit code 2 means the Cook package or its addon is missing (the message gives the build command); any other failure exits 1 with its message.
Limits known today:
- Unique triangles follow the adapter: the tracer reports
maxUniqueTriangles(4,793,490 on a 12 GB RTX 3060, more on a larger card) and the page packs up to that, never above 16,000,000 and never below the 1,500,000 of a one-message export. With--instancinga geometry counts once; without it every copy counts. The scene is read from the page as one Blob over the DevTools stream, so the size of one message does not bound it. A scene over the limit fails with one message that names the count, the limit and the overage (got 5089446, 295956 too many) and what to drop: share geometry between copies, decimate, or pass fewer triangles. The same holds for instances and texture texels. - Parts: up to 1,000,000 parts (flattened) or distinct geometries (instanced); the 1,024 of the CPU and WebGL tracers does not apply.
- At most 256 point, spot and area lights together. The 16 point, 8 spot and 7 area lights of a drawn frame do not bound a traced one: the kernel picks lights through its light tree. Light linking (
affects) still needs each kind within those drawn limits, because a linked light keeps one mask bit; a scene over them with a link fails with a message that names the list and the count. More emitters than 256 go in as meshes with an emissive material, which have no count limit. - Glass exported from Blender as soft alpha stays alpha (a see-through cutout, not refraction) unless you patch it, for example with
--patch-materials. - There is no camera near clip, so geometry between the eye and the target is drawn.
- Bloom and colour grade are not drawn (see above).
Lights go in the scene description under renderer.environment: keyColor and lightDirection for the sun (sunAngularRadius sets its size), areaLights (position, direction, width, height, color, intensity; portal: true makes a window portal instead of an emitter) and pointLights (position, color, intensity, radius). The HDRI is the hdri path of the same file.
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.
What CI runs (issue #1146)
The required test check builds no addon, so the tests that need it skip there. The Cook addon workflow (not required) builds the pinned Cook with a cached cargo target, runs every test file that loads tests/support/cook.js on the software Vulkan adapter lavapipe and writes the counts to its job summary: tests that passed, failed, skipped (with the reasons) and tests that lost the GPU device. Lavapipe lists VK_KHR_ray_query but loses the device on the first trace, so the tests that draw pixels still need a real GPU: run them with npm run cook:build and node --test tests/native-*.test.js on a machine with a ray query card.
Progressive preview, blue noise and light choice (issue #623)
crucible/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; resolutionDivisors (third argument, default [4, 2, 1]) lists the sizes drawn first as whole numbers from 1 and ends with 1; 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)
crucible/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: A scene it refuses (no parts, over the part cap, local volumes) is checked before any GL object is made or released, so a refused update({ parts }) keeps the scene the tracer had and a refused first scene leaves nothing allocated.
- Half-size tracing. One path per pixel and frame at half the output size (
resolutionDivisor, 2), two bounces (bounces, 2).resolutionDivisorandcacheCellSizemust be above 0,historyLimitat least 1 andfilterIterationsa whole number from 0 to 16, andwidthandheightwhole numbers whose traced size (overresolutionDivisor) stays from 16 to 4096, or the tracer refuses them. 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.