# Path Tracing The path-tracing mode after the 2026-07-22 overhaul (commits `27fddfd8` → `81799ea2`). Everything here is **shipped** behaviour; the PT survey's status is at the end. ## Pipeline shape One compute kernel, `Resources/ShadersSlang/path_tracing/path_tracing.slang`, dispatched by `PathTracing::recordCommands` between two image barriers that move the rasterizer's offscreen target (`rgba16f` since the HDR unit, `OUT_IMAGE_BINDING`) to `eGeneral` for the compute write and on to `eShaderReadOnlyOptimal` for the post pass. Both sit in the frame's graphics command buffer, so no queue-family ownership transfer is involved. The post pass samples that target like any other mode: path tracing replaces the *lighting*, not the presentation path. Rays traverse with `GL_EXT_ray_query` against the RT mode's TLAS; geometry/material data arrive via buffer-device-address (`ObjectDescription` → vertex/index/material-id/material arrays). The record path dispatches only when a TLAS exists: during the async model load there is nothing to trace against, and dispatching anyway used to consume never-written descriptor sets. Neither the bounce ray nor the NEE shadow ray traces `RAY_FLAG_FORCE_OPAQUE`. A ray query has no any-hit stage, so glTF MASK cut-outs are alpha-tested inline in each query's candidate loop, via the `ray_hit_masked_out` helper shared with `raytracing/raytrace.rahit.slang` (`Resources/ShadersSlang/common/alpha_test.slang`). A candidate triangle is committed with `CommitNonOpaqueTriangleHit()` only when the test passes; not committing is the discard. The shadow ray keeps `RAY_FLAG_ACCEPT_FIRST_HIT_AND_END_SEARCH`: it ends the search at the first *committed* hit, so a masked-out candidate does not end it early. ## The estimator Per pixel and frame, `samples_per_pixel` independent paths (GUI slider, default 8), each up to `max_bounces` segments (GUI slider, default 8). Changing either slider resets the accumulation (a mean over two different estimators is biased). - **Primary ray** from the precomputed `inv_view`/`inv_projection` in `GlobalUBO` (the kernel used to invert both matrices *per sample*: 24 4x4 inversions per pixel per frame), jittered uniformly within the pixel's unit square (a box filter) instead of always through the exact centre, so `samples_per_pixel` and the temporal running mean anti-alias geometric edges rather than just denoise a point-sampled image. - **Hit**: throughput *= albedo (texture, or `material.diffuse` when `textureID` is -1). Normals are transformed as directions (inverse-transpose via row-multiplying `worldToObject`); the hit normal is face-forwarded against the ray. - **Next-event estimation**: one shadow ray per bounce toward the GUI directional light; unoccluded hits contribute `throughput * NdotL * (1/pi) * dirLight.color.rgb * dirLight.color.w`. The throughput carries the albedo, NEE the Lambertian 1/pi: without it lit surfaces measured 208.5 crop luminance vs 188.2 correct (forward: 158.1, the gap being PT's indirect sky). NEE is the only connection to the GUI light; before it, the mode's sole light source was an accidental radiance-1 "white furnace" on miss. The BOUNCE path needs no 1/pi: cosine-weighted sampling of a Lambertian cancels the pi and the cosine exactly. - **Bounce**: RTIOW-style cosine-ish sampling (normal + random unit vector), with the degenerate-scatter guard (a near-zero sum falls back to the normal). The sampled direction is renormalized before it becomes the next segment's `rayDirection`: the unnormalized sum has length in `[0, 2]`, and `TMin`, `TMax` and the miss gradient below are all measured in units of that vector's length. From the fourth segment on, **Russian roulette** terminates low-throughput paths and reweights survivors (unbiased). - **Miss**: a soft RTIOW gradient sky at half intensity ends the path. Self-intersection is guarded by a 1e-4 normal offset **and** ray-query `t_min = 0.001` (matches the RT path). `KATAGLYPHIS_PT_FURNACE=` forces every hit's albedo to 1 and replaces the gradient sky with a uniform `` environment; the shader gates on `pc_ray.clearColor.w > 0.5`. It is read via `getenv` once per `recordCommands` call, not cached, so several tests sharing one process each see their own setting. This is the classic white-furnace test: an unbiased estimator must converge every pixel to exactly the environment radiance, for any geometry. `GoldenRender.PathTracingPassesTheWhiteFurnaceTest` is the oracle. ## Temporal accumulation The kernel folds the frame index into the RNG seed (without it, every frame drew bit-identical samples) and keeps a running mean in a dedicated `rgba32f` history image (`ACCUMULATION_IMAGE_BINDING`): full float, because averaging in the output target (`rgba8` before the HDR unit) would quantize and stall after a few frames. There is exactly **one** history image, deliberately not per swapchain image; a compute→compute barrier orders each frame's read-modify-write against the previous frame's dispatch across command buffers. The history resets whenever its premises die: | Trigger | Where | | --- | --- | | Camera moved (view-matrix compare) | PT branch of `record_commands` | | Quality sliders changed (different estimator = biased mean) | same | | Swapchain resize (extent-sized image is recreated) | `recreateSwapChain` | | AS rebuilt - model load/reload OR GUI transform moved the traced world | `updateRaytracingDescriptorSets` | The AS-rebuild trigger was found the hard way: without it, the mean kept blending frames of the *half-loaded* scene until the camera happened to move, and that healing motion mimicked convergence well enough to make a naive golden pass with per-frame sampling disabled. ## Verification Eight PT- and RT-facing goldens in `Test/commit/VulkanEngine/goldenRenderSuite.cpp`, each red/green-proven against the pre-fix shader. Numbers are post-HDR: before the HDR unit, lit surfaces clamped at the UNORM ceiling (186 after tonemap) and hid most of every light response; lifting it widened several margins dramatically. - `PathTracingAccumulatesAndConverges` - consecutive-frame changed-pixel fraction in a GUI-free crop: 7.6e-3 early, 3.1e-5 late; the frame-invariant seed measures exactly 0 early and fails. - `PathTracingAntiAliasesGeometricEdges` - the shadow rig's slab against the sky: a jittered, accumulated primary ray blends that edge in 312 of 312 columns, a pixel-centre-only kernel in none, so it fails. The oracle, and why every edge in the crop stopped being it on 2026-10-12: `gpu-golden-testing.md` § The riscv64 light variant. - `PathTracingRespondsToTheDirectionalLight` - radiance 10 vs 0 on the shadow rig: swung fraction 0.751 (0.027 pre-HDR - the ceiling hid three quarters of the response) vs exactly 0 for the pre-NEE kernel. - `PathTracingHonorsTheQualityControls` - bounce cap 8 vs 1 swings 0.255 (all indirect sky light vanishes); hardcoded-bounds kernel: 7.3e-5. - `RaytracedWorldFollowsTheModelTransform` - a GUI move must change the traced image: 0.397 vs exactly 0 on a stale TLAS. - `PathTracingPassesTheWhiteFurnaceTest` - furnace-mode crop converges to mean luminance ~231.6 (`linear_to_srgb(aces_tonemap(1.0)) * 255`, since `post.slang` encodes for the UNORM swapchain) with >98% of pixels within +-6 of that value; a biased estimator either drifts off 231.6 or leaves visible geometry in the (supposedly uniform) image. - `RaytracedLargeMeshDoesNotLoseTheDevice` - the RT pipeline must survive 10 frames against the shipped large dinosaur-mesh debug scene; it scopes the `VK_ERROR_DEVICE_LOST` the PT reproducer hit on the same mesh to `path_tracing.slang`/`RayQuery` rather than the shared vertex-upload/BDA path (`gpu-golden-testing.md` § Known issue: path-tracing compute device-lost on the large dinosaur mesh, BACKLOG.md). - `RaytracedShadowsAreDarkerThanLitGround` - the RT closest-hit path, not PT: on the shadow rig the darkest decile of a GUI-free crop must stay under 5% of the brightest decile's luminance. Measured 0 vs 244 with the fix, 41.6 vs 248 when `raytrace.rchit.slang` seeds its payload with the unlit albedo (`e852ac99`). The instrument cautions these goldens were built on are in [`gpu-golden-testing.md`](gpu-golden-testing.md)'s cautions section. Editing the kernel needs no C++ rebuild: the Slang compile script regenerates the `.spv` and the engine loads it at startup. `scripts/windows/Build-SlangShaders.ps1` is the build/CI path. ## Open work (BACKLOG, "PT survey" section) None: all 11 items of the 2026-07-22 PT survey are resolved (`8cf33378`). The last, RNG decorrelation (item 11), closed as a measured null result: lag-1 autocorrelation of the depth-2 noise field is -0.012 (lag-16: +0.015), because the LCG pre-step plus the PCG output hash already decorrelate adjacent linear seeds. `PathTracingAccumulatesAndConverges` logs both lags, unasserted, so a future seed change shows its noise character.