WIP: feat(vk): ray tracing: lights from glowing materials, guide buffers and alpha in the rays without micromaps (on #727) #1151

Draft
Drommedhar wants to merge 152 commits from Drommedhar/Longshot:feat/path-tracing into main
First-time contributor

Type: feat · Risk: medium · Tested on: Windows 11, Radeon RX 9070 XT · Needs: an NVIDIA RTX card (the path with micromaps), Intel Arc, Linux

On top of #727. This branch is rebased onto #727's as it moves (now 19f973b0), so until #727 merges the diff here shows its commits too. Ours are the last 70, nearly all in files of our own; in #727's files we add marked hook lines and #ifdef blocks. #727 has since taken its own versions of three things that started here (cut-outs tested in the ray loop, the mesh-shader cards' bits, the bottom levels' budget from the video memory): those are its commits now, and ours build on them. What we found on the way that concerns #727 itself is in #727 (comment).

Why

With #727 the sun, the sky and the game's few lamps are ray traced. But in a town at night nearly everything that glows, every lantern and every lit window, is a glowing material with no lamp behind it: it lights nothing and casts no shadow, and the warm light round it is baked ambient. And on a card without opacity micromaps (every AMD card today) leaves and fences were solid in the rays, so a tree's shadow was a blob, and Kakariko lay under a sheet of shadow at night.

This is also the groundwork for a path-traced mode: lights that exist as lights, the game's own colour at a ray's hit, and the guide buffers a denoiser or Ray Reconstruction needs.

What changed

Lanterns, lantern glass and windows become real lights with ray-traced shadows, highlights and normal-map detail; rays respect alpha where the device has no micromaps; a ray's hit knows the game's texture colour. All of it is off unless its row or switch is on.

  • Lights from what glows (vk_rt_emit.cpp, vk_rt_emitters.cpp, rt_emitters_policy.h, rt_emit_islands.h): a program's emission read from its SPIR-V; sphere and area lights from lantern bulbs, lantern glass and window panes, a batched draw split into its islands; kept in a world light grid (rt_light_grid.h), so which lights reach a surface depends on the surface's place, never the camera's.
  • Those lights in the picture (RX_VK_RT bit 32, row "Ray-traced lantern lights": Off / Low / Medium / High / Ultra; vk_rt_di.cpp, shaders/rt_di_def.comp): a pass after the lit draws with the diffuse term and a GGX highlight. It traces a shadow ray only for the lights that matter at a pixel (a light under 5 or 10 % of the pixel's unshadowed lantern light is not traced and takes the traced ones' mean visibility), skips pixels where lantern light is under half a percent of their own colour (by day nearly all), and works at half size in the two lower steps.
  • Guide buffers (rt_guide_spirv.h, vk_rt_guides.cpp): the lit programs store the shading normal (normal map included), roughness, albedo and F0, by a SPIR-V patch like #727's own; every guide in 77.8 % of the cache's lit stages.
  • The game's lamp list and ray-traced lamp shadows (RX_VK_RT bit 16; vk_rt_lights.cpp, vk_rt_lamps.cpp, rt_lamp_spirv.h): the lamp list's layout is from #815.
  • Rays without micromaps (RX_VK_RT_ALPHA=1, whose baked opacity bits in the candidate loop are #727's now; ours on top in vk_rt_alphax.cpp, vk_rt_holes.cpp): the game's texture sampled at the hit for a covered cell, terrain patches open at the game's holes, and the kBlocker class (the game's low-detail shadow models) left out of a sun ray whose receiver is within 50 m of the camera, by the ray's instance mask (#727's falling leaves keep casting).
  • Colours at hits (RX_VK_RT_HIT=1; vk_rt_hitrec.cpp, vk_rt_recipe.cpp, shaders/rt_recipe_eval.glsl): a lit program's base colour as a recipe folded per draw, with records for the ground and the mesh-shader cards; so far used by debug pictures only.
  • Looking and tuning (rt_views.h, rt_look.h, vk_rt_show.cpp, vk_menu.cpp): F8 flips between the game's own picture and the traced one, F7 shows one part or one guide buffer alone, F4 to F6 step through and change nine look settings (a collapsible group in the menu, saved with the options).
  • Diagnostics (vk_rt_scene_big.cpp, vk_rt_scene_who.cpp, the emission census): the biggest instances, a leave list, and sun probes that name what a pixel's sun ray meets.
  • One change of #727's behaviour left: the traced sun shadow also in the cascades' channel (distant characters lost their shadows). The reason is in the comment linked above; the other two named there are #727's own now.

Everything is described in docs/ray-tracing.md.

Measurements

Verdict: pending. The numbers below are single headless runs without a frame rate cap (1707x960 internal, FSR 4.1.2, AO Medium, reflections at the Low roughness step), made while building with the desktop in use: the same scene ran up to 1.5 times faster or slower between hours, so only numbers within one line compare. Interleaved medians follow before this leaves WIP.

Baseline: #727 at f70c348d, not main: this branch sits on it.

Hardware: Windows 11, Radeon RX 9070 XT 16 GB (driver 26.11.1), FSR 4.1.2 Quality to 1440p.
Scene: the Market at a shop door and at a pine by night, Kakariko by night, Kokiri Forest; 1707x960 scaled to 2560x1440, no frame generation, no frame rate cap.
Method: one headless run each through the control bridge, 30 to 120 s, the player standing still; brightness as the mean of a fixed crop of the "Sun shadows" view's picture, frame rate from the bridge's status, pass times from RX_VK_GPU_PROFILE=1, the hits' share from the log's rt hit: primary rays line. Not medians.
How to reproduce: a save at each spot, RX_VK_RT=63 RX_VK_RT_ALPHA=1, and the part's own live switch for the before column (exact=0 blockernear=0 and holes=0 in RX_VK_RT_ALPHA_CTL, di=0 in RX_VK_RT_LAMPS_CTL).

Before, the part off: this PR @ f86523bf After: this PR @ f86523bf
A pine's sun shadow near the camera, Market by night (mean brightness, the game's own shadow 84) 63 (shadow models at every distance) 80 to 88
Kakariko by night, the sun term's mean over the village (of 255) 72 131
Primary-ray hits with the game's texture colour, Kokiri Forest (before: this branch @ 11739f5e, without the ground's and the cards' records) 52 % 99.9 %
Lights in the Market at a shop door with four lanterns the game's 2 spots 2 spots and about 130 of ours
Frame rate at that door by night, everything on 74.6 fps with ray tracing off (GPU 10.0 ms a frame) 33 to 38 fps (20 to 24 ms) with the lantern lights at full size and every light traced
The lantern lights' steps at that door (one run): fps, the pass, shadow rays a lit pixel off: 60 fps Ultra 46 fps, 4.2 to 4.6 ms, 7.7 rays; High 51, 2.5 to 2.8 ms, 3.2; Medium 56, 0.9 to 1.0 ms, 3.2 at half size; Low 58, 0.6 to 0.7 ms, 1.8
The lantern lights' pass by day, the Market's square (Medium / High) every lit pixel traced 0.19 / 0.39 ms: 97 % of the lit pixels left out by the floor
The Market's square by day, about 5,500 instances: fps, the render thread's work a frame off: 68.9 fps, 8.6 ms; #727 alone: 30 to 35 fps, 17.5 ms 28 to 32 fps, 21.8 ms (the top level 1.7 microseconds an instance a frame against #727's 1.3)
The sun's and AO's rays, Market by night, with the kBlocker rule 1.74 ms (shadow models at every distance) 1.66 ms

Flags and settings

New menu rows and switches; every one is documented in docs/ray-tracing.md, the rows also in the README's option table.

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
RX_VK_RT bit 16, row "Ray-traced lamp shadows" shadows for the game's own lamps none off a shadow ray a lamp in the lit programs helps wherever the game has a lamp; few places off until measured
RX_VK_RT bit 32, row "Ray-traced lantern lights" (Off / Low / Medium / High / Ultra; RX_VK_RT_DI_SIZE, RX_VK_RT_DI_CUT, RX_VK_RT_DI_FLOOR go over the step) the lights made from glowing materials, in the picture none off diffuse light and highlights with shadows; the steps trade shadow rays and size for time towns at night; by day the floor leaves it nearly free off until measured; Medium where it is on
RX_VK_RT_GUIDES the guide buffers none on only while a consumer needs them every lit pipeline is made again once needed by bit 32's deferred way as it is
RX_VK_RT_ALPHA_EXACT (with #727's RX_VK_RT_ALPHA=1) the game's texture sampled at a candidate in a covered cell none on with RX_VK_RT_ALPHA leaves and fences cut as the game draws them AMD; untested elsewhere on
RX_VK_RT_BLOCKER_NEAR distance within which a receiver's sun ray passes kBlocker none 50 (with RX_VK_RT_ALPHA) trees' shadows show their leaves see #727's comment 50
RX_VK_RT_HIT the hit records and their debug pictures none off texture colours at ray hits for developers so far off
Look settings (nine rows, F4 to F6) strength, reach and warmth of our lights; #727's sun softness and smoothing; AO, bounce and highlight strength none lantern light x0.328, window light x2.44, the rest neutral the look chosen by eye on one PC as they are
"Ray tracing: show" (F8), "Ray tracing: view" (F7) the game's own picture; one part alone none on; off comparing and debugging - as they are

Testing

Tested: Windows 11, Radeon RX 9070 XT (no VK_EXT_opacity_micromap): headless runs through the control bridge from saves in Kokiri Forest, the Market, Kakariko and Hyrule Field, by day and night, with every part on and each on its own, no device loss or Vulkan error in the logs (the validation layers were not on); and several hours of play by the branch's owner in the same areas. The transform feedback capture, on by default again at #727's 19f973b0, ran in two real sessions in the Market by day on this card without a device loss (it lost the device there before #727's 9a818a6a). Game-free checks: python -I -B tests/run_all.py --jobs 8 rt_ emit program_cache menu gain look readme audio linux_pressure: 86 pass, 1 fails (test_menu_save_atomic, which fails on #727 alone). The full suite fails 17 or 18 checks on this PC that fail the same on #727 alone (among them test_env_on, test_release, test_walk_key, test_vk_occlusion_queries, test_menu_save_atomic, test_cpp_preflight, test_linux_preflight, test_options_budget_once).

Not tested: any device with opacity micromaps (NVIDIA): there our alpha path is off, but the lights, the guide buffers, the deferred pass and the hooks in #727's files run and never have on such a card. Intel Arc. Linux (not even built). Frame generation with the rows on. Areas other than the four above for the lights.

Must be tested:

  • NVIDIA RTX with micromaps, Windows: RX_VK_RT=63 in the Market by night, expecting lanterns and windows to light their surroundings with shadows and no error in the log (by hand: the Market's lanterns by night and the log; not asked yet).
  • Linux, any ray tracing GPU: build it and make the same run, expecting the same picture and no error in the log (by hand: the log and the Market's lanterns by night; not asked yet).

Risks

What could break: with the guide buffers on, every lit program's module changes: a driver that rejects a patched module would leave those draws out (accepted on the RX 9070 XT). The hooks in #727's scene and mask code run on every device once ray tracing is on.

Turning it off: every part has its row or switch and is off by default; RX_VK_RT_GUIDES=0 returns the lit programs to #727's own.

Compatibility: longshot_options.ini gains the look settings' keys and two rows; a ray-traced_lantern_lights=1 saved by an earlier state of this branch now reads Low. The first start with the guide buffers on makes the lit pipelines again (about a minute with parts of the picture missing). MKWVK_API_VERSION is unchanged (vk_api.h untouched).

Checklist

Everyone

  • One topic. (Not yet: this is the whole line of work on top of #727; to be cut into reviewable parts once #727 has landed, or as its author prefers.)
  • The title is a Conventional Commit (type(scope): description) of the status line's type.
  • Why gives the reason plainly and links the issues that fit (the tracker searched).
  • Tested on my own PC where it runs (in the game, for a change the game runs), as Testing's Tested says; what
    can't be run by hand is in Testing's Not testable by hand, with why.
  • Measurements has a verdict, or one line saying why there is nothing to measure. (Pending: single runs so far.)
  • Nothing gets worse that I know of: any cost (speed, latency, memory, a setup that worked before) is measured and
    in Risks. Not ticked yet: Measurements verdict is still pending, so the lantern lights' frame cost is not stated.
  • Testing names what was tested, what wasn't, and what must still be tested, where and how.
  • Rebased on current main. (On #727's branch, which it follows.)
  • python -I -B tests/run_all.py passes (any failure that also fails on main is named). (The failures named above fail on #727 alone; not yet compared with main.)
  • No game files, dumps, build output or generated files.
  • third_party/ untouched (a new folder with a PROVENANCE.md instead).
  • The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled.

When it applies

  • AI assistance recorded with Assisted-by: / Co-Authored-By: trailers.
  • Numbers from the same PC, scene and settings, at least 2 interleaved runs each, the median reported. (Pending.)
  • Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value.
  • Screenshots of the same spot, captioned like the Measurements columns, for a change that shows on screen. (To follow.)
  • A file in docs/tested/ for each new measured run (format in docs/tested-configurations.md). (With the measurements.)
  • The SPIR-V headers regenerated with glslang (a shader changed). (Ours, by our own scripts; none of #727's is written.)
  • A check under tests/ that reads changed source updated in this PR, not weakened.
  • Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. (Windows only so far.)
  • Docs updated.

🤖 Generated with Claude Code

**Type:** feat · **Risk:** medium · **Tested on:** Windows 11, Radeon RX 9070 XT · **Needs:** an NVIDIA RTX card (the path with micromaps), Intel Arc, Linux **On top of #727.** This branch is rebased onto #727's as it moves (now 19f973b0), so until #727 merges the diff here shows its commits too. Ours are the last 70, nearly all in files of our own; in #727's files we add marked hook lines and `#ifdef` blocks. #727 has since taken its own versions of three things that started here (cut-outs tested in the ray loop, the mesh-shader cards' bits, the bottom levels' budget from the video memory): those are its commits now, and ours build on them. What we found on the way that concerns #727 itself is in https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/727#issuecomment-36272. ## Why With #727 the sun, the sky and the game's few lamps are ray traced. But in a town at night nearly everything that glows, every lantern and every lit window, is a glowing material with no lamp behind it: it lights nothing and casts no shadow, and the warm light round it is baked ambient. And on a card without opacity micromaps (every AMD card today) leaves and fences were solid in the rays, so a tree's shadow was a blob, and Kakariko lay under a sheet of shadow at night. This is also the groundwork for a path-traced mode: lights that exist as lights, the game's own colour at a ray's hit, and the guide buffers a denoiser or Ray Reconstruction needs. ## What changed Lanterns, lantern glass and windows become real lights with ray-traced shadows, highlights and normal-map detail; rays respect alpha where the device has no micromaps; a ray's hit knows the game's texture colour. All of it is off unless its row or switch is on. - **Lights from what glows** (`vk_rt_emit.cpp`, `vk_rt_emitters.cpp`, `rt_emitters_policy.h`, `rt_emit_islands.h`): a program's emission read from its SPIR-V; sphere and area lights from lantern bulbs, lantern glass and window panes, a batched draw split into its islands; kept in a world light grid (`rt_light_grid.h`), so which lights reach a surface depends on the surface's place, never the camera's. - **Those lights in the picture** (`RX_VK_RT` bit 32, row "Ray-traced lantern lights": Off / Low / Medium / High / Ultra; `vk_rt_di.cpp`, `shaders/rt_di_def.comp`): a pass after the lit draws with the diffuse term and a GGX highlight. It traces a shadow ray only for the lights that matter at a pixel (a light under 5 or 10 % of the pixel's unshadowed lantern light is not traced and takes the traced ones' mean visibility), skips pixels where lantern light is under half a percent of their own colour (by day nearly all), and works at half size in the two lower steps. - **Guide buffers** (`rt_guide_spirv.h`, `vk_rt_guides.cpp`): the lit programs store the shading normal (normal map included), roughness, albedo and F0, by a SPIR-V patch like #727's own; every guide in 77.8 % of the cache's lit stages. - **The game's lamp list and ray-traced lamp shadows** (`RX_VK_RT` bit 16; `vk_rt_lights.cpp`, `vk_rt_lamps.cpp`, `rt_lamp_spirv.h`): the lamp list's layout is from #815. - **Rays without micromaps** (`RX_VK_RT_ALPHA=1`, whose baked opacity bits in the candidate loop are #727's now; ours on top in `vk_rt_alphax.cpp`, `vk_rt_holes.cpp`): the game's texture sampled at the hit for a covered cell, terrain patches open at the game's holes, and the `kBlocker` class (the game's low-detail shadow models) left out of a sun ray whose receiver is within 50 m of the camera, by the ray's instance mask (#727's falling leaves keep casting). - **Colours at hits** (`RX_VK_RT_HIT=1`; `vk_rt_hitrec.cpp`, `vk_rt_recipe.cpp`, `shaders/rt_recipe_eval.glsl`): a lit program's base colour as a recipe folded per draw, with records for the ground and the mesh-shader cards; so far used by debug pictures only. - **Looking and tuning** (`rt_views.h`, `rt_look.h`, `vk_rt_show.cpp`, `vk_menu.cpp`): F8 flips between the game's own picture and the traced one, F7 shows one part or one guide buffer alone, F4 to F6 step through and change nine look settings (a collapsible group in the menu, saved with the options). - **Diagnostics** (`vk_rt_scene_big.cpp`, `vk_rt_scene_who.cpp`, the emission census): the biggest instances, a leave list, and sun probes that name what a pixel's sun ray meets. - **One change of #727's behaviour left**: the traced sun shadow also in the cascades' channel (distant characters lost their shadows). The reason is in the comment linked above; the other two named there are #727's own now. Everything is described in `docs/ray-tracing.md`. ## Measurements **Verdict:** pending. The numbers below are single headless runs without a frame rate cap (1707x960 internal, FSR 4.1.2, AO Medium, reflections at the Low roughness step), made while building with the desktop in use: the same scene ran up to 1.5 times faster or slower between hours, so only numbers within one line compare. Interleaved medians follow before this leaves WIP. Baseline: #727 at f70c348d, not main: this branch sits on it. Hardware: Windows 11, Radeon RX 9070 XT 16 GB (driver 26.11.1), FSR 4.1.2 Quality to 1440p. Scene: the Market at a shop door and at a pine by night, Kakariko by night, Kokiri Forest; 1707x960 scaled to 2560x1440, no frame generation, no frame rate cap. Method: one headless run each through the control bridge, 30 to 120 s, the player standing still; brightness as the mean of a fixed crop of the "Sun shadows" view's picture, frame rate from the bridge's status, pass times from `RX_VK_GPU_PROFILE=1`, the hits' share from the log's `rt hit: primary rays` line. Not medians. How to reproduce: a save at each spot, `RX_VK_RT=63 RX_VK_RT_ALPHA=1`, and the part's own live switch for the before column (`exact=0 blockernear=0` and `holes=0` in `RX_VK_RT_ALPHA_CTL`, `di=0` in `RX_VK_RT_LAMPS_CTL`). | | Before, the part off: this PR @ f86523bf | After: this PR @ f86523bf | |---|---|---| | A pine's sun shadow near the camera, Market by night (mean brightness, the game's own shadow 84) | 63 (shadow models at every distance) | 80 to 88 | | Kakariko by night, the sun term's mean over the village (of 255) | 72 | 131 | | Primary-ray hits with the game's texture colour, Kokiri Forest (before: this branch @ 11739f5e, without the ground's and the cards' records) | 52 % | 99.9 % | | Lights in the Market at a shop door with four lanterns | the game's 2 spots | 2 spots and about 130 of ours | | Frame rate at that door by night, everything on | 74.6 fps with ray tracing off (GPU 10.0 ms a frame) | 33 to 38 fps (20 to 24 ms) with the lantern lights at full size and every light traced | | The lantern lights' steps at that door (one run): fps, the pass, shadow rays a lit pixel | off: 60 fps | Ultra 46 fps, 4.2 to 4.6 ms, 7.7 rays; High 51, 2.5 to 2.8 ms, 3.2; Medium 56, 0.9 to 1.0 ms, 3.2 at half size; Low 58, 0.6 to 0.7 ms, 1.8 | | The lantern lights' pass by day, the Market's square (Medium / High) | every lit pixel traced | 0.19 / 0.39 ms: 97 % of the lit pixels left out by the floor | | The Market's square by day, about 5,500 instances: fps, the render thread's work a frame | off: 68.9 fps, 8.6 ms; #727 alone: 30 to 35 fps, 17.5 ms | 28 to 32 fps, 21.8 ms (the top level 1.7 microseconds an instance a frame against #727's 1.3) | | The sun's and AO's rays, Market by night, with the kBlocker rule | 1.74 ms (shadow models at every distance) | 1.66 ms | ### Flags and settings New menu rows and switches; every one is documented in `docs/ray-tracing.md`, the rows also in the README's option table. | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | `RX_VK_RT` bit 16, row "Ray-traced lamp shadows" | shadows for the game's own lamps | none | off | a shadow ray a lamp in the lit programs | helps wherever the game has a lamp; few places | off until measured | | `RX_VK_RT` bit 32, row "Ray-traced lantern lights" (Off / Low / Medium / High / Ultra; `RX_VK_RT_DI_SIZE`, `RX_VK_RT_DI_CUT`, `RX_VK_RT_DI_FLOOR` go over the step) | the lights made from glowing materials, in the picture | none | off | diffuse light and highlights with shadows; the steps trade shadow rays and size for time | towns at night; by day the floor leaves it nearly free | off until measured; Medium where it is on | | `RX_VK_RT_GUIDES` | the guide buffers | none | on only while a consumer needs them | every lit pipeline is made again once | needed by bit 32's deferred way | as it is | | `RX_VK_RT_ALPHA_EXACT` (with #727's `RX_VK_RT_ALPHA=1`) | the game's texture sampled at a candidate in a covered cell | none | on with `RX_VK_RT_ALPHA` | leaves and fences cut as the game draws them | AMD; untested elsewhere | on | | `RX_VK_RT_BLOCKER_NEAR` | distance within which a receiver's sun ray passes `kBlocker` | none | 50 (with `RX_VK_RT_ALPHA`) | trees' shadows show their leaves | see #727's comment | 50 | | `RX_VK_RT_HIT` | the hit records and their debug pictures | none | off | texture colours at ray hits | for developers so far | off | | Look settings (nine rows, F4 to F6) | strength, reach and warmth of our lights; #727's sun softness and smoothing; AO, bounce and highlight strength | none | lantern light x0.328, window light x2.44, the rest neutral | the look | chosen by eye on one PC | as they are | | "Ray tracing: show" (F8), "Ray tracing: view" (F7) | the game's own picture; one part alone | none | on; off | comparing and debugging | - | as they are | ## Testing **Tested:** Windows 11, Radeon RX 9070 XT (no `VK_EXT_opacity_micromap`): headless runs through the control bridge from saves in Kokiri Forest, the Market, Kakariko and Hyrule Field, by day and night, with every part on and each on its own, no device loss or Vulkan error in the logs (the validation layers were not on); and several hours of play by the branch's owner in the same areas. The transform feedback capture, on by default again at #727's 19f973b0, ran in two real sessions in the Market by day on this card without a device loss (it lost the device there before #727's 9a818a6a). Game-free checks: `python -I -B tests/run_all.py --jobs 8 rt_ emit program_cache menu gain look readme audio linux_pressure`: 86 pass, 1 fails (`test_menu_save_atomic`, which fails on #727 alone). The full suite fails 17 or 18 checks on this PC that fail the same on #727 alone (among them `test_env_on`, `test_release`, `test_walk_key`, `test_vk_occlusion_queries`, `test_menu_save_atomic`, `test_cpp_preflight`, `test_linux_preflight`, `test_options_budget_once`). **Not tested:** any device with opacity micromaps (NVIDIA): there our alpha path is off, but the lights, the guide buffers, the deferred pass and the hooks in #727's files run and never have on such a card. Intel Arc. Linux (not even built). Frame generation with the rows on. Areas other than the four above for the lights. **Must be tested:** - NVIDIA RTX with micromaps, Windows: `RX_VK_RT=63` in the Market by night, expecting lanterns and windows to light their surroundings with shadows and no error in the log (by hand: the Market's lanterns by night and the log; not asked yet). - Linux, any ray tracing GPU: build it and make the same run, expecting the same picture and no error in the log (by hand: the log and the Market's lanterns by night; not asked yet). ## Risks **What could break:** with the guide buffers on, every lit program's module changes: a driver that rejects a patched module would leave those draws out (accepted on the RX 9070 XT). The hooks in #727's scene and mask code run on every device once ray tracing is on. **Turning it off:** every part has its row or switch and is off by default; `RX_VK_RT_GUIDES=0` returns the lit programs to #727's own. **Compatibility:** `longshot_options.ini` gains the look settings' keys and two rows; a `ray-traced_lantern_lights=1` saved by an earlier state of this branch now reads Low. The first start with the guide buffers on makes the lit pipelines again (about a minute with parts of the picture missing). `MKWVK_API_VERSION` is unchanged (`vk_api.h` untouched). ## Checklist ### Everyone - [ ] One topic. (Not yet: this is the whole line of work on top of #727; to be cut into reviewable parts once #727 has landed, or as its author prefers.) - [x] The title is a Conventional Commit (`type(scope): description`) of the status line's type. - [x] Why gives the reason plainly and links the issues that fit (the tracker searched). - [x] Tested on my own PC where it runs (in the game, for a change the game runs), as Testing's Tested says; what can't be run by hand is in Testing's Not testable by hand, with why. - [ ] Measurements has a verdict, or one line saying why there is nothing to measure. (Pending: single runs so far.) - [ ] Nothing gets worse that I know of: any cost (speed, latency, memory, a setup that worked before) is measured and in Risks. Not ticked yet: Measurements verdict is still pending, so the lantern lights' frame cost is not stated. - [x] Testing names what was tested, what wasn't, and what must still be tested, where and how. - [ ] Rebased on current `main`. (On #727's branch, which it follows.) - [ ] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). (The failures named above fail on #727 alone; not yet compared with main.) - [x] No game files, dumps, build output or generated files. - [x] `third_party/` untouched (a new folder with a `PROVENANCE.md` instead). - [x] The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled. ### When it applies - [x] AI assistance recorded with `Assisted-by:` / `Co-Authored-By:` trailers. - [ ] Numbers from the same PC, scene and settings, at least 2 interleaved runs each, the median reported. (Pending.) - [x] Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value. - [ ] Screenshots of the same spot, captioned like the Measurements columns, for a change that shows on screen. (To follow.) - [ ] A file in `docs/tested/` for each new measured run (format in `docs/tested-configurations.md`). (With the measurements.) - [x] The SPIR-V headers regenerated with glslang (a shader changed). (Ours, by our own scripts; none of #727's is written.) - [x] A check under `tests/` that reads changed source updated in this PR, not weakened. - [ ] Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. (Windows only so far.) - [x] Docs updated. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Ported from the work on v3.0.0-rc.3 (rt-all 2ad17d6) onto main e090cc4.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Fable 5.2 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
The checks test_drawn_page_map and test_recorder_sync now know the RT passes.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
The mask part's ray query trace declared VK_EXT_opacity_micromap's capability on every device: a second build without it
(rt_ao_trace_rq_plain) where the scene cuts no cards. docs/ray-tracing.md describes the four parts, their requirements,
cost and switches, and the comments point to it; docs/development.md's switch table names RX_VK_RT.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
The rays alone miss casters the game's cascades and static map have: with native mesh shaders every plant (a mesh stage's output cannot be captured), 15 % of the Kokiri spawn's picture is game shadow the rays leave lit; with RX_VK_MESH_SHADERS=compute 5.8 %. The static map's channel now takes min(game, traced) under the sun gate, the cascades stay the game's in both modes. Same-frame 4K dumps, share of the picture, lost shadow / lost sun: native Kokiri 1.7 -> 0 % / 1.9 %; compute Kokiri 5.8 -> 0 % / 7.3 -> 7.7 %; gorge 1.1 -> 0 % (compute); Lake Hylia 0 % / 8.9 % (past the cascades' reach). RX_VK_RT_SUN_KEEP=0: as before. docs/ray-tracing.md describes it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
After each native task/mesh draw of the pre-pass or a sun cascade whose bottom level is due (RX_VK_RT_MESH_EVERY), draw() runs again for capture only with the program's compute fallback variant: its task and mesh stages write the records, nothing is drawn, and the cards are cut by micromaps as in compute mode. Kokiri Forest, native: leaves and grass in the structure, 23 mesh draws a frame, about a quarter captured each frame, none left out; no device loss or validation line. RX_VK_RT_NATIVE_MESH=0 turns it off. The first native run in an area compiles the fallback variants.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
GI's passes cost 0.94 ms at 4K on an RTX 5090 (were 1.4): one ray a half-size pixel and a 3 x 3 a-trous filter by default (RX_VK_RT_GI_RAYS, RX_VK_RT_GI_KERNEL=5 for the old taps), and the hit's own sun ray only where neither the screen nor the cache knows the hit. RX_VK_RT_GI_STABLE=1 logs how much the light changes a frame where the same surface is seen (about 6 % still, 10-12 % turning, below the game's own lit colour's 10-16 %); RX_VK_RT_GI_HOLD and RX_VK_RT_GI_FEEDBACK are the history's clamp and feedback, for testing. The head comment says what the energy rule is now (the scale held between 1 and 2.5, ADD 2).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
GI: Death Mountain Trail gets its own area row (its light-mask program is its own), and a place with no row takes the switches' values instead of the last area's. Scene: the status line counts the sun cascades' draws left out of the structure, by reason, and names their programs once.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Neighbouring pixels share their reflection rays through quad subgroup swaps (RX_VK_RT_REFL_SHARE, default 2): for the material-F0 class (armour, water) each pixel traces 2 rays and the 2 x 2 quad averages them, so rough plate armour is smooth and as steady frame to frame as the game's own (Kakariko's guard); a single-ray pixel takes the quad leader's answer when it is on the same surface. A device without quad operations in fragment shaders gets no reflections, logged. Without opacity micromaps the rays leave the cut classes out (mask 0x85 in place of 0x97), as GI does. The kept picture is half size, and nothing is captured while reflections are off. The Castle moat shows the scene (a ninth water surface). The SPIR-V linker check passes: 20 modules, 0 invalid.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The traced sun shadow takes the game's place in all three channels the sun goes through: the cascades', the static map's and the characters' (Link and the people are in the structure), so nothing is shadowed twice. The plants count as traced with the scene's native capture as in compute mode (foliage_traced()). Past 60 m the traced shadow hands over to the game's value, fully by 120 m (RX_VK_RT_SUN_FADE). The sun gate only catches a broken structure: the game's shadow comes back under 25 % of its sunlight kept (back over 40 %), or over 125 % (back under 115 %), and its log names its sums. Debug views sun_cmp and sun_cmp2 put the game's sun, the traced and the depth in one frame.

Native mode, one frame per view at 4K, share of the picture, lost shadow / shadow the game lacks: Kokiri spawn 4.3 % (15.0 % before the native foliage capture) / 4.9 %; Hyrule Field tunnel 0.1 / 1.0 %; gorge exit 0.9 / 1.7 %; Lost Woods 2.4 / 15.6 % (real canopy and blade-on-blade shadow); Lake Hylia 5.4 / 1.4 % (the game's blurred map past the traced edge). The gate fired in none. The menu help, README and docs no longer say leaf shadows need the compute mesh mode.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
A cascade draw whose vertex stage places its triangles by a rule the scene cannot read (the Lost Woods' falling leaves,
from particle storage buffers) is recorded again with its own vertex stage, the rasterizer off, and its clip positions
captured by VK_EXT_transform_feedback; rt_scene_mesh.comp turns them into world triangles (kCaster). RX_VK_RT_XFB=0 turns
it off. Also: a logged frame writes the SPIR-V of the cascades' left-out programs, the sun gate's log line names the sun's
direction, and the GI and reflection control files take clock=<hour> (menu_ask_cheat_action) for night tests.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Inside the Temple of Time the game's mask keeps the sun out wholly and the structure has no roof over the hall: the
traced shadow left 40-42 % of the picture lit and the floor burnt white, since the gate took no reading under 5 % sunlit.
Now the traced sunlight over a twentieth of the picture more than the game's reads as 150 % and the game's values stay.
A Kakariko house, Link's house and the Bombchu Bowling Alley are as with the rays off. Also test switches for the sun's
direction (RX_VK_RT_SUN_TILT, RX_VK_RT_SUN_TURN; RX_VK_RT_LIFT may be negative), and the docs' gate defaults corrected.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Indoors no sun cascade draws the walls and roof, so the Temple of Time's vault left the structure whenever the camera
looked level and the sun's rays reached the floor (40 % of the picture open to the sun, 0.2 % now). A static model the
pre-pass has drawn at one place for eight frames stays in the top level as a caster when it is not drawn; it is let go
when its memory is rewritten, its bottom level is freed, a loading screen passes or the camera jumps 30 m.
RX_VK_RT_REMEMBER=0 turns it off. Also: a transform feedback capture that could not run (its program not in the cache
yet, on the first visit) is counted among the cascades' left-out draws with the reason, and retried every 180 frames.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
program_cache_save hands each translated program's SPIR-V to rt::scene_program_translated, which keeps the vertex
stages of the programs transform feedback would capture (at most 512) and makes the capturing module at the program's
first capture. Programs loaded from the cache file still go through the background scan. Lost Woods with
RX_VK_NO_PROGRAM_CACHE=1: 4 of 4 capturing stages made from memory, no cascade draw left out.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
test(vk): program cache fixtures stub rt::on and rt::scene_program_translated, which program_cache_save now calls
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 3s
CI / Workflow lint (actionlint) (pull_request) Successful in 5s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 4s
Third-party parts / As their notes say (pull_request) Successful in 8s
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 4s
f8ddebbc6e
Co-Authored-By: Claude Opus 5.5 <[email protected]>
The start offset grows with the view depth; at 2 and 3 it was 3-12 cm at 10 m, more than the gaps between a fern's leaves, so plants past a few metres lost their own shadows. Kokiri spawn, one frame, lost / added shadow against the game 6-20 m: 4.0 / 2.9 % -> 1.1 / 4.4 %; 20-60 m: 5.3 / 8.3 -> 1.6 / 9.5 %. No acne on Kakariko's walls, steps and rocks or Kokiri's ground.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Screen-space hits (a hit's colour from the frame before's picture, and the depth march) are off unless RX_VK_RT_REFL_SCREEN=1: every hit is lit from the structure alone, so nothing that exists only on screen (Navi's glow, particles) shows in a reflection, and a hit no longer changes as it leaves the screen. The picture still sets the light level of a hit lit flat.

The Graphics tab gains Reflections: max roughness under the Ray tracing rows (Low, Medium, High, Max: ordinary surfaces 0.2 / 0.35 / 0.5 / 1, metal and glass 0.45 / 0.65 / 0.8 / 1), applied at once; Medium is the old default.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
test(vk): the Linux memory pressure fixture stubs the ray tracing hooks the program cache calls
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 4s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
3add916dfd
Co-Authored-By: Claude Opus 5.5 <[email protected]>
fix(vk): rt gi: a hit within 15 cm of its ray's start counts for nothing (RX_VK_RT_GI_SELF), so Link's hair is no longer lit orange in specks
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 5s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
a1a6cbcace
The rays of a clump (hair cards, a fern's fronds) end on the clump a few centimetres off and brought back its own sunlit colour; over a dimmer region that drove the hair's ambient scale towards its cap in specks, worst close to the camera. Such a hit now counts for neither light nor cover, fading in by twice the distance, so a clump keeps the game's ambient and a corner's bounce past 15 cm stays. Kokiri spawn: GI's overall lift +1.5 luma levels instead of +2.2.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
feat(vk): rt AO deepened in creases and corners (RX_VK_RT_AO_CONTACT 1.5), the depth march weighs 0.3, no foliage in the AO's rays; the sun gate opens again where the game and the rays agree on next to no sunlight
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 5s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
e9518463f5
The written AO takes o + 1.5 o^2 of the traced occlusion: a crease or the floor under a table read 0.49 traced where the game's SSAO has 0.30-0.38, while open walls and lightly covered ground already matched, and strength or radius darkened those too. With the march at 0.3 and the foliage out of the AO's rays (the grass came out twice as dark as the SSAO), a Kakariko house where the SSAO is under 0.5 / 0.5-0.8 / over 0.95 reads 0.27 / 0.56 / 0.98 (SSAO 0.34 / 0.68 / 0.99; before 0.49 / 0.70 / 0.98).

The sun gate opens again where the game and the rays agree on next to no sunlight (under 5 % sunlit in the game's picture, the traced within 5 % of it): a gate that closed on the way into the Temple of Time, before its vault was in the structure, no longer stays closed.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The game draws its 12288 x 12288 static shadow map (D16) once, while an area loads: some 2000 to 3600 depth-only
draws in a frame or two, with no scene yet, so the cascades' rule ("no scene this frame: a cascade of nothing we
trace") left them all out, and what the camera never shows and no cascade reaches was in no top level (the mound's
shade by Link's house, the cliff's across Kakariko's terraces: mask's lost shadow). They are now noted as the
cascades' draws are (models by their object block, the height-field patches) and kept in a set of the area's own,
placed every frame as kBlocker / kCaster like a cascade's draw, a caster once by its geometry and place. The set
is let go when the map is drawn again after a pause (another area). Their mesh draws (24 to 56 a batch) are not
captured. RX_VK_RT_STATIC_MAP=0: not taken. The status line says the batch: its draws, the casters kept.
Kakariko: 1966 draws, 1830 casters kept (109 terrain patches), none left out but 24 mesh draws. Kokiri: 3629
draws, 3560 kept. Kokiri spawn: agreement with the game's depth unchanged (89.4 %), 4561 instances a frame
(1197 without), 116 MB of bottom levels (43).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The map's 24 to 56 task/mesh draws a batch (trunks, rocks: solid, no leaf cards among them) were not taken. They
come once, in a loading frame where no top level is built and their count is not known to the CPU, so they
cannot use the frame's arena: after the fallback's stages ran for the capture (as a native mesh draw's do),
rt_scene_mesh.comp reserves the draw's room in a pool that lasts the area (192 MB, RX_VK_RT_STATIC_MESH_MB) and
writes its triangles there, by the map's own camera; rt_scene_omm.comp its opacity states, a card's. The place
and the triangles taken go to the draw's count slot; scene_tlas builds the bottom level once that is read back
and keeps its instance (0x80; cards 0x88) every frame. Let go with the area's other static casters when the map
is drawn again. RX_VK_RT_STATIC_MESH=0: not taken. The batch's status line counts them.
Kokiri: 56 asked, 56 captured, 56 built, 231665 triangles; Kakariko: 24, 24, 22 built (two empty), 46378.
Agreement with the game's depth unchanged at both.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
A skinned draw's object is found by the mean of its bones' positions, not by the order of the draws, so an object the game
culls no longer hands its bottom level to the next. An object drawn on 8 frames or more keeps its last pose in the top level
while the camera does not draw it; let go of when its place is in view within 40 m and the game has not drawn it for 3
frames, when another object of its geometry drawn this frame stands within 0.5 m, on a loading gap or a 30 m camera jump.
The same object drawn again by another pass (within 25 cm) is placed once. RX_VK_RT_REMEMBER_SKINNED=0: off.

The camera's static models are remembered also when a cascade placed the same model at that place first (the cascades draw
before the camera's pass, so many were never remembered).

A logged frame (RX_VK_RT_SCENE_LOG, debug file "log") lists every placed instance, the remembered models and the skinned
objects.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
rt::scene_materials has two blocks of 4096 records: record 4096 + slot is the material's emission (rgb linear, in the
albedo's scale; a 1 when known to glow), zero until written. The game has no emissive texture: its glow (read from the
translated fragment stages of c012b5595725b5f1, 9357fdc112e91bf3, 700c26a16fa2a79d) is a light inside the object added
last, E = c5[106] * M * G * C: C = c5[4j+32..34] (j = c5[78]); G = falloff * c5[75] / clamp(c5[72], .01, 1)^2, the falloff
the mean over the geometry's vertices of min(1, (c5[72] / d)^2), d to the glow's point c5[56..58], N.L a half; M the red
channel of material texture k = c5[79] (0-5 at c2+0x20 + 8k, 6 at 0x68; none where that is a screen buffer). The family:
constant buffer 5 indexed at run time (used size 65536). shaders/rt_scene_emission.comp writes the mask's mean times the
colour, again on a 10 % change (flicker), every 8 frames at most. Each glowing geometry has its own slot. RX_VK_RT_EMISSION=0
off, RX_VK_RT_EMISSION_GAIN scales. Debug view tlase.

A geometry at a place is placed once also within 2 cm (rotation to 1/256, 27 cells): a cascade's copy and the camera's no
longer both stand when their 1 mm rounding fell apart. RX_VK_RT_NEAR_DEDUPE=0: off.
Checked by the mask part with and without the 2 cm dedupe: one-frame lost shadow at the Kokiri spawn 1.8 / 1.8 %,
Kakariko gate 1.5 / 1.4 %; the characters' own shadow reproduced 96 / 94 % with it, 91 / 87 % without.
shaders/rt_scene_build.sh makes rt_scene_emission's header too. docs/ray-tracing.md: the emission block, the 2 cm
dedupe, their switches, the tlase view.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
feat(vk): rt reflections: a hit's own light from the scene's emission block, and hits right by the ray's start fade
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 5s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
6f19017d7c
A hit lit flat now adds its material's emission where the scene's second material block has one (RX_VK_RT_REFL_GLOW, 1), so the Kokiri door lanterns reflect in the stream the same on screen and off. At 4x the lanterns' flicker breaks into orange specks on the ripples, so 1 stays. A top level's hit within 0.1 m plus 0.004 m a metre of distance of the ray's start fades to the game's lookup (RX_VK_RT_REFL_NEAR, RX_VK_RT_REFL_NEAR_FAR): a grazing ray's own floor rims and seams, lit flat, would draw streaks.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
perf(vk): rt reflections: the material-F0 class widens only at High and Max, so cloth stops tracing at Medium
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 4s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
5821699f56
The class of programs with a material F0 is armour and glass but also cloth (banners, bunting, tunics), which traced up to roughness 0.65 with 2 rays for nothing visible. At Low and Medium its cutoff is now the others' (0.2, 0.35); High widens it to 0.65, Max to 1. Market gate, the GPU pass time a frame: off 2.99 ms, the old Medium 6.28, the new 4.78 (a second run 6.30 / 4.79); no local difference in the picture.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
feat(vk): rt sun: the traced shadow takes the game's place at every distance (RX_VK_RT_SUN_FADE 0)
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 4s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
500a01a912
The traced sun shadow handed back to the game's own value from 60 to 120 m of view depth. With the user's rule that it replaces the game's everywhere in view, it no longer does. Of the texels past 60 m, the share the rays shadow and the game lights: Lake Hylia 43 % (far cliffs under the fog: the final picture looks the same), Kokiri 13 %, Kakariko 6 %, the castle gate's field 5 %, Gerudo Valley 1 %; no stray caster, and the castle, hedges and canyon walls agree with the game. RX_VK_RT_SUN_FADE=60 brings the handover back.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The 2 cm dedupe keys the rotation to 1/256, so a card the wind turns (program f2999864d78ae1d3, a 6-index quad) stood twice:
as the static shadow map captured it while the area loaded and as drawn now, 0.002 to 0.024 apart. An instance not drawn
this frame now also checks the frame's placements of its geometry in the 27 cells round it, regardless of the key, and
is left out when every rotation term is within 0.05 (crossed cards of one geometry stay apart). The frame's own draws
come first. RX_VK_RT_NEAR_DEDUPE=0 turns both off.

A logged frame's "rt scene placed:" lines also give the geometry's hash, vertex and index buffers, base vertex and
rotation.
Kokiri spawn, one logged frame: duplicates within 2 cm of the same program and index count 47 -> 35 a frame; same
geometry 30 -> 0 (the rest are other geometries of equal index count: a model's parts, the lanterns' cards).
Agreement with the game's depth 89.1 % (89.2 to 89.6 % in the runs before: within the run-to-run spread).
docs/ray-tracing.md: the dedupe's paragraph.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Mask's run (PR 727 renderer, RX_VK_RT=15, Kokiri, teleport 3) lost the device in the Market's first frame, past the last
checkpoint (a draw), in the unmarked scene and ray-tracing work. Kokiri's static shadow map casters (3560) were still kept
there: their set goes only when the next static map is drawn, and the Market's had not come. Each frame a kept note whose
vertex or index stream was written since its bottom level was built was built again from the note's addresses, which now
held the Market's data: its words read as indices with Kokiri's count and vertex bound, past the vertices (undefined in an
acceleration structure build; a fault). The clean run's teleport to Kakariko had about 19 statics left by then.

A static shadow map's caster or a carried draw (not drawn this frame) now carries the memory generation and frame it was
noted in. When its streams were written since: noted before the camera's last scene ahead of a loading screen, it is let go
(a static one erased); noted since (the area's own, streaming in), its indices are read on the CPU first and it is let go when
one reaches past its vertices or they do not read, otherwise built again as before and not read again until written again.
The log names the first 8 and counts them a frame (the first 20 frames).

Not yet run: the diagnostic run (solo, GPU-assisted validation, mask's recipe) waits for the lead.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
fix(vk-rt): transform feedback capture of particles off by default (RX_VK_RT_XFB=1 turns it on) until the Market's device lost is understood
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 17s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
1173c39426
A normal run of scene-port (Kokiri, teleport to Kakariko, teleport to the Market) lost the device in the Market about 20
frames into play, in the frame of the run's first transform feedback capture: two sun-cascade particle draws
(1c8ada05a80b2ca1, 7773a9a770c712f4, 30 indices, 1 and 2 instances), their capturing vertex stages made from the SPIR-V in
memory, translated in that run; the checkpoints stop right before the first of them (runs\prscene-1116-020703). The same
route with RX_VK_RT_XFB=0 ran clean through both teleports and 75 s in the Market (runs\prscene-1116-021244). The capture's
writes and reads are bounded as far as the code shows; the patched vertex stage is the suspect. The extension is not asked
for either while the switch is off. The Lost Woods' falling leaves are out of the structure meanwhile.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The approach comes from PR 815 by JayDeGoodz; the code is our own. The game's SSAO (a generate and four blurs, compute, writing an R8 storage image half the scene's size before the combine: 171c34b219c9c1a5, de8569e5db7cab73, bf75a6300919b337 in Kokiri) is found by what it does, and its dispatches are left out (mask_ssao_stand_in) from the frame after the traced AO first went into its image. Before the combine draw (mask_before_draw) the AO alone runs its own trace / temporal / a-trous chain (parts[1]) and rt_ao_ssao.comp averages it down into that image, deepening deep occlusion (o + AO_CONTACT o^2) as rt_ao_apply.comp does in the mask, so the combine's upsample and blend take it as the game's. The sun part stays after the combine; AO_INTO_SSAO=0 brings back the write over the mask's r.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The approach comes from PR 815 by JayDeGoodz; the code is our own. The row's On becomes four steps (vk_menu.cpp tx_ao_quality; the INI key stays): Ultra is the look so far, AO_RAYS (2) at the scene's size; High halves the rays; Medium traces the early pass (the AO into the game's SSAO image) at half the scene's size each way, the image's own size; Low does both; Off leaves the game's own SSAO running. vk_rt_mask.cpp ao_quality_of reads opts.rt_ao every frame, so moving between the steps applies at once; Off and on stays a restart (rt::mode). RX_VK_RT_AO_QUALITY=<0-4> or AO_QUALITY in the tune file hold a step; with RX_VK_RT turning the AO on and the row at Off, Ultra. The AO shaders take the pass's size from size_frame and the depth texel under a pass texel from extra3.w (depth_texel; extra3.z stays the AO's contact term). README's option table and docs/ray-tracing.md (The AO in the game's SSAO image) say so.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The Ray-traced ambient occlusion row was Off / On, and its On (1) traced every pixel with all its rays: the Ultra step (4) now, where 1 is Low. With the key unchanged, everyone who had the AO on would have moved to Low without a word. menu_init now loads a file from before options_version 7 with its 1 as 4, and save() writes options_version 7, so the move happens once and a Low chosen later stays Low. Off stays Off.

tests/test_ao_steps_saved.py compiles menu_init's line and runs it for each version and step, then checks save()'s version and the row's names.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The scene builds bottom levels from the game's vertex and index buffers where they are, and a pool's mirror may be a
sparse buffer. Those were made with kUsage, without ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY, which GPU-assisted
validation reported on every such build. pool_usage() is kUsage plus that bit when the device traces with RX_VK_RT on
(rt::scene_buffer_usage), as the other pools and the dense mirrors already have; without RT nothing changes.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
For the Market's device lost on the first transform feedback capture: the patched vertex stages are the suspect, and they
exist only in a running game (translated in that run, or read from the cache file by the background scan). With
RX_VK_RT_XFB=2 both paths patch as before, write xfb-<id>-in.spv and xfb-<id>-out.spv into RX_VK_RT_XFB_DUMP and stop
there: no module, no pipeline, no capture draw (the draw is dropped as when no stage is found). For spirv-val offline.
xfb_mode() reads the switch once for the note, the extension and both patch paths.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The cache scan asked a stage it had written for the test again 180 frames on, as one it could not find, so the dump and its log lines came back every few seconds. A stage written for the test now waits as long as one translated in the run (frame + 100000).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
rt_xfb_capture runs right after the game's indexed draw, inside draw()'s OccGuard, and scene_xfb_end ends the render pass to turn the captured positions into triangles (a fill, a compute dispatch, barriers). The game's occlusion query begun for that draw stayed active across vkCmdEndRendering and that work, and ~OccGuard ended it outside the pass it began in (VUID-vkCmdEndRendering-None-06999, VUID-vkCmdEndQuery-None-07007). OccGuard::end() now ends it right after the game's draw, counting that draw alone; with RX_VK_DRAW_STATS's own query running, the capture is left out (scene_xfb_drop).

xfb_note also leaves out a program with a tessellation or geometry stage: the Xfb execution mode belongs to the last stage before the rasterizer, and only the vertex stage is patched.

The capture stays off by default (RX_VK_RT_XFB=0) until a run proves the Market's device lost gone.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
test(vk): the AO's write into the game's SSAO image in the drawn page map's writers, and the roughness row's override read as values
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 4s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
d16c17e048
The AO into the SSAO image (2f3f348) notes the image's page map with a reason of its own; it needs no ParLock since the parallel replay is off while ray tracing runs. The Reflections: max roughness row checked RX_VK_RT_REFL_ROUGH and RX_VK_RT_REFL_METAL_ROUGH by getenv alone, which test_env_on reads as set-means-on switches; they are now read as values.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The capture's vkCmdBindTransformFeedbackBuffersEXT, vkCmdBeginTransformFeedbackEXT and vkCmdEndTransformFeedbackEXT are called through pointers vk_rt_scene.cpp loads itself (RT_LOAD), not through vk_work.h. With RX_VK_RECORDER=thread (Threaded rendering: Auto) the pass's begin, the capture pipeline's bind and the draw were still packets in the recorder's ring, so these calls reached cmd first, outside the pass and with another pipeline bound, from the replay thread while the recorder thread used the same pool. A core-validation run (RX_VK_RT_XFB=1, Market, 11-16) showed VUID-vkCmdBeginTransformFeedbackEXT-None-04128, vkCmdBegin/EndTransformFeedbackEXT-renderpass, vkCmdBindPipeline-None-02323 and UNASSIGNED-Threading-MultipleThreads-Write before the device was lost. Each call now follows boundary(B_DIRECT), as the acceleration structure and micromap builds do; tests/test_recorder_sync.py checks them with as_build and mm_build.

The pending capture (xfb_note's, taken by scene_xfb_wanted, begun and ended around the draw's repeat) is now thread-local like xfb_wanted, so with RX_VK_PARALLEL's workers one worker's note is never begun by another's draw.

Capture stays off by default (RX_VK_RT_XFB=0) until a validation run shows it clean.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
A batch of the static shadow map's draws after a pause of 30 frames let the whole set go as another area's. The game also draws the map again in part without leaving the area: the Market's 1572 casters were let go for 3, then 3, then 33 (37 kept), Kakariko's 1830 for 289 (164 kept), so most of the area's static shadows left the scene a few seconds after it loaded. Such a batch is another area's now only past a loading screen (gap_from after the batch before, as the teleport fix reads it); otherwise its casters join the set (static_keys keep each caster once) and its mesh draws are not captured again (their keys count draws, not geometry: they would be in the pool twice). Past 25000 casters the set starts again as before. A new area's batch also lets the pooled mesh draws go when the casters were all let go before it (their streams written).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
fix(vk-rt): the static shadow map's batch line says what a part drawn again added, not the area's first batch's mesh counts
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 15s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
9f05136e46
On a batch merged into the area's set (drawn again in part) the "last batch" line showed the mesh counters of the area's first batch (asked, captured), which a merged batch never touches. It now says so: the batch's draws, its mesh draws (not captured again) and the casters it added, then the area's built mesh draws and casters kept.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The Market's casters, mostly let go by the stale-stream guard after the walk out through the gate, left some 40-60 behind in the next scene (the drawbridge), which draws no static shadow map: the Market's geometry where that area stands. Once a static noted before the gap was let go by its streams' writes (another area loaded) and no batch starts within 30 frames, the rest go too (statics_orphaned, let_statics_go shared with the batch's own let-go). A pause writes nothing and keeps the set; a batch during or after the loading screen is past it. The stale-stream guard itself is unchanged (it only counts). tests/test_rt_static_orphan.py checks the wiring and the decision.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
docs(vk-rt): a scene with no static shadow map of its own keeps none of the area before's casters
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 5s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
07a98b9a5e
Co-Authored-By: Claude Opus 5.5 <[email protected]>
fix(vk-rt): reflections share a ray in a quad only when the vectors are within two pixels' angle
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 11s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
f7177fd0d2
The quad's pixels took the first pixel's answer whenever their vectors were within 18 degrees. Rippled shallow water turns its vectors by a few degrees from one pixel to the next, so whole quads showed one answer: a mosaic of 2 x 2 tiles of flat-lit hits and kept-picture colours along the Kokiri stream's edge. A pixel now takes the answer only when its vector is within two pixels' angle of the first pixel's (from the view rays' derivatives), or within half the lobe a rough surface blurs over. share=3 keeps the wide test for comparison.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
fix(vk): rt gi: no bright specks on Link's hair where it keeps no history (a dark room by the fairy's light)
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 4s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
e56b6d8291
In Dodongo's Cavern, lit by the fairy, Link's hair still had gold specks with GI on, a new set each frame; with GI off it had none. The hair's rays mostly end on its own clump and count for nothing (RX_VK_RT_GI_SELF), so a hair texel is dark unless its one ray escapes to the room and brings back full light. The hair's cards fail the history's depth and normal tests every frame, so nothing averages that out, and the upsample, finding none of the four half-size texels on the pixel's surface, normalised their tiny weights and took one at random: the hair's dark or the face's or the wall's light.

- rt_gi_temporal.comp: a pixel with under 3 frames of history takes the mean of this frame's rays round it on the same surface (5 x 5 texels two apart, its own among them), so a speck is spread over its neighbours and light they share stays. A surface with history gathers its rays as before.
- rt_gi_upsample.comp: each texel's weight gets a floor of 0.02 besides its plane's nearness, so a pixel none of them fits blends them; at a character's edge against the far background the background weighs 2 % of the pixel's own surface.

Same spot and camera, five GI off / on pairs each: specks on the fringe (pixels 35 over their 7 x 7 median) on minus off +100 before (run-main's renderer), -10 after. Kokiri spawn and Kakariko's entrance look the same as before. A run under GPU-assisted validation is clean.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
fix(vk-rt): a reflection's flat-lit hit is no brighter than 1.5 times the kept picture around it
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 5s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
55fede0367
A top level's hit off the kept picture is lit flat by the whole picture's mean light. Under the Kokiri canopy that mean is the bright haze and light shafts, so sun-facing pebbles at the shallow stream edge, a few centimetres from the water, came out as white chips and silvery sheets beside the dim pebbles the picture shows. The hit is now bounded by 1.5 times the kept picture's brightness around its place (a coarse level), RX_VK_RT_REFL_BOUND or bound= in the control file (0: no bound). Sunlit places, where the picture around a hit is bright, are not changed.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
fix(vk-rt): reflections' Medium step keeps armour and glass tracing up to roughness 0.65, so the guards' plates reflect by default
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 7s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
02fbf76c6c
The max roughness row's Medium step (the default) had dropped the material-F0 class (armour, glass, water, cloth) from 0.65 to 0.35 to stop cloth tracing for nothing, but the guards' plates take the ground only at 0.65 (hardly at 0.5, not at 0.35), so at the default their reflections were gone. Medium is 0.65 for the class again; it costs about 1.5 ms a frame at the Market's gate, where the bunting is. Low still drops it to 0.2.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
fix(vk-rt): a reflection's flat-lit hit keeps its own glow past the bound, so the Know-It-All brothers' lanterns show in the stream again
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 4s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
bb9279d32a
55fede0 bounded a flat-lit hit at 1.5 times the kept picture around it, but it bounded the hit's emission with its lit part, so a lantern reflected over dark water was cut to the water's brightness and disappeared. The bound now applies to the light the hit takes (albedo times ambient and sun); the emission is added after it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
A reflection's or GI's hit off the kept picture is lit with the material record, the mean of the lit draw's albedo texture. A rupee's gem texture is pale; its colour is the material block's first colour, c5[32..34] (program a5ab9e9efb5f0553: its Eden IR takes the albedo as saturate(texture x c5[32..34]); the blue one's 0.014 0.05 1, the green one's 0 0.29 0). Its record was the texture's grey-white, which the user saw in the Kokiri stream.

The record is now the mean times that tint for the programs known to take their albedo that way (material_tint; RX_VK_RT_TINT_PROGS, the rupees' by default; RX_VK_RT_TINT=0 for none). It is not taken from every program: the same words are added in ab82811383b384b5, read as integers in others, and hold 0 0 0 or pure 1 0 0 in many, so a blanket tint would recolour them. The green and the blue rupee share one model and texture, so a tinted record is kept by geometry and object block (tinted_material, object_material) and scene_tlas places an instance with it ahead of the geometry's own; a slot is a texture and tint. rt_scene_mean.comp takes the tint as a push constant (the layout's range 32 bytes). No device-address reads added.

RX_VK_RT_MAT_LOG=<lines> (a test): each small lit geometry's program, textures, attributes and material block, once.

Checked at the Kokiri stream (RX_VK_RT_DEBUG=tlasm, the records as hits show them): the rupee grey-white with RX_VK_RT_TINT=0, green with the fix; the Market's material view the same off and on but for what moves (1.3 % of pixels). tests/test_rt_material_tint.py checks the wiring.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
docs(vk-rt): the rupees' tint in their material records (RX_VK_RT_TINT, RX_VK_RT_TINT_PROGS)
All checks were successful
PR description / Description follows the template (pull_request_target) Successful in 5s
68f4e54fc4
Co-Authored-By: Claude Opus 5.5 <[email protected]>
With screen-space hits off (the default) every top level's hit was lit flat: the mean albedo times the picture's light level, plus the emission record. A rupee's tinted record (0 0.29 0 times the pale gem's mean) came out dark green beside the bright rupee above it: its program (a5ab9e9efb5f0553) shades it far past its albedo lit flat (lighting times the tint, plus a texture times 30, scaled by c5[106]). A lantern's glass took its emission record times the picture's level, a fraction of the lantern the game draws.

Now a top level's hit whose material lights itself takes the kept picture's colour where the hit is on it at the depth it has (rt_refl_screen, the same test the screen-space hits use), and is lit flat as before off it. Self-lit is told by the emissions' block (the materials' second 4096 records) by the same record: w 1 for a glow (written by rt_scene_emission.comp, as before), and now w 2 for a tinted record, which rt_scene_mean.comp marks 0 0 0 2 when its push constant's w is 2 (the dispatch passes 2 for a tinted job; its descriptor covers both blocks). RX_VK_RT_REFL_OWN=0, or own=0 in RX_VK_RT_REFL_CTL, keeps the old flat lighting; rf.ambient.w carries the switch.

Checked on run-reflpr (the user's options, scene 2560x1440, RX_VK_RT=15), live own=1/own=0: the hit-kind view (RX_VK_RT_DEBUG=reflh) shows kept-picture hits only with own=1 (the water at Link's feet reflecting him, whose program family has a glow record); the Market gate the same but for what moves; the white-chip spot at the Know-It-All stream calm with own on and off (bound 0 still shows the sheets). RX_VK_RT_DEBUG=tlase shows the Know-It-All lanterns in the structure, glowing. Not seen: a lantern's or the rupee's own reflection; the reachable cameras do not see them in water. tests/test_rt_material_tint.py checks the mark.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
docs(vk-rt): a self-lit hit's colour from the kept picture (RX_VK_RT_REFL_OWN)
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 6s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
bec545f6b5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
emission_note took any draw of the lantern family as a light. Link (and, per refl, the Know-It-All house's trunk) carry intensity, power, radius and colour all exactly 1, and got a grey 0.5 record that tlase shows white and that the self-lit reflection path took as self-lit. Such a block now writes none. RX_VK_RT_EMISSION_DEFAULTS=1 takes them as before.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
docs(vk-rt): no glow record for a program whose glow words are all defaults (RX_VK_RT_EMISSION_DEFAULTS)
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 5s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
f70c348d21
Co-Authored-By: Claude Opus 5.5 <[email protected]>
The game gives every lit draw a list of its local lights (lamps, torches,
the fairy) in the vertex stage's first storage block. It is read once a
frame at the first depth pre-pass draw that has it, decoded, and handed to
a pass by rt::lights(cmd) as a storage buffer of 64-byte records
(shaders/rt_lights.glsl). Nothing uses the list yet: this is the source for
local-light shadows, direct lighting and the lights of GI hits.

RX_VK_RT_LIGHTS=1 turns the capture on by itself, without the acceleration
structures; RX_VK_RT_LIGHTS_LOG=<n> logs every n-th frame's count and first
lamps. Off, the draw hook is one load.

The list's layout and its validity checks are JayDeGoodz's, from pull
request #815 (gpu/vk/rt_policy.h, note_lights in gpu/vk/vk_rt.cpp), taken
over without its lamp-shadow policy. Added here: a size bound on the block,
finiteness checks on the cone words, and a 64-lamp cap for the GPU list.

Tests: tests/test_rt_lights.py (the decode on invented bytes, the GLSL
record against the C++ struct, nothing read with the switch off, the hook
and the recorder's rules). Not yet run in the game.

Co-Authored-By: JayDeGoodz <[email protected]>
Co-Authored-By: Claude Fable 5.2 <[email protected]>
In the game the capture never read a block: it asked for a depth pre-pass
draw by "no stage stores colour" and "depth written", but the pre-pass's
programs store a colour the pipeline masks off, and the lit draws only test
the depth, so every draw was turned away. The list is given to both kinds
of draw, and the block's own shape says whether it is the list, so any draw
into the scene's colour and D32F targets is asked now. A block refused once
in a frame is not read again for the draws that share it, and up to 64
different blocks may be refused before the frame is given up.

In the game (Windows 11, RX 9070 XT, driver 26.11.1, Kokiri Forest at
Link's house, RX_VK_RT=15 RX_VK_RT_LIGHTS=1): the list is found (98368
bytes, 1024 records), one lamp in play, number 100 (the fairy), at
-46.32 119.43 15.77 while the game's own state has Link at
-46.09 118.44 15.39: the list is in the game's world coordinates.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
The four Ray tracing rows are read at the start, so comparing the traced
picture with the game's own took a restart. A fifth row, "Ray tracing:
show" (Off/On, applied at once, never saved: On at every start), and the
F8 key flip between the two while the game runs:

- AO and sun shadows: the pass leaves the game's light mask as the game
  wrote it. The top level is still built, so showing the rays again is at
  once; the history restarts and the sun gate takes the return as a cut.
- GI and reflections: the path their control files' `off` already takes
  (the lit programs sample the black texel; every lookup is the game's).

With no ray tracing row on, the row and the key do nothing. The state's
logic is in gpu/vk/rt_toggle.h; each change logs `vk: rt: shown on|off`.
F8 is taken out of the keys that can be bound to a game button.

Tests: tests/test_rt_toggle.py (the logic, and that each part asks it);
the menu's row and key lists updated. In the game (Windows 11, RX 9070 XT,
driver 26.11.1, Kokiri Forest, RX_VK_RT=15, the row set through the control
bridge): off is as close to a run with RX_VK_RT=0 (mean difference 7 to 9
of 255) as two pictures with it on are to each other (6 to 8), and on
against off differs by about 21. The key itself was not pressed in the game.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
The first layout was pull request #815's reading of the block. The lit
fragment programs themselves (their clustered light loop, the same in
every one of them) use the record differently:

- word 0 is the light's type (0 point, 1 spot, 2 sphere, 100 and up the
  fairy and volume lights; 5 and unknown types are skipped), not a number;
- word 19 is a spot's exponent, not a kind; words 11 and 15 its cone
  cosines (word 11 of a sphere: one over its radius);
- word 7 is one over the range, with the window clamp(1 - (d w7)^4)^2;
  words 12-14 a quadratic denominator; word 21 a near fade.

The decoder follows that, and no longer refuses records by word 19. The
record for shaders grows to 80 bytes and carries what lighting a point
needs; rt_lights.glsl gets rt_light_attenuation, rt_light_incident and
rt_light_radiance, with the same arithmetic in C++ for the test (the GLSL
is not compiled here: no pass includes it yet). The log names each lamp's
type and prints a spot's cone and a sphere's radius.

Tests: tests/test_rt_lights.py (the layout on invented records, the
attenuation against hand-computed numbers, the GLSL record against the C++
struct). In the game (Windows 11, RX 9070 XT, driver 26.11.1, RX_VK_RT=0
RX_VK_RT_LIGHTS=1): Kokiri Forest the fairy alone; the Market 8 lamps
(lanterns as spheres of radius 0.1, spots with cone 0.985 0.906 and
exponent 2); inside the Deku Tree a lantern, the fairy and the spot from
the opening above (range 88); Zora's Fountain a spot and the fairy.

Co-Authored-By: JayDeGoodz <[email protected]>
Co-Authored-By: Claude Fable 5.2 <[email protected]>
Before rays can read a hit's texture, it has to be known where each kind
of draw keeps its texture coordinate and which of its textures is the
colour. RX_VK_RT_CENSUS=<n> logs, once per program of the draws the scene
takes (static, skinned, terrain, mesh), the vertex attributes, the
fragment stage's textures, and what the scene's own rules pick as colour
and as alpha source, then totals by class. It reads only: no texture is
uploaded for it, and off it is one load.

What it found (Windows 11, RX 9070 XT, driver 26.11.1, Kokiri Forest and
Castle Town's market): attribute 8 is the texture coordinate in every
static and skinned program that has one (RG16, RG16F, RG16SN or RG32F),
attribute 14 a second set on some static ones; a rule that takes the first
two-component attribute would take the skinning weights in a quarter of
the skinned programs. The colour pick is an sRGB view at one descriptor in
every case and never a rendered texture. The alpha rule, run on programs
that are not cut-outs, lands on a handle table or a rendered buffer: it
must not be used for lit hits as it is. The device has position fetch, 32
bound sets and no limit on sampled images.

Tests: tests/test_rt_census.py (the formats, the coordinate rules, the
bounded log). Six runs in the game, none lost the device.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
RX_VK_RT_BLAS_MB defaulted to 768 on every card. In Castle Town's market
the scene wants about 1200 MB on a Radeon RX 9070 XT (15,000 bottom
levels), so thousands of them were let go and built again every few
seconds, and shadow casters came and went with the camera; with 3072 set
by hand the market held still.

The default is now 768 for a card with 8 GB or less (no room to spare
there: as before), and an eighth of the video memory above that, at most
4096: 1536 on 12 GB, 2048 on 16 GB. The switch, when set, wins as before.
The rule is in gpu/vk/rt_budget.h, and the scene logs the budget once.

Tests: tests/test_rt_budget.py (the rule's values, and that the scene
takes its default from it and still reads the switch). Not yet run in the
game with the default: the market was checked with RX_VK_RT_BLAS_MB=3072.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
The first half of ray-traced lamp shadows. The game's lit fragment programs
apply their local lights in one clustered loop (iteration 0 the sun, the
later ones a 96-byte record of the lamp list each), and never shadow them.
lamp_find recognises that loop in a fragment module and returns the site a
patch needs: the lamp path's blocks, the test that says an iteration is a
lamp, the record's word index, the colour phis where the sun's and the
lamps' paths join with their lamp operands, and the surface position. A
module whose shape it does not expect is refused with a reason, never
guessed at. Nothing is rewritten yet, and nothing calls it.

Offline, over the 46,410 fragment stages of one prepared program cache:
24,173 have the record fetch; 23,826 of them are recognised (98.6 %); 311
test another light type, 8 another skip test, 28 apply the light inside
the lamp path. None of the 22,237 stages without the fetch is recognised.

Tests: gpu/vk/tests/rt_lamp_spirv_test.cpp on invented modules (the shape,
eleven near misses, malformed input), run by tests/run_all.py.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
The game never shadows a lamp: its lit programs add each lamp's light in
one clustered loop with no shadow term, so a lantern lights through walls.
A fifth Ray tracing row, "Ray-traced lamp shadows" (off by default, a
restart row; RX_VK_RT bit 16), traces one ray from the surface to each
lamp the loop visits and scales that lamp's colour by what it finds.

- shaders/rt_lamp_visibility.frag: the ray query, linked into the lit
  fragment modules as the reflection lookup is (two builds, with and
  without the opacity micromap extension). The ray starts a little off the
  surface, growing with the distance from the camera and the ray's length,
  and stops 0.15 m short of the lamp (lanterns sit inside their housing);
  both are switches.
- rt_lamp_spirv.h: lamp_patch scales the lamp operand of the colour phis
  at the end of the lamp path, about 35 instructions in one block; the
  sun's path is untouched, and a skipped record traces nothing. Its linker
  is a copy of rt_refl_spirv.h's, about 150 lines, so that file is not
  changed.
- vk_rt_lamps.cpp: the descriptor set (the top level and a frame block),
  bound beside GI's and the reflections'; lamps stay as the game has them
  where the device binds too few sets. The live switch (F8) hides it.

Offline, over one prepared program cache: all 23,826 recognised stages
patch, alone and after GI's and the reflections' patches in the cache's
order; an independent checker finds nothing wrong in the 43,108 distinct
patched modules, and catches 120 of 120 deliberate breakages. 347
lamp-loop stages of another shape are left as the game has them.

Not run in the game or on a GPU: whether a driver takes the patched
modules, whether the lamps' and the surface's positions share the top
level's space, the ray's offsets and the cost are all open. The first
run's checklist is kept with the work's notes.

Tests: gpu/vk/tests/rt_lamp_spirv_test.cpp (the patch on an invented
module, refusals), the menu's and the toggle's checks.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
The frame's set went to the first full-size target a lit draw with the patch
drew into. In Kakariko Village three such draws go into another full-size
target before the scene's own, so the scene's hundreds of lit draws got the
"off" set and the lamps stayed the game's own, unshadowed: the status line
had 3 lit draws with the patch where the reflections counted 114 to 835.

The lit draws now vote for their target, and the one with the most is the
next frame's scene, as the reflections choose theirs (rt_lamps::SceneVotes,
checked in rt_lamp_spirv_test.cpp).

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Without VK_EXT_opacity_micromap (AMD's Windows driver on a Radeon RX 9070
XT) the scene could only take a cut-out as a whole triangle, so the
reflections' and GI's rays left the cut classes out and the sun's rays
met solid cards. With RX_VK_RT_ALPHA=1 (off by default) the opacity bits
the micromap bake computes are baked anyway, kept in an arena with a
record per instance, and looked up in the ray query's candidate loop from
the hit's barycentrics; cut-out instances are no longer forced opaque.

- rt_hit_math.h, vk_rt_hit.cpp: the lookup (a barycentric point to its
  micro-triangle, the inverse of the micromap's order), the bake (the
  scene's own rt_scene_cut.comp, run as it is), the arena and the table.
- shaders/rt_alpha.glsl and nine new variants in headers of their own,
  made by rt_alpha_build.sh. The four ray shaders get an #ifdef ALPHA
  block each and RT_PROCEED in place of their loops; every variant that
  existed before compiles to the same bytes as before, so the committed
  headers are untouched. A loop passes at most 24 candidates over and
  then confirms the rest, so it always ends.
- FULL is split into OMM and FETCH: a GPU with position fetch but no
  micromaps now gets face normals at hits.

Covered: static cut-outs. Not yet: mesh-shader cards (grass, ferns, leaf
cards), terrain holes, skinned cut-outs, and programs whose coordinate
the cut rule does not read; alpha is taken at the texture's level 0 with
the fixed threshold.

In the game (Windows 11, RX 9070 XT, driver 26.11.1; seven runs, none lost
the device): in Kokiri Forest the structure agrees with the game's depth
on 85.9 to 86.05 % of the screen with the cut classes in (83.9 % as whole
triangles, 86.7 % with them left out); at Zora's Fountain the share of
water pixels whose reflection ray finds nothing falls from 26.8 to 23.9 %
and from 21.9 to 18.3 %; the cut class alone shows stems and blades with
their shapes; the sun's shadows in Kokiri show no visible change. GPU time
at Zora's Fountain with all four parts: 16.4 to 18.1 ms a frame (one run
each).

Tests: tests/test_rt_hit.py (the lookup by exhaustion for levels 3 to 5).

Co-Authored-By: Claude Fable 5.2 <[email protected]>
The grass, ferns, flowers and leaf cards are most of the cut-out geometry
outdoors, and without opacity micromaps they were whole opaque quads in
the structure. With RX_VK_RT_ALPHA=1 their opacity bits are baked by the
scene's own rt_scene_omm.comp (the card build and the outline-only build)
into a range of the bits arena kept for each mesh draw, which lives as
long as its bottom level, not as long as the frame's capture arena. Mesh
instances with bits are no longer forced opaque and get a table record;
the candidate loop is the one the static cut-outs use.

In the game (Windows 11, RX 9070 XT, driver 26.11.1, Kokiri Forest; five
runs, none lost the device): the structure agrees with the game's depth
on 92.9 % of the screen (86.0 % with static cut-outs alone, 83.9 % with
whole triangles, 86.7 % with the cut classes left out), and the grass
blades and vine leaves show their shapes in the scene's debug picture.
GPU time with all four parts: 10.2 to 11.0 ms a frame (one run each). At
Zora's Fountain the share of water pixels whose reflection ray finds
nothing falls by about 3 points, as with static cut-outs alone. Whether
the sun's shadows of plants change visibly could not be told from two
runs' pictures.

Not covered: the static shadow map's pooled mesh draws (solid casters),
terrain holes, skinned cut-outs.

Tests: tests/test_rt_hit.py.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
The rays' hits were shaded with one mean colour a texture. This adds what
a hit needs to read the game's own texture, and a picture to check it by,
without changing AO, GI or the reflections yet:

- vk_rt_bindless.cpp: the game's textures that the scene's materials name
  as one array of sampled images for compute passes (partially bound,
  updated after bind, a white texel for an empty slot). A texture is only
  borrowed while it is resident, never uploaded for.
- vk_rt_hitrec.cpp, rt_hitrec_math.h: a 64-byte record an instance (by
  InstanceId): the index and vertex streams, the texture coordinate's
  stream (attribute 8, in its four formats), the colour texture's slot,
  taken from what the scene's material rule already picked. Static and
  skinned geometry; terrain and mesh cards are marked "no texture".
- shaders/rt_hit_debug.comp: RX_VK_RT_DEBUG=hitc shades each primary
  ray's hit with its texture at the hit's coordinate (level 0, no light),
  hitu shows the coordinate. Every read the shader makes through an
  address is bounded by the record's counts; a zero address, a count past
  the range or a coordinate that is not finite shows a marker colour.

In the game (Windows 11, RX 9070 XT, driver 26.11.1; seven runs, none
lost the device): Castle Town's market 96.9 % of hits textured (2.9 % mesh
cards, 1.9 % sky), Kokiri Forest 77.9 % (22 % mesh cards). Right: the
gate's wood, the paving, the banners' emblem, the guard's mail, Link's
tunic. Not yet: tiled materials are too coarse (no coordinate scale for
programs outside the cut family), layered materials lack their second
layer, plaster walls are pale (no vertex colour or tint), grass and
leaves have no coordinate yet.

Tests: tests/test_rt_hitrec.py (the coordinate's decode, the read bounds
over 3.3 M reads, the slot table, the record against the shader's).

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Tiled materials came out too coarse in the hits' texture picture: the
game's vertex stage puts attribute 8 through a 2x3 matrix (the first six
words of its fifth constant block) before the texture is read. A static
draw's record now carries that matrix, taken from the lit draw's vertex
stage when the words are a usable matrix; a skinned draw keeps the
identity, since in the character programs read that matrix belongs to a
second texture. The lit draw's values reach the record by the scene's
geometry hash, because the depth draw has no fragment stage.

The record grows to 96 bytes and also carries the lit program's key and a
vertex colour stream (attribute 12, RGBA8), which is shown by views of its
own (hitv, hitb) but not applied: of the 19 programs that load it, 12
multiply it into the colour and 7 use it as blend weights. Views: hitc
(with the matrix), hitc0 (without), hitp (by program), and
RX_VK_RT_HIT_PROBES=x,y;... logs what lies under up to eight pixels.

In the game (Windows 11, RX 9070 XT, driver 26.11.1; eight runs, none lost
the device): the curtain and the rug in Kokiri Forest have the game's
weave; the market's timber is brown with its vertex colour. Not recovered:
the houses' plaster colours (palette tints of the fifth constant block
through masks and a height blend, or from the lighting), second layers
(faces, eyes): those need the fragment module's arithmetic recognised.

Tests: tests/test_rt_hitrec.py (the 96-byte record against the shader's,
the vertex colour's bounds, the matrix rule).

Co-Authored-By: Claude Fable 5.2 <[email protected]>
rt_ao_trace.comp and rt_ao_common.glsl changed upstream; only the AO trace's ALPHA
variant differs. The GI, scene debug, reflection and hit debug variants come out
byte for byte as committed. Every non-ALPHA variant of #727's shaders still
compiles, and to the same SPIR-V as from the base branch's sources. #727's own
headers are not written.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
rt_refl_lookup.frag changed upstream (f7177fd0, e56b6d82): its four ALPHA variants
are made again with glslang 16.6.0 by rt_alpha_build.sh. The AO, GI and scene debug
ALPHA variants, the hit debug variants (rt_hit_build.sh) and the lamp shadow
variants (rt_lamp_build.sh) come out byte for byte as committed. #727's own headers
are not written.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
The fairy that follows the player (record type 100) is one of the game's lamps, so she cast ray-traced shadows of everything around
the player all the time, which swamped the lanterns' own. The visibility function only got a bool (type != 5) and could not tell her apart.

The function now takes the record's type (word 0, a u32) in rt_lamp_in_type instead: type 5 and an off frame give 1 as before; type 100
gives 1 without a ray unless lf.flags.w bit 0 is set; types above 100 (volume-shaped lights, not points) always give 1 without a ray.
lamp_patch stores the load of the record's word 0 into it, and refuses a module whose type word is not a load of the module's own u32
(Reason::kTypeWord), or is defined where it does not dominate the patch. RX_VK_RT_LAMPS_FAIRY=<0|1> (default 0) and the control word
fairy= set the flag. The two generated headers are regenerated with glslang 16.6.0; the test and docs are updated.

Offline proof on the program cache: 23,826 of 24,173 lamp-loop stages patched in all four orders, 0 refused; 43,108 patched modules
checked, 0 failures.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Her light reaches several metres and fills in what a lantern's shadow would
leave dark, so the lanterns' shadows are hard to judge beside her even when
she casts none of her own. With RX_VK_RT_LAMPS_FAIRY=2 (the control file's
fairy=2) the function answers 0 for her record: her light is off where the
patch is, and only there. 0 and 1 are as before.

The two generated headers are made again with glslang 16.6.0.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
No change in behaviour: the same conversions, spelled as static_cast, in
vk_rt_lamps.cpp only (ours; #727's files keep their style).

Co-Authored-By: Claude Fable 5.2 <[email protected]>
rt_refl_lookup.frag changed upstream again (55fede03: a flat-lit hit is no
brighter than 1.5 times the kept picture around it): its four ALPHA variants
are made again with glslang 16.6.0 by rt_alpha_build.sh. The other ALPHA
variants, the hit debug variants (rt_hit_build.sh) and the lamp shadow
variants (rt_lamp_build.sh) come out byte for byte as committed. #727's own
headers are not written.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
For a ray's hit to show the surface's true colour, the hit shader has to
know how the game's own program forms it: which textures, at which
coordinates, tinted, masked and blended by which of the draw's words.
rt_roles_spirv.h reads that from a lit fragment module (and its vertex
stage): it finds the three diffuse accumulators of the lighting loop, takes
the one loop-invariant factor that differs by channel, and lifts its
arithmetic as an exact tree of nodes (constants, the draw's constant words,
vertex attributes, varyings with the vertex stage's expression, texture
samples and their coordinates). The discard's condition and the normal map
are found beside it. What it does not know it refuses, with the reason;
nothing is approximated.

Nothing in the renderer uses it yet: it is the analysis the draw-time
evaluator and the textured hits are to be built on. Offline, over the
program cache: 19,002 of 23,977 lit fragment stages give a complete recipe;
the rest are light-only loops, per-pixel-only factors, programs with a mesh
stage and about 320 singletons. A checker that shares no code with it (its
own SPIR-V interpreter on invented inputs) agrees on all 2,247 channel
values of 450 programs.

rt_roles_spirv_test.cpp builds its modules itself (no game data) and is
run by tests/run_all.py.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
On a device with no opacity micromaps the lamp rays leave the cut classes
out, so that a leaf card does not shadow whole. The characters go with them:
their programs discard, so the scene has them as kCutout, and they cast no
lamp shadow (seen in Kakariko: static geometry casts, Link and the villagers
do not). RX_VK_RT_LAMPS_CUTS=1 (the control file's cuts=1) keeps the classes
in the mask: the characters cast, and a cut card shadows whole. A test, until
the lamp rays test the cut-outs' baked bits as the other rays do.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
The test switch's note said the characters are cut-outs and therefore cast
no lamp shadow without it. The scene's instance picture in the Market
(RX_VK_RT_DEBUG_FILE, tlasi with masks 4 and 2) shows otherwise: the
characters' bodies are kSkinned and cast either way; kCutout holds their
hair and straps, the lanterns' housings, banners and fences. The comment and
the docs say that now. No change in behaviour.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
#727's debug pictures were chosen once, by RX_VK_RT_DEBUG at the start, so
checking AO, the sun shadows, GI and the reflections apart took a restart
each. A row, "Ray tracing: view" (Off, AO, Sun shadows, GI, Reflections,
applied at once, never saved: Off at every start), and the F7 key step
through them while the game runs; each change logs `vk: rt: view now <name>`.

- The list, the names, the bits and the stepping rule are in
  gpu/vk/rt_views.h (no Vulkan). A part that is off is skipped.
- The parts read their picture where they read their control files, once a
  frame: the mask part's tune (ao, shadow), GI's and the reflections' `view=`.
  One hook line each, and one at the present. A view is live as the control
  files' `view=` already was; nothing is relinked or rebuilt.
- The reflections' pictures need the slower build of their lookup, chosen at
  the start: RX_VK_RT_VIEWS=1 links it without showing anything (not the
  default); without it the selector skips Reflections and says why once.
- RX_VK_RT_DEBUG=<ao|shadow|gi|refl> still shows at the start, and the row
  starts from it; other pictures are left alone until the row is used.
  With Ray tracing: show Off no view is shown.
- F7 is read as the menu's keys are and cannot be bound to a game button.

Tests: tests/test_rt_views.py with test_rt_views.cpp (the rules, and that
each part asks); the toggle's, the menu's keys and sections checks updated
for the new key and row. Not run in the game.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
The check compiles vk_menu.cpp from tx_output_res to tx_speed with stubs; tx_rt_view
(rt::view_info) is not in its stubs, so it goes after tx_speed.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
With RX_VK_RT_ALPHA=1 on a device with no opacity micromaps, the lamp rays now
take the cut classes (cut-out, foliage, cascade) and test the baked bits in the
ray query's candidate loop, as the reflections' lookup does (rt_alpha.glsl):
the characters, whose programs discard and which the scene has as cut-outs,
and the foliage cast a lamp shadow cut by their alpha, and a leaf card no
longer shadows whole. Without it nothing changes (the classes stay out of the
mask, RX_VK_RT_LAMPS_CUTS=1 still puts them back whole).

rt_lamp_visibility.frag gets an ALPHA build (a third header, made by
rt_lamp_build.sh; the FULL and basic headers are byte for byte as they were):
two storage buffers at bindings 2 and 3 of the function's set, RT_FLAGS and
RT_PROCEED; the first confirmed candidate still ends the ray. The linker
already links every global and moves the set and binding, so rt_lamp_spirv.h
only names the new count. vk_rt_lamps.cpp picks the module, makes the set
layout of four bindings, writes rt::hit's table and bits into the frame's set
(again when either or the top level changed), and a frame in which they are
not made yet traces nothing (the "off" set, null descriptors). The mask rule
is in rt_lamps_policy.h. The "on:" line says how the cut-outs are cut.

Offline, the ALPHA function linked into 23,826 of 24,173 lamp-loop stages in
all orders (alone, after gi, after the reflections' ALPHA lookup with and
without position fetch, and after both), as before; the independent checker
passed every distinct module.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
The mask part's RX_VK_RT_DEBUG=ao|shadow pictures are written into the game's
light mask, which the lit programs then light the scene with, so emissive
materials and characters show on top of them, and a developer wanted the
term alone. Two compute shaders write a picture over the scene's colour:

- rt_show_term.comp: the light mask's r (AO) or g * b * a (the sun's product),
  grey, white 1 open or lit, the sky white, times RX_VK_RT_DEBUG_GAIN.
- rt_show_lamps.comp: the game's lamp list on a white diffuse surface
  (rt_light_radiance), each lamp with one ray to it against the top level with
  the lamp shadows' own start, stop and mask; position and normal as
  rt_ao_trace.comp makes them. Three builds as the AO's rays have: plain, OMM
  (micromaps) and ALPHA (the cut-outs' bits in the ray's loop).

rt_show_build.sh makes the four headers (glslang 16.6.0). Not used by anything
yet.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
The row's AO and Sun shadows were #727's mask debug pictures, which are the
game's lit picture with a doctored light mask: characters and glowing
materials still showed, and what was in shadow did not read cleanly. They are
now pictures of our own, written over the scene's colour at the point of the
frame where the scene part's debug picture is (after the fog's composite of the
world), by gpu/vk/vk_rt_show.cpp:

- AO is the light mask's r, Sun shadows its g * b * a, after the mask part
  wrote the traced terms into it (what the lit programs are given), grey, the
  sky white; the mask part's debug stays off while they show.
- Lamps, after Sun shadows: the direct light of the game's lamp list on a white
  surface with each lamp's traced shadow, the lamp shadows' own rays and
  rules (vk_rt_lamps.cpp lamp_rules), pi times the sum so that 1.0 is a lamp at
  full attenuation straight on. Works with or without the lamp shadows' bit; the
  selector skips it, and says why once, when the lamp list is not read
  (RX_VK_RT_LIGHTS=1).
- White is 1.0 times RX_VK_RT_DEBUG_GAIN, as the scene part's debug picture.
- Nothing is recorded unless one of the three is shown and Ray tracing: show is
  on. RX_VK_RT_DEBUG=ao|shadow at the start still shows the mask part's own
  picture, until the row is moved.

Hooks in #727's vk_rt_mask.cpp: an include and two lines in mask_after_draw.
Tests: tests/test_rt_views.cpp and .py cover the new table, the mapping, the
lamps' skip and the pass's descriptors, push constants and hooks. Docs and
README updated. Not run in the game.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
The selector's own pictures (AO, Sun shadows, Lamps) are drawn only once
the row or F7 has moved, and RX_VK_RT_DEBUG=ao|shadow keeps showing the
mask part's old picture, so a run with no keyboard could not show them: a
headless test had no way to look at the new pass. RX_VK_RT_VIEW=<view>
(ao, sun or shadow, lamps, gi, refl) moves the row to that view once at the
start, as the key would.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
rt_roles_spirv.h reads a lit program's base colour as an exact tree; this
makes it something a hit evaluates, in the two steps roles-analysis.md
section 6 names, and records what the next stage reads. Off with RX_VK_RT_HIT
(nothing analysed, folded or made), not run in the game.

- Per program, once (vk_rt_recipe.cpp): roles_find on the fragment and vertex
  modules at the program's first lit draw, within 3 ms a frame; the modules
  come from the program cache's file where the stage says its code is, or from
  the copy kept when the program was translated in this run (one hook line in
  vk_progcache.cpp). A refused program keeps today's picture, counted by reason.
- Per draw (rt_recipe_fold.h, no Vulkan): the constant words the recipe names
  are read and hashed, the cache asked, and on a miss the tree is folded with
  them (constants, x*0, x*1, x-x, selects on known conditions without looking
  at the dead arm, lerp and clamp recognised) into at most 24 ops, 4 textures,
  4 vertex attributes. A subtree of per-pixel leaves alone becomes its place's
  neutral value and the result is flagged approximate; more than the limits, a
  gather or array sample, an instanced coordinate, an op without an op of the
  table: today's picture, with the reason. The cache, the 2048-entry table and
  the analysis are bounded; the log tells the CPU a frame costs.
- One text of the ops (shaders/rt_recipe_eval.glsl): the hit shader includes
  it and the C++ side compiles the same file through rt_recipe_shim.h, so the
  reference evaluator and the GPU cannot differ on what an op is.
- The record grows from 96 to 208 bytes (resid, state, up to four attribute
  streams, four texture slots, the discard's compare) and a table of
  304-byte residuals is bound at binding 7; rt_hitrec_math.h stays the one
  layout, with hit_recipe() as the shader's C++ twin. vkCmdUpdateBuffer takes
  65536 bytes at most and the old record count per update went past it: fixed.
- hitc runs the residual where the record has one, hita shows the state (green
  exact, yellow approximate, magenta fell back, red refused).

gpu/vk/tests/rt_recipe_test.cpp (in tests/run_all.py): invented trees and
words, the residual equals the whole tree (exact) or the neutral reference
(approximate), the shapes of the analysis and a fuzz of 6000 trees; the
record and a hit from invented memory. tests/test_rt_recipe.py checks the
layouts against the GLSL structs and the shader's bounds. The three tests
that compile program_cache_save with stubs get the recipe's.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
The per-program analysis, the per-draw fold and what it may and may not do, the
record's recipe part, the shader, the offline proof.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
With everything traced, #727 writes the traced sun shadow into the mask's a
(the static shadow map's channel) alone and sets the cascades' g and the
characters' b to one. Seen in the Market on an RX 9070 XT: a character about
30 m from the camera then casts nothing on the ground, while a planter
beside her does and nearer characters do. She is in the top level (the
scene's picture with mask 4 shows her, at the game's depth), the pass's
filter and history off change nothing, and with RX_VK_RT_CHANNELS=1353 her
shadow is there: the lit programs stop taking a past the static map's range,
where their far map has the static world only, and take g at every distance.

channels_default now gives g the traced shadow as well (3 where it was 7).
The price is the squared penumbra #727's note avoids, where both channels
are taken. This is a change in #727's own rule, marked as ours, and belongs
upstream.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
rt_refl_lookup.frag changed upstream again (02fbf76c: the Medium step keeps
armour and glass tracing; bb9279d3: a flat-lit hit keeps its own glow past
the bound): its four ALPHA variants are made again with glslang 16.6.0 by
rt_alpha_build.sh. The other ALPHA variants, the hit debug variants, the
lamp shadow variants and the view pass's come out byte for byte as
committed. #727's own headers are not written.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
The game lights its world with a short lamp list and baked ambient; lanterns, lit windows, signs and crystals are glowing materials with no light.
For ray traced direct light with shadows (and the path-traced mode) everything that emits has to be known. rt_emit_spirv.h finds E, the colour a lit
fragment program stores with every light's source at 0 (the lighting loop's accumulators, the light block (c6, or c15 in the mesh pipeline's programs, told by the
loop's cap on a cell's lamps), the storage blocks, the cube and volume lookups), as a tree of rt_roles_spirv.h's nodes (that lifter, not changed): a first
pass puts 0 where only the sources make a lane, the lifter reads the rest, a second drops the zeros and the translator's san(). Then what E is made of (words,
textures as mask or colour, vertex data, per-pixel terms), whether a word of the material block switches it off (the marker of an emission, against fog and
volumes), a point of the draw's it measures a distance from (the lanterns' c5[56..58]), the family. rt_emit_eval.h folds E with a draw's own words.
Refuses, with its reason, what the lifting does not know. The test makes its own modules (a mask and a constant, a gate by a select, a point two ways, a colour
table, an accumulator that starts at 1, fog kept apart, the sun's rim, hemisphere, probe and reflection as 0, unlit and filter loops, the refusals) and is in tests/run_all.py.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Off by default and free (one load in each of two hooks in vk_rt_scene.cpp). Every n-th frame, for each distinct draw into the scene's colour whose fragment program
emits (rt_emit_spirv.h's E, folded with the draw's own constant words), one vk: rt emit: line of key=value words: program, family, colour (a texture taken as 1, and
said so), gate word, the draw's place and radius (the object block's matrix over the position stream), triangles, the program's point; for an unlit draw its blend state
and whether its colour exceeds 1. A summary line follows: programs by verdict, emitters, solid ones, by family. A program is read once from the program cache's file
(Stage::code_at), or as it is translated. It reads and logs only. tests/test_rt_emit.py: the pure part (rt_emit_policy.h: lines, the cap, the summary) on invented data,
the hooks, nothing without the switch, no Vulkan call. docs/ray-tracing.md: the switch and a section.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
The translator writes a float compare as OpFUnord* (true when either operand is NaN, the
compare's `bits` 3). apply() took bits 3 into the branch that compares the words'
integers with nothing to compare, so a known `ge`, `lt`, `gt`, `le` or `eq` of two
numbers answered the same for every pair (true for ge and gt, false for lt, ...). The
fold and the emission analysis evaluate known compares through apply(), so a gate made of
one (a word against a literal) decided its arm wrongly. Bits 3 now compares the floats as
bits 0 does, after the NaN rule; test_unordered_compares checks every compare on numbers
and NaN.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
The first run in Kakariko kept today's picture for most of what the walls and crates are
drawn with. The census of the program cache, with the words the game's own log has of each
program's block 5, says why: a residual of more than 24 ops (10 to 31 % of the Kakariko
lit programs, 14 to 26 % of the Market's, by the words of the other blocks), a compare of
floats (OpFUnord*) the evaluator had no op for (6 to 9 %), a sample with three
coordinates, a layer (1 to 3 %); and, by the game's log, a third of the records that kept
today's picture (31,855 of 92,857) were programs with no lighting loop, whose output
colour was never read at all. The 128 ops and 6 textures are the census's numbers (90 % of
the residuals at most 43 ops, 99.7 % at most 128 with every gate open; the Kakariko
programs need 68 at most, the Market's 126), the entry grows from 304 to 1200 bytes (54
entries in one vkCmdUpdateBuffer, 64,800 bytes), the evaluator no longer clears its
registers (it reads only what it wrote).

* ops: the unordered compares (OpFUnord*, true on NaN) and the ordered not-equal, trunc,
  roundEven, sin, cos, isnan, in the one list both sides share.
* array layers: a sample with a third coordinate whose layer is a word of the draw (a
  literal in the fold, kept with the sample, in the cache's key, a float a sample in the
  entry; the shader samples vec3(uv, layer)); a layer per vertex or per pixel is refused
  (kFbLayer). The bindless table already borrows 2D images as 2D_ARRAY views, and refuses
  a volume or a cube at the draw.
* unlit programs: rt_recipe_unlit.h reads the output colour of a program with no lighting
  loop through the emission analysis (unchanged) into the base colour's Roles, with the
  coordinates classified by rt_roles_spirv.h's coordinate_forms (the loop of roles_find
  made a function); the record has a bit for it (kRUnlit), hita shows it blue / violet.
* what an approximate residual is made of is kept (PixelKind bits) and told by the log,
  with the draw's words the recipe names, one line each for the first 120 folds, and the
  approximate records by kind every 600 frames.

The fold equals the whole tree on 678,000 values of the census (0 disagreements); the test
adds the ops, 127, 128 and 130 ops, six textures in a hit, layers, an unlit tree with and
without a fog.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
"The recipe at a hit" says what the second version does: the larger residual and its
numbers (from the census over the program cache and the game's own words), the compare
and float ops, array layers that are words of the draw, programs with no lighting loop
read as their output colour (blue and violet in hita), the kinds of per-pixel leaf the
log tells, the test's new cases.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
The game's lamp list holds only a few spot lights; the many lanterns are glowing
textures with no light attached. Their material does describe one (a point, a
radius, a power, an intensity and a colour table: the glow #727's emission uses).
Each lit draw of that program family, told exactly as emission_note tells it,
now makes a light: the glow's point through the draw's object matrix, a sphere
of the glow's radius times the object's scale, coloured pi * I * P * C / r^2 (the
glow is a radiance, a lamp record's colour an irradiance; the derivation is in
rt_emitters_policy.h). Its range, which the game does not give, is a documented
switchable choice. The list is deduped by place, kept between frames with the
flicker's current values, aged out, capped at 256 and logged every 600 frames.

rt::lights() gives them after the game's lamps as sphere records marked as ours
(RtLight.origin), 64 records in all, with 16 slots kept for them; the nearest to
the camera's reach are picked. The Lamps picture shows them with the game's
lamps, each with its shadow ray stopped short by the light's radius plus 0.1 m,
and RX_VK_RT_SHOW_LAMPS=<all|game|emitters> tells them apart. The game's lamp
shadows and #727's emission are untouched. Off with RX_VK_RT_EMITTERS=0.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
The first two headless runs put every light at round numbers (0 111 -20, 1 100 10)
with colour 3142: the hook read a lit draw's block ubo[0][1] as the object matrix,
which is only the object's for the draws the scene notes as static models; other
draws (the height field's patches, other families that pass the loose c5 test)
fill that binding with other numbers. And the mask was taken as 1, so materials
with generic c5 values and dark masks became white lights.

- Place: the glow is recorded by its geometry's hash (after emission_note, with its
  slot and the last emission scale); the light is made where the scene's top level
  places an instance of that geometry, from the matrix its rays see (a hook in
  scene_tlas' place lambda). Several instances of one geometry are several lights;
  a lantern the scene keeps out of view keeps its light.
- Mask: the record carries the material's slot and a per-channel factor, and the
  Lamps pass multiplies #727's emission record (mask mean times its scale) by it
  (rt_lights.glsl RT_LIGHTS_MATERIALS_BINDING, rt_light_colour); a dark mask gives
  no light. The Lamps shader's cut-out buffers move to bindings 5 and 6.
- Radius: R = max(r * s, 5 cm, sqrt(J / colour_max)) keeps the far field J / d^2
  and bounds the surface colour (RX_VK_RT_EMITTER_MAX, 100): no point of 3142.
- Ageing: lights followed the family's sporadic lit draws and were dropped after
  300 frames; they now follow the scene's placing, and a glow is kept 3600 frames.
- Logging: left-out family draws counted by the scene's reason, and
  RX_VK_RT_EMITTERS_LOG=<n> dumps the candidate blocks' words of the first n draws.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
The lanterns' bulb is an unlit blended ball (program 38cdd9d8563b16eb): its fragment stage stores the draw words c3[12..15] as colour and alpha, its
vertex stage places it with the object block's matrix and adds no origin (the lit programs add words 16 to 18; the census' places 100 m off and z 2539
were those words). One sphere light of the game's lamp units a bulb: colour gain * rgb * weight, radius 15 cm (larger over colour 100, keeping the far
field), range where the irradiance falls to 0.02; held for the area; a bulb with a game lamp within 0.6 m is left out. The rule names no program: an
unlit program whose colour is draw words alone, blended, an indexed mesh. The analysis keeps the output's alpha (rt_emit_*.h). The glow family of the
first attempt occurs in none of the census' areas and is gone, with its mask machinery in rt_lights.glsl and the Lamps shader (headers regenerated).

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
A lit program whose emission is draw words and textures with nothing per pixel (class solid, dependence solid: the Market's windows 6632b6fd1c32da37,
fdc8e3a0c08d599d, 73a306738ebf18ba, output plus texture * c5[106]) gives the same light from every camera position. Its triangles through the object block's
matrix with its origin give the surface: area, centroid and winding normal; a flat one is an area light of ours (type 200: L A cos(theta_e) / (d^2 + A), nothing
behind it), a closed one a sphere. Radiance is the folded colour times a share (0.5, RX_VK_RT_PANE_SHARE: the texture's mean is not known). Held for the area,
dropped when the draw words give 0. The Lamps picture shows an area with one ray to its centre. The view-dependent, storage-instanced windows (edd50455bcaa915d)
give no place and are not lights; the notebook and docs say why.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
The scene's status line says "37.0 in the top level, 6.5 cut by a micromap": the 6.5 is the mesh draws captured this
frame that have cards (st_cards), not the instances with bits, so it cannot say which entries lack them. Every instance
placed is now tallied by its mask's class (opaque, cutout, skinned, cascade, foliage, late, blocker, caster) and, if it
has no bits, by the reason: not in the cut family, skinned, no texture yet, the frame's budget, arena full, not baked,
a mesh draw that is not cards, the static shadow map's. Every 600 frames (RX_VK_RT_ALPHA_CENSUS=1, off by default) a
`vk: rt alpha census:` line gives a frame's mean of each, and a second line the triangles and micro-triangles baked.
hit::cut and hit::mesh_bake say why they gave none.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
The mesh cards' bits were baked at mesh_omm_level(), the micromaps' RX_VK_RT_OMM_LEVEL (default 3): 64 micro-triangles a
triangle, 8 cells to a side, for cards whose texture is a layer of a 128 x 128 or 256 x 256 array holding a cluster of
leaves (census-market-2). A sun shadow cut by that is a blob. They now have a level of their own,
RX_VK_RT_ALPHA_MESH_LEVEL (3 to 5, default 5; the Market's mesh draws are 35k triangles in room, 4.5 MB at level 5), and
when the arena has no room for a draw's bits at that level it takes the finest that fits instead of leaving the cards
whole. The static cut-outs stay at level 4 (RX_VK_RT_ALPHA_LEVEL, when set: for every draw) but a draw of up to 4096
triangles (a card, a bush) is baked at 5 while the arena is under 5/8 full; the frame's budget of triangles counts a
level-5 triangle as four. The arena's default is 128 MB (RX_VK_RT_ALPHA_MB) for that. rt_hit_math.h has the choice and
the weights, tested in tests/test_rt_hit.cpp.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
rt_alpha_solid confirmed every candidate past kAlphaCap (24) as solid so that the loop always ends. A sun ray runs 300 m
through the top level, and through a canopy of cards it meets dozens of triangles (each card two, the leaves' cards lying
over one another), most of them holes: past the 24th the ray was dark whatever the leaves were, which makes a soft blob of
the thick middle of a crown. 64 still bounds the loop. Not settled without a run: how many rays reach either cap.
Our ALPHA variant headers are made again (rt_alpha_build.sh, rt_hit_build.sh, rt_lamp_build.sh, rt_show_build.sh, glslang
16.6.0); no header of #727's differs from pr/727.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
A skinned cut-out was never given bits: cut_note was skipped for it (`cutout && !n.skinned`) and cut_bits returned none for
n.skinned, so its instance was FORCE_OPAQUE and a ray hit the whole card. Its triangles and their texture coordinates do not
change with the pose, and its bottom level is built from the draw's own index buffer (the skin shader moves the vertices
only), so primitive i of the bottom level is triangle i of the draw: the bits baked for the draw serve every pose. cut_note
now runs for a skinned draw and cut_bits places the bits at the skinned instance, the kept skinned objects too
(RX_VK_RT_ALPHA_SKINNED=0: whole as before; the hit record's matrix of a skinned draw stays as it was). Not seen in a run:
whether every skinned cut-out program's coordinates are attribute 8 as cut_note reads them.
tests/test_rt_hit.py checks the new hooks and switches (census off by default, the mesh level, the level fallback, skinned),
and the docs' "Cut-outs without micromaps" says what has bits at what level and what has none.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
The bake of the mesh cards (level 5: 1024 texture lookups a triangle) ran at every capture of every draw, about 48,000
triangles a frame in the castle approach, +1.7 to +3 ms of GPU. Its input is the records' texture coordinates and layer
(the wind moves the cards' positions, not these), so rt_hit_uvhash.comp hashes them per capture, in the records' order (the
bits are by triangle number), and the last workgroup compares the hashes and the corner count with those of the bake the bits
stand from and writes the groups of the bake (vkCmdDispatchIndirect): none when the same. A new texture view, threshold,
shape, range or level forces a bake, and so does a check every 600 frames (a texture's pixels may change under a view). A
draw whose bits are baked again on most of 16 captures is churning (the culled set or the order the compute fallback writes
the records in changes from frame to frame: nothing to keep) and is baked at level 4. The census line gives captures
asked, baked (GPU's count, read back late), reused and the churning draws.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
rt_hit_debug.comp (the recipe's 128 ops) and rt_show_lamps.comp (the area
lights) met rt_alpha.glsl's change (64 candidates) on this branch: their
ALPHA variants are made again with glslang 16.6.0 by rt_hit_build.sh and
rt_show_build.sh. Every other header of ours comes out byte for byte as
committed, and #727's own headers are not written.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
The height-field ground was left out of hitc because its patches' vertices are ours (no coordinate to read) and its lit programs pick the albedo
array's layer from the patch's map per pixel (a layer the recipe refuses); the mesh cards because their coordinates are words of a records buffer
the next mesh draw overwrites.

Ground (kind 4): the record holds the map's matrix, the map's and the albedo array's bindless slots and an entry of the residuals' table that holds
the patch's table of 124 ids (layer, planar scale); the hit shader reads the map's texel at the hit's world x and z and samples the albedo array.
Cards (kind 3): rt_hit_cardsuv.comp copies each triangle's coordinates and layer into a soup kept for the draw (vk_rt_hitmesh.cpp); the hit shader
reads it by primitive and samples the card array. Three hook lines in vk_rt_scene.cpp; logs say what each first record was made of.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
The mesh cards' arrays were all refused (14400 of 14394 refusals in 600 frames): a card atlas is a 2D array too big to keep whole, so the texture part keeps it
as a sparse image, and the bindless table refused sparse textures. A sampled read of a tile with no memory is a zero, not a fault, and the game's own draws made
the layers resident: the table now borrows them. Every refusal is told once per texture with its reason, format, layers, levels, flags and view.

A terrain instance with no ground record says once per program why (no lit draw of its geometry, or the first test of ground_of that failed, with the fragment
stage's blocks and texture descriptors). The records that have a coordinate and no colour texture (yellow in hitc) are counted by program and the top ten
told every 600 frames with the recipe's state and reason.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
The table refused every square 2D array as "a cube": Texture::cube is VK_IMAGE_CREATE_CUBE_COMPATIBLE, which a square array has, and a 2D array view of it is as
good. The card atlases (128x128, 27 to 396 layers) and the ground's albedo array (1365x1365, 90 layers) were those seven refusals.

The textured hit views took every instance, the shadow casters and blockers too: 1067 instances a frame of the program ffb53ed102dd9908 (depth only, no lit draw
of their geometry) lay over the ground and cliffs and drew yellow. They now take what the camera sees (0x37) unless RX_VK_RT_DEBUG_MASK is set; the log's top ten
tells each program's geometry and instance masks.

A patch drawn again by the holes' stage (the map and no albedo) kept the lit program's ground material only until that draw replaced it; it is kept now.
A texture handle that gets no slot by a way the table does not tell is logged once.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
#727 changed rt_refl_lookup.frag (a self-lit hit takes its colour from the
kept picture): our ALPHA builds of it are made again with glslang 16.6.0 by
rt_alpha_build.sh. Every other header of ours comes out byte for byte as
committed, and #727's own headers are not written.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
A: RX_VK_RT_EMITTER_LIST / ctl list= (full ranked light list), per-program table and the passes' list line in the status, RX_VK_RT_SHOW_MARKS / ctl marks= (marks in the
Lamps view), the pass list chosen by importance (strength over distance squared) with the left-out count; new-light lines up to 256.
B: RX_VK_RT_EMIT_CENSUS tells near refused/none/literal/unread draws (why, place, blend, textures) and the first records of instanced storage-fed draws.
C: glass (closed glowing shapes) as one sphere over its bounds, merged with a bulb inside, shadow rays stop outside the glass; #727's glow family (emission_note's c5 words)
makes pane and glass lights (RX_VK_RT_GLOW); the analysis' view/residue classes optional.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
The lantern glass a1c74226a51fb7ce and the door's panes f76f461080f8dc36 store lit + emissive * c5[106] * c6[225] * rim; the dark evaluation took c6[225] for a light's source, so both
were `none`. A program that is `none` is read again with that product kept (the retry stands only if it finds an emission: 45 stages of the cache change, none refused); a select of one
condition inside its own arm is simplified (104 residue -> solid). E is folded as an upper bound (fold_bound). A draw is split into islands (connected triangles), each its own pane or
glass light with its bounds; islands are cached by the draw's geometry. RX_VK_RT_EMIT_PROBE names the draws under picture points. The flat pane's minimum area is 0.04 m2.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
The islands of a draw within RX_VK_RT_ISLAND_GAP (0.5) of each other's size are one shape: a closed group is one glass over its bounds, a flat one one pane over its extent. A shape
refused for a program is told with its rule (area, size, triangles, small pane, fairy) and one example in the program's row; a light's line has the folded colour, area and islands. The
bulbs' bounds, the glow family's falloff and a draw's islands are kept by a mesh key (6 small reads a draw) and counted in the status line.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
The gain of the lights made from bulbs, glass and window panes is a row of 37 steps (a factor 1.25 each, x0.018 to x55.5, the middle exactly x1) that applies at
once: the lights are made at gain 1 and rank() gives the passes a copy with the colour times the gain and the range made again for it, so a change needs no
relight and no restart. F5 steps down, F6 up (with the lamp list read; not bindable); each change logs `vk: rt emitters: gain now x<value>`. The row is not saved:
every start is RX_VK_RT_EMITTER_GAIN's nearest step. Checks for the steps and for apply_gain; the checks of the keys and rows by text follow.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
A lower gain shrank every light's range (made again for the weaker colour) and cut lights off where they reached before. Now the lights are made without the
gain (no `* t.gain` in the making; RX_VK_RT_EMITTER_GAIN is only the row's start), are ranked at gain 1, and rank() gives the passes a copy with the colour
times the gain after the ranking: range, radius, place, kind and the set of lights given are the same at any gain.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
RX_VK_RT_EMITTER_GAIN's default, the Ray tracing: lantern light row's start, is 1.25^-11 (step 7). The owner chose it by eye in the Lamps view at the door with the
four lanterns on 2026-11-16, to be validated again once the lantern lights are part of the final picture: not a measured value. The row's steps, its middle at
exactly x1, the lights made at gain 1 and everything the gain does not touch are as before.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Where the device has no opacity micromaps (RX_VK_RT_ALPHA=1), three things for
the sun's and the AO's rays of the mask part and for GI's:

- The exact test (RX_VK_RT_ALPHA_EXACT, on by default; control file
  RX_VK_RT_ALPHA_CTL with exact=, lod=, lodnear=, lodmax=): the baked bits stay
  the quick "may be covered" test, and a candidate in a covered cell fetches
  its triangle's coordinates, samples the game's texture through the bindless
  table and applies the bake's own alpha rule, as an any-hit shader would. A
  frond card of one to three metres had cells of 3 to 9 cm at level 5 and came
  out nearly solid; with the test its needles and gaps are there.
- The static shadow map's mesh-shader casters get bits and an exact record.
- The kBlocker class (models only the cascades or the static shadow map draw
  and the camera never has: the game's own low-detail shadow models, in which
  leaf cards are solid polygons) is far only: a sun ray whose receiver is
  within RX_VK_RT_BLOCKER_NEAR metres of the camera (50; 0: off, #727's
  behaviour; blockernear= in the control file) passes it. The game uses those
  models where its static shadow map applies, far from the camera; in the rays
  they were hit at every distance and filled a tree's shadow. The price: a
  real object the camera has never drawn casts no shadow onto receivers within
  that distance until the camera has seen it once.

Measured on an RX 9070 XT in the Market by night at the pine, #727's default
shadow mask, the sun's term hard and unfiltered, mean brightness of the tree's
shadow (the game's own about 84): 55 without both, 62 with the exact test
alone, 69 with the blocker rule alone, 79.5 with both; the mask part's rays
1.18, 1.49, 1.38 and 1.85 ms. Lamp shadows and the reflections' lookup keep
the bits alone (their pipeline layouts are the game's). The branch's rejected
attempts (copies matched by geometry, by place, by pass, by vertex layout) are
not in this commit.

Our ALPHA and EXACT headers are made with rt_alpha_build.sh,
rt_alpha_exact_build.sh, rt_hit_build.sh, rt_lamp_build.sh and
rt_show_build.sh (glslang 16.6.0); none of #727's headers is written.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
The bulbs, glass and panes are entered in a world grid of 8 m cells (a hash table of buckets with linear probing on the GPU, up to 24 lights a cell, the ones with the most
irradiance at the cell's centre stay), 1024 lights held. The Lamps picture walks the pixel's own cell and the game's short global list; the marks go over every light. The grid is
rebuilt only when the set of lights changed (a light added, let go, moved, its range grown); the live gain and the fade rewrite the lights' words alone. New lights fade in and
gone ones fade out over half a second. The ranking by the camera and its slots are gone.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
rt_di_policy.h: bit 32 needs bit 4, the lamp list wanted by the bit, the term's strength (pi times the sum of rt_light_radiance: the
Lamps view's pixel for a white surface), the pass's size, the control words di= and disize=, the status line. rt_di.comp: the Lamps
view's place, normal and shadow ray for the lights of the grid alone, at half the scene's size; rt_di_up.comp: global illumination's
upsample weights, added to its added image. rt_di_build.sh makes the four headers (plain, OMM, ALPHA; the upsample); none of #727's.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
vk_rt_di.cpp runs the two passes after GI's upsample and before the first lit draw, so GI's filters never blur the shadows; the lit programs
multiply the sum with the albedo as they do the bounce. Hooks in #727's files, marked: the image's creation also for this bit, the call, the
present, the bit in mode() (dropped without bit 4, logged), the lamp list read by the bit. A row "Ray-traced lantern lights" after the lamp
shadows'. Status line every 600 frames (vk: rt di:), profile spans, RX_VK_RT_DI_SIZE=half|full.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Co-Authored-By: Claude Fable 5.2 <[email protected]>
Hyrule Field's ground is textured once the game's lit ground program (de97d1daff5eb7a7) is built: the draws of a program whose pipeline is not ready are left out in
vk_draw.cpp before the scene part is told of them, so until then a patch is known only from its depth and shadow variants (the holes' stages, map and no albedo)
and has no material. Not a failed association: the lit draw does not exist yet.

The log now says once for each patch geometry which program placed it (and its instance mask), and which lit programs were seen for it with ground_of's verdict,
or that none was yet. A mesh instance with no card coordinates says whether its draw was solid (no coordinate word), a leaf shape (no texture) or not captured here,
and the 600-frame line counts the three.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
RX_VK_RT_EMITTER_GAIN's default, the Ray tracing: lantern light row's start, is 1.25^-7 (step 11), in place of x0.0859. The owner chose it by eye on 2026-11-16 in the
final picture (the lantern lights added through GI's term, the Market's door with four lanterns, by night): x0.262 and above looked overbright to him. x0.0859 had been
chosen in the Lamps view on a white surface. Not a measured value: the game's own baked glow around the lanterns is under it.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Three diagnostics for "what is casting that shadow", none on unless asked:

- RX_VK_RT_SCENE_BIG=<n>: every 600 presents the n largest instances of the
  frame's top level, the n largest above the camera and the n with no box
  that have the most triangles, each with its geometry key, class, the passes
  and programs that drew it and their blend and depth state.
- RX_VK_RT_SCENE_LEAVE=<key>,... and the control file RX_VK_RT_SCENE_CTL
  (leave=...; kinds: mesh, nobox, class:<mask>, prog:<key>): geometry left out
  of the top level, to prove a cause in one run.
- RX_VK_RT_SCENE_WHO=x,y;... (who= in the control file): for up to eight
  points of the picture, a ray from the surface seen there towards the sun
  with the mask part's own start, length and mask (rt_scene_who.comp, made by
  rt_scene_who_build.sh), and the log names the instance it meets.

They found Kakariko's night shadow: the sun rays of the village's ground are
stopped from below, 8 to 15 m up, by the terrain's patches. The game cuts
holes into its height field per pixel where the village's own ground lies
lower; the top level's patches have none. Leaving the patch geometry out
lifts the sun picture's mean from 35 to 62.

Hook lines in #727's vk_rt_scene.cpp and vk_rt_mask.cpp are marked; none of
its headers is written.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
The game discards the ground where its map has a hole (max(red, green) of the nearest texel over 0.50186; read from the SPIR-V of the lit ground programs and the holes'
stages), and a village's own ground lies below the height field there. The top level's patch was the whole grid, so it lay over the village as a solid sheet and the sun
saw a back face 8 m from every point in it (Kakariko by night: the sun picture's mean 35, 62 without the patches).

Without micromaps (RX_VK_RT_ALPHA=1): holes_note is read for the bits too; when a patch is built, vk_rt_holes.cpp asks the bits arena for its triangles and, right after
rt_scene_terrain.comp wrote the vertices (world positions: the map coordinate of a triangle's point is the matrix applied to it), rt_terrain_holes.comp sets each
micro-triangle's bit where the map is solid at any of four places in it. The instance is placed like a cut-out. The EXACT builds look at the map's texel at the
candidate's own place (a kind 4 record; rt_alpha.glsl gets the candidate's world place as an argument of the EXACT builds alone, whose three headers are made again).
RX_VK_RT_TERRAIN_HOLES=0|1 (default 1), holes=0|1 live in RX_VK_RT_ALPHA_CTL, a status line, tests/test_rt_terrain_holes.*, docs.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
A flat pane made from a lit program whose emission is class pixel with dependence view (the angle fade of the normal and the view) is a window: kind=window in the light list,
(window) in the program table, a yellow mark in the Lamps picture (the lamps shader's headers made again with rt_show_build.sh), and the status line counts the windows made, new and
held, and the ones refused by reason. The light is the pane's of before (the head-on value by fold_bound, the share standing for the texture, the winding normal, the area record), which
the camera plays no part in; tests: the same light from both sides of the pane, a closed object of such a program is no window, the record's mark, the list's and the table's words.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
rt_emit_records.h runs the vertex stage's address arithmetic (the instance number, the driver bank's descriptor words, the table's value, the strides and field offsets) over the
stage's SPIR-V and writes down each load from a storage block: for an instance 0 and 1 and a table value of 0 and 1 the addresses differ by the table's and the record's strides alone,
so the layout (table, records, the fields read, the words every instance shares, the draw's matrix) is the stage's own, not a guess from the blocks' sizes. The census tells the layout
and, for up to eight instances spread over a draw, the record's bytes, its fields, the clock and the instance's place; a stage with records and a clock is a particle system's
(`particle=1` on its lines, `particles=` in the summary), by what it reads and not by a program's name. The earlier size guess logged nothing for edd50455bcaa915d.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
The near lines (the draws the analysis refused, judged dark or did not read) told only draws within 15 m of the camera: a village's lit windows in view but 40 m off were never named.
RX_VK_RT_EMIT_NEAR=<metres> (1 to 1000, 15 by default) widens it.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Kakariko's lit lattice windows (3be28542db4ee637: lit, emission c5[32..34] * c5[106] * c6[225] * (1 - t.a) * (c5[73] + |N.V|^c5[72]), the Market windows' make) were refused:
the analysis calls the program's dependence `screen` for its front-facing flag, which only turns the normal the rim takes the absolute value of. front_only_screen admits a gated
pixel program whose ONLY screen leaf is that flag, with no point of its own, and gated by both c5[106] and c6[225] (31 programs of the cache have that gate; this is the one that was out).
RX_VK_RT_EMIT_PROBE read `0.16,0.165` as nothing: a number with a decimal point is now a fraction of the scene's size, a draw near a point whose triangles are not read is told, and
far draws the analysis cannot use are counted (far_unusable=) in the summary.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
The game's lit fragment programs are given, by a SPIR-V patch of the family of the GI, reflection and lamp patches (rt_guide_spirv.h, made where a
module is made, after those three), three image stores at the pixel's own place: the shading normal with the normal map in it and the roughness
(RGBA16F), the diffuse albedo (RGBA8) and F0 with a flags byte as its alpha (RGBA8; flags 0 is "no guide"). Where each value is: the albedo the
lighting loop's diffuse accumulators' channel-specific invariant factor (rt_roles_spirv.h's finder, without the lifting), the normal the diffuse
cube lookup's direction (x, y, -z, normalised), the roughness the other factor of the specular lookup's level, F0 the constant 0.04 or the three
fma(metal, c - 0.04, 0.04). The stores sit after the later lookup where every value is defined (the blocks' dominators checked), under early
fragment tests (the lit draws test EQUAL after the pre-pass and write no depth). Over the program cache: 22,037 of 46,412 fragment stages are
patched, 18,665 with every guide; a module no check refuses is checked for every operand defined where used (rt_guide_check.h: no spirv-val here).

Storage images in a descriptor set of ours (vk_rt_guides.cpp), not extra colour attachments: the targets' machinery counts them in some sixty
places and the guides-off pipelines stay as they were (no program patched, no set made). The images are cleared at the first patched lit draw into
the scene of each frame; a draw that blends, or into another target, binds a scratch set of one texel. RX_VK_RT_GUIDES=0|1, a status line every
600 frames (vk: rt guides:). Views Normal, Roughness, Albedo, F0 and Guide coverage on the Ray tracing: view row (F7, RX_VK_RT_VIEW=normal|roughness|
albedo|f0|guides): rt_guide_view.comp, made by rt_guide_build.sh (a header of ours; none of #727's touched). Hooks in the project's files are marked:
vk_progcache.cpp, vk_draw.cpp (three lines), vk_rt.h, vk_shader.h (Program::rt_guide), vk_rt_di.cpp present (the status line). Docs: Guide buffers.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
At the fog's composite of the world, with the opaque scene lit and before the game's fog and tone mapping (and before global illumination keeps the
lit colour), a compute pass (vk_rt_di_def.cpp, rt_di_def.comp, made by rt_di_def_build.sh: scene size, or half with rt_di_def_up.comp's plane-aware
upsample; plain, OMM and ALPHA builds) walks, for every pixel with a guide, the lights of its grid cell, traces the injected way's own shadow ray for
each, and adds to the scene's HDR colour kInjectScale * (albedo * sum(incident * N.L / pi * vis) + spec * sum(incident * lobe * vis)) with the
guide's shading normal, roughness and F0. The diffuse term is the injected way's (deferred_diffuse == lit: tests/test_rt_di.cpp); the lobe is the
game's own lamp specular read in the world program's text (Schlick F with the game's exponent, GGX of alpha = roughness^2, Schlick-GGX Vis with
k = (roughness + 1)^2 / 8), widened by the light's angular size (Karis' sphere light) and at the diffuse term's scale. A pixel without a guide gets
nothing. The live gain scales both terms; RX_VK_RT_DI_SPECULAR / dispec= the highlights alone.

The way is chosen once a frame (rt_di_policy.h way_of: the control file's diway=, RX_VK_RT_DI_WAY, the guides being on): deferred by default when
the guides are on, never both ways. Bit 32 no longer needs bit 4 where the deferred way is possible (the row's text and the docs say so). Size: full
by default for the deferred way (RX_VK_RT_DI_SIZE, disize=), half for the injected way as before. The status line says way, size, highlights and
the pixels with and without a guide (counted by the pass, read back five frames on); profile spans for both passes. Docs: Lantern lights in the
picture, two ways; tests: test_rt_di.cpp / .py, test_rt_di_def.py.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Round 2 after the first GPU run. The deferred pass lights a pixel with no guide or no albedo (diffuse only, no highlight) from the guide's normal or
else the depth's, with the hue of the pixel's own lit colour at a mid reflectance of 0.5 (RX_VK_RT_DI_FALLBACK, RX_VK_RT_DI_MID, difallback=, dimid=; the
shaders' bits packed into the pass's div word), counts three kinds of pixel (every guide, the fallback, none and not lit) for the status line, and a pixel
with no light in its cell stops after the cell look-up and writes nothing. The guide views raise each value to RX_VK_RT_VIEW_GAMMA (2.2) first: they are
written into the linear colour the game then exposes, tone maps and encodes, which lifted every value and made them pale. New view Normal-map detail
(the angle between the shading normal and the depth's, 30 degrees white; RX_VK_RT_VIEW=normaldetail). One log line and a doc bullet say that the guides make
every lit pipeline again and what the first start shows; the code read for why patched and unpatched modules never mix. The vk_rt_scene.cpp message about
bit 32 now says it is only the injected way that needs bit 4. Cube-less lit programs (3,371 with the accumulators, 1,708 toon) have no readable normal
(the dot products' terms come in no fixed order or sign): counted, not patched, served by the fallback. Docs and notebook.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
rt_look.h defines the settings once (name, key, switch, steps, default, where they apply) and the rows, keys, on-screen line, log, options file keys and docs come from it:
Lantern light (moved, x0.21), Window light (a strength of its own for windows, times the lantern light's; their range follows it), Light reach, Light warmth (a blackbody
shift, luminance kept), Sun shadow softness and smoothing, Ambient occlusion strength and Bounce light strength (#727's tune: the rows are its lowest layer, its switches and
files win, a row at its default changes nothing), and Highlights, the deferred lantern pass's specular strength (rt::look::highlights(), vk_rt_look.h; RX_VK_RT_DI_SPECULAR
sets the row for a run, the control file's dispec= is over it while set). The rows are saved and are a group the entry row "Ray tracing: look settings" opens (row_shown hides
them; the control bridge lists and sets them either way); a key shows the setting's name and value on the screen for 2.5 s and logs `vk: rt look: <name> now <value>`.
The light grid is rebuilt when a range moves.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
feat(vk): rt look: the owner's values are the defaults: Lantern light x0.328, Window light x2.44
Some checks failed
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 6s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
79d6d5350a
Lantern light starts at step 13 (1.25^-5, x0.328) and Window light at step 14 (1.25^4, x2.44); the other settings stay at their defaults, which the owner tried and left.
Chosen by the owner by eye on 2026-11-16 in the final picture with the deferred lantern light and its highlights, in the Market, Kakariko and Hyrule Field by night and
day; x0.328 replaces x0.21, chosen before the highlights and the normal maps were in the light. Not measured values.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Drommedhar force-pushed feat/path-tracing from 79d6d5350a
Some checks failed
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 6s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
to f86523bf67
Some checks are pending
CI / Conventional Commit title (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions
CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions
Guide screenshots / Guide images and local UI source review (pull_request) Blocked by required conditions
Third-party parts / As their notes say (pull_request) Blocked by required conditions
Third-party parts / The same as upstream (pull_request) Blocked by required conditions
PR description / Description follows the template (pull_request_target) Successful in 10s
2026-11-16 18:54:24 +00:00
Compare
Author
First-time contributor

Rebased onto #727 at 19f973b0 and pushed: f86523bf, 70 commits of ours on top. Still WIP.

What changed

  • #727 took its own versions of three things that started here (cut-outs tested in the ray loop, the mesh-shader cards' bits, the bottom levels' budget from the video memory). Our copies are gone from this branch; the exact texture test, the terrain holes and the rest build on its.
  • The lantern lights have quality steps on their row (Off / Low / Medium / High / Ultra). A pixel traces a shadow ray only for the lights that matter to it, pixels where lantern light cannot show are skipped (by day 97 % of them), and the two lower steps work at half size. In the Market at night the pass takes 4.2 to 4.6 ms at Ultra, 2.5 to 2.8 at High, 0.9 to 1.0 at Medium and 0.6 to 0.7 at Low; four pictures of the steps look alike at 1280x720, a judgement at 1440p is still owed.
  • The kBlocker rule is done by the ray's instance mask (a sun ray whose receiver is within 50 m passes the game's shadow-only models), no longer in the candidate loop: 1.66 ms for the sun's and AO's rays against 1.74 with the rule off, the pine's shadow as before. #727's falling leaves keep casting at every distance.
  • The description's frame rates were wrong: they had been taken under the test profile's 60 fps cap at 1280x720. They are replaced by runs without a cap at 1707x960.

What the new measurements show

In a crowded place the cost is mostly on the CPU and mostly not ours: the Market's square by day runs 69 fps with ray tracing off, 30 to 35 with #727 alone and 28 to 32 with this branch. The render thread rebuilds the top level every frame at about 1.3 microseconds an instance (1.7 with our hooks), and a walk through the square fills the scene to 11,000 instances. Next here: a scene that keeps what has not changed, then reflections traced in one pass instead of in every lit program (facing water they are the largest GPU cost above the Low roughness step).

Checks: rt_ emit program_cache menu gain look readme audio linux_pressure: 86 pass, 1 fails (test_menu_save_atomic, which fails on #727 alone). The transform feedback capture, on by default again in #727, ran in two real sessions in the Market on the RX 9070 XT without a device loss.

Rebased onto #727 at 19f973b0 and pushed: f86523bf, 70 commits of ours on top. Still WIP. **What changed** - **#727 took its own versions of three things that started here** (cut-outs tested in the ray loop, the mesh-shader cards' bits, the bottom levels' budget from the video memory). Our copies are gone from this branch; the exact texture test, the terrain holes and the rest build on its. - **The lantern lights have quality steps** on their row (Off / Low / Medium / High / Ultra). A pixel traces a shadow ray only for the lights that matter to it, pixels where lantern light cannot show are skipped (by day 97 % of them), and the two lower steps work at half size. In the Market at night the pass takes 4.2 to 4.6 ms at Ultra, 2.5 to 2.8 at High, 0.9 to 1.0 at Medium and 0.6 to 0.7 at Low; four pictures of the steps look alike at 1280x720, a judgement at 1440p is still owed. - **The kBlocker rule is done by the ray's instance mask** (a sun ray whose receiver is within 50 m passes the game's shadow-only models), no longer in the candidate loop: 1.66 ms for the sun's and AO's rays against 1.74 with the rule off, the pine's shadow as before. #727's falling leaves keep casting at every distance. - **The description's frame rates were wrong**: they had been taken under the test profile's 60 fps cap at 1280x720. They are replaced by runs without a cap at 1707x960. **What the new measurements show** In a crowded place the cost is mostly on the CPU and mostly not ours: the Market's square by day runs 69 fps with ray tracing off, 30 to 35 with #727 alone and 28 to 32 with this branch. The render thread rebuilds the top level every frame at about 1.3 microseconds an instance (1.7 with our hooks), and a walk through the square fills the scene to 11,000 instances. Next here: a scene that keeps what has not changed, then reflections traced in one pass instead of in every lit program (facing water they are the largest GPU cost above the Low roughness step). **Checks**: `rt_ emit program_cache menu gain look readme audio linux_pressure`: 86 pass, 1 fails (`test_menu_save_atomic`, which fails on #727 alone). The transform feedback capture, on by default again in #727, ran in two real sessions in the Market on the RX 9070 XT without a device loss.
Owner

Brought up to the ready-for-review standard (#1454): the checklist's Everyone list has two new boxes, added here from what this PR's description and comments show (please check they match what you know).

  • Tested on my own PC: ticked: Testing's Tested: in-game and headless runs on Windows 11, Radeon RX 9070 XT by the branch owner.
  • Nothing gets worse that I know of: not ticked: Measurements verdict is still pending, so the lantern lights' frame cost is not stated. Measure that cost and state it in Risks, then tick it.
Brought up to the [ready-for-review standard](https://git.magicbean.dev/MagicBeanDev/Longshot/src/branch/main/CONTRIBUTING.md#ready-for-review-out-of-wip) (#1454): the checklist's Everyone list has two new boxes, added here from what this PR's description and comments show (please check they match what you know). - *Tested on my own PC*: ticked: Testing's Tested: in-game and headless runs on Windows 11, Radeon RX 9070 XT by the branch owner. - *Nothing gets worse that I know of*: not ticked: Measurements verdict is still pending, so the lantern lights' frame cost is not stated. Measure that cost and state it in Risks, then tick it.
Some checks are pending
CI / Conventional Commit title (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions
CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions
Guide screenshots / Guide images and local UI source review (pull_request) Blocked by required conditions
Third-party parts / As their notes say (pull_request) Blocked by required conditions
Third-party parts / The same as upstream (pull_request) Blocked by required conditions
PR description / Description follows the template (pull_request_target) Successful in 10s
This pull request has changes conflicting with the target branch.
  • README.md
  • docs/development.md
  • gpu/vk/vk_draw.cpp
  • gpu/vk/vk_main.cpp
  • gpu/vk/vk_memory.cpp
  • gpu/vk/vk_menu.cpp
  • gpu/vk/vk_menu.h
  • gpu/vk/vk_progcache.cpp
  • tests/test_audio_output_menu.py
  • tests/test_menu_keys.py
  • tests/test_menu_sections.py
  • tests/test_recorder_sync.py
Some workflows are waiting to be reviewed.
View command line instructions

Manual merge helper

Use this merge commit message when completing the merge manually.

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u 'feat/path-tracing:Drommedhar-feat/path-tracing'
git switch 'Drommedhar-feat/path-tracing'
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
MagicBeanDev/Longshot!1151
No description provided.