Host lifecycle

`PathTracer` is the largest single owner of GPU state in the engine: roughly thirty images, a host-visible material SSBO, one descriptor set, an RT pipeline, a shader binding table, and five optional denoise/post backends held by pointer. `init()` runs six build steps whose order is forced by data dependencies, not taste: `createRTPipeline` needs the descriptor set layout to build a pipeline layout, and `createShaderBindingTable` needs the finished pipeline to query group handles plus `vkGetBufferDeviceAddress` to publish the SBT's strided regions — which is itself resolved in step one.

Step one exists for three of the four pointers it fetches. `vkCreateRayTracingPipelinesKHR`, `vkGetRayTracingShaderGroupHandlesKHR` and `vkCmdTraceRaysKHR` are `KHR` extension entry points that no loader exports as core symbols; they are looked up by name on the device and the whole init aborts if any comes back null — the cheapest place to discover that a device advertised the extension but the driver did not deliver it.

The fourth pointer the same function loads is not a ray-tracing entry point and does not share that justification. It is fetched under the unsuffixed name `vkGetBufferDeviceAddress` — core Vulkan since 1.2 — and the instance is created with `apiVersion = VK_API_VERSION_1_3`, so on a conforming loader it cannot come back null and its term in the `&&` chain is dead.

One number in the pipeline create-info is worth pausing on. It declares a maximum ray recursion depth of two, with a comment that path tracing "needs bounce recursion" — but the bounce loop in every raygen variant is iterative, and no closest-hit, any-hit or miss shader in `shaders/rt/` calls `traceRayEXT`. Every ray is launched from the raygen, so the pipeline never recurses past depth one.

The caller passes display dimensions; `PathTracer` keeps two pairs. `m_outW/m_outH` is what was asked for, `m_width/m_height` is what the raygen dispatch and every AOV are sized to. They are equal in every mode except a DLSS upscaling preset, where `computeRenderResolution()` shrinks the render pair.

The shrink is not a plain multiply: DLSS wants even dimensions, so the scaled value is masked down to even and floored at two — the render resolution is therefore almost never exactly `scale × output`.

Two images escape the render pair, and both are sized to *output*. The RGBA8 beauty is the first: under upscaling it is the full-res target the DLSS tonemap writes, so the raygen's own beauty store into it at render size is discarded.

The second is the DLSS-RR `COLOR_OUT` image — RGBA16F, allocated at the end of the same `createImages()` behind `#ifdef OHAO_DLSS_ENABLED`. It is what DLSS upscales the render-res guide buffers *into*, which is exactly why it cannot be render-sized; the DLSS tonemap compute then reads it and writes the RGBA8 beauty. Both exceptions therefore exist for the same reason, and both are live in the one mode where render and output differ.

`init()` runs before any denoise mode has been applied, so the scale there is always 1. A later `setRenderSettings()` that switches into DLSS-RR is what triggers the device-idle, destroy-all-images, recreate-all-images pass.

The same incompleteness forces the constructor and destructor out of line: a `unique_ptr` to a forward-declared denoiser cannot instantiate its deleter in the header. Both live in `path_tracer.cpp`, the one translation unit that includes every backend's real header.

There is no descriptor caching and no per-frame-in-flight duplication: the pool is created with `maxSets = 1` and `render()` rebuilds up to 29 writes from scratch before every trace. The array is sized exactly to the worst case, so adding a binding without growing it overruns a stack buffer.

Several of those slots are geometry SSBOs the scene may not have uploaded yet. Rather than skip the write and leave a descriptor undefined, every null buffer handle falls back to the material buffer — a 256-entry host-visible allocation that always exists after `init()` and therefore doubles as the universal dummy.

Rewriting one shared set is only defined if no pending submission still references it, and nothing here establishes that. `renderRTPipeline()` waits on the fence of the frame slot it is about to reuse — frame *N−3* — and `MAX_FRAMES_IN_FLIGHT` is 3, so frames *N−1* and *N−2* can still be executing when `vkUpdateDescriptorSets` lands on the same `VkDescriptorSet`. Of the 36 bindings only binding 12 carries `UPDATE_AFTER_BIND`; the other 35 do not. Treat this as an open hazard rather than a contract: the fixes are a per-frame-in-flight set, or a wait that covers every in-flight submission.

The push-constant block is asserted at 256 bytes — the device maximum on most RT GPUs — so when a genuine per-frame sample count was needed there was no room to append a field. It went into the high half of the word that already held the bounce limit.

Only the realtime raygen unpacks the high half and loops on it; the base and offline raygens mask it off and trace one path per dispatch. The same push constant means two different things depending on which SPIR-V the profile loaded.

No mode samples at pixel centre. Every raygen already draws its own stochastic sub-pixel offset per sample — `getSample2D(dimIdx) - 0.5` — and adds it to the primary-ray UV in all denoise modes.

What the host contributes, and only when the mode is NRD or DLSS-RR, is the second term in that sum: `pc.jitter.xy`, a *deterministic* offset. Determinism is the whole point — the same numbers are handed to the denoiser so it can subtract them during temporal reprojection. NRD receives them as `cameraJitter`/`cameraJitterPrev`; DLSS-RR receives them negated as `InJitterOffsetX/Y`. A shift the denoiser could not name would misalign history rather than widen the footprint. The offset is the radical inverse of the frame index in bases 2 and 3 — the Halton sequence — recentred on zero:

$b$ is the base, $d_k$ the digits of index $i$ in that base, and $\mathbf{j}_n$ the pixel offset for frame $n$. The loop in `render()` is that sum written out, with `f` accumulating $b^{-(k+1)}$. The index is taken modulo 16 and then incremented, because $\Phi_b(0) = 0$ would spend one of the sixteen slots on "no jitter at all". Every other denoise mode gets `pc.jitter.xy = 0` and keeps only the sampler's own random offset.

`m_sampleIndex` and `m_historyFrameCount` both advance once per frame and are not interchangeable: the first seeds the sampler, the second drives temporal logic. A reset sends the history counter to zero but restores the sample index to a caller-settable seed rather than zero, so finite-difference and inverse-rendering runs replay an identical sample sequence across parameter perturbations.

The accumulation buffer is never cleared. On the frame where the history counter is zero its barrier declares the old layout `UNDEFINED`, licensing the driver to discard the contents; on every later frame the same barrier is a `GENERAL → GENERAL` read-modify-write acquire.

The post-processing images use the same idiom with per-instance latch booleans instead of a shared counter — and `createImages()` re-arms them, so a resize re-fires the `UNDEFINED → GENERAL` transition on the freshly created `VkImage` instead of trusting a stale "already transitioned".

The descriptor set layout declares 36 bindings. Bindings 29–34 are the ReSTIR GI reservoir ping-pong and 35 is the DLSS specular hit-distance guide; all seven images are created and destroyed with the rest, and the realtime raygen declares all seven. It cannot store to all of them: 29–31 are the *prev* half of the ping-pong, declared `readonly` and only ever `imageLoad`ed. Stores go to 32–34, the *curr* half declared `writeonly`, and to 35.

No `vkUpdateDescriptorSets` call anywhere in `ohao/` targets those bindings — the per-frame rewrite stops at 28, and only binding 12 carries `PARTIALLY_BOUND`. Those descriptors are never written while a shader reads them. Treat the reservoir plumbing as allocated-but-unwired until a writer appears.

• `init()` must not be reordered: function pointers first, descriptor layout before pipeline layout, pipeline before SBT.
• The two profile renderers each own a full `PathTracer`, and each `PathTracer` allocates its own set of roughly thirty images, so an eager pair doubles the render-target footprint. They are created lazily on the first `setRenderMode()` into that mode instead.
• The single descriptor set is rewritten from the host at the top of `render()`, and bindings 13–16 flip between ping-pong views each frame, so the rewrite is not idempotent — and it is not synchronised against the two more recent submissions that may still hold the set.
• `setMaterialAlbedos` / `setMaterialData` copy at most 256 entries and silently drop the rest — the material SSBO is a fixed 256-instance allocation.
• `destroy()` waits for device idle, tears down the denoisers, nulls the borrowed CDF handles, and only then destroys the SBT, pipeline, descriptors, material buffer and images. The destructor calls it, so an object outliving its `VkDevice` is a use-after-free.
• Switching to or from a DLSS upscaling preset reallocates every render target, so `setRenderSettings()` is safe only between frames — never inside a command buffer.
• The `PathTracerShaderSet` defaults name `rt_pt_raygen.rgen.spv`, but both shipped profiles pass explicit sets (`..._realtime`, `..._offline`), so the default never loads in-tree.