Keep RR guides and separate alpha in VRAM

docs/architecture.md

@@ -44,9 +44,15 @@ Feature 13 uses the NGX core's CUDA lifecycle, not the denoiser's native D3D12 b
 
 Feature requirements may be queried before NGX initialization. The shim loads the providers without initializing NGX with a provisional application identity; when the core declines feature-13 discovery, it asks the CUDA-capable denoiser's D3D12 requirements export for the adapter's eligibility. This discovery-only call does not select the native D3D12 rendering backend. Initialized capability checks and feature creation still require the core's successful denoiser initialization.
 
-The shim snapshots denoiser guide bindings, scalar settings, camera matrices, and subrect origins per submitted frame. Normals and roughness use the SDK's `GBuffer.Normals` and `GBuffer.Roughness` resource keys; diffuse and specular albedo bindings are translated to the CUDA denoiser's `DLSS.Input.*Albedo` keys. Guide readback and CUDA upload follow the main input marker, and the backing resources remain held until that frame retires. Uploads use per-slot host staging because direct ROCm image copies from Vulkan-mapped memory truncated guide rows on gfx1201. CUDA parameters point at stable texture-handle storage, not D3D12 resource pointers. Normals preserve the caller's component values rather than being renormalized during format conversion.
+The shim snapshots denoiser guide bindings, scalar settings, camera matrices, and subrect origins per submitted frame. Normals and roughness use the SDK's `GBuffer.Normals` and `GBuffer.Roughness` keys; albedo bindings are translated to the CUDA denoiser's `DLSS.Input.*Albedo` keys. CUDA parameters point at stable texture-handle storage, not D3D12 resource pointers. Normals preserve the caller's component values rather than being renormalized during conversion.
 
-Separate alpha output follows the same produced-frame slot as RGB, including its output resource and subrect. Requesting separate alpha cuts over through the existing drained host-staging path instead of publishing mismatched VRAM RGB and alpha results.
+With VRAM interop, guides copy from Vulkan images into per-slot shared device buffers, then into the CUDA arrays sampled by the denoiser. Half, float, UNORM, and SNORM layouts copy verbatim where possible. BGRA and packed RGB formats are converted to RGBA32F by a Vulkan blit. Raw integer guides retain the host conversion because integer-to-float blits do not reproduce its semantics. CUDA import happens on the worker after allocation, outside the guide-binding lock. The input marker orders both routes, and resources remain held until their frame retires.
+
+`D4R_SHIM_RR_VRAM_GUIDES=0` selects the host guide route for A/B checks without disabling RGB VRAM interop. `D4R_SHIM_VRAM_VERIFY=1` also stages the guides and compares the actual CUDA arrays against the CPU conversion, failing the frame on mismatches. Verification preserves pitch-linear input row alignment; diagnostics must not replace GPU geometry with a tightly packed host stride.
+
+Separate alpha no longer forces RGB through host staging. R32F alpha copies from the denoiser's CUDA array into a shared result buffer and into the caller's subrect; half and UNORM destinations use a GPU blit. Raw integer destinations keep their existing host conversion, independently of the RGB route. Blit rounding is hardware-dependent and can differ from CPU conversion by one destination quantization step.
+
+Split frames reserve the current frame's alpha slot before its producer runs. Previous-frame presentation matches alpha to RGB's produced frame and validates its format and subrect. Pixels outside the evaluated rectangle remain untouched. `D4R_SHIM_ALPHA_VERIFY=1` compares the array region with its shared buffer; combined with output capture, it also saves that region as `*.rgba16f.alpha.f32`.
 
 ## Why each piece exists
 

docs/building.md

@@ -104,6 +104,25 @@ scripts/d4r_play.sh
 
 In the game, pick DLSS as the upscaler (OptiScaler intercepts it). Every setting in the file can also be given as an environment variable, which takes precedence; `D4R_NO_CONFIG=1` ignores the file.
 
+### Cyberpunk 2077 RR launch notes
+
+The optimized RR route was exercised in a loaded Cyberpunk 2077 2.31 save on RX 9070 XT (gfx1201), with preset E, path tracing and Ultra Performance (640×360 → 1920×1080). The user also verified gameplay. This is a functional check, not a comparative FPS benchmark.
+
+On the tested GE-Proton11-3 setup, Wine's builtin ICU aborted on `icuuc.dll.u_setMemoryFunctions_65`. Use the game's native ICU DLLs for that setup:
+
+```sh
+WINEDLLOVERRIDES='icuuc=n,b;icuin=n,b;icudt=n,b;d3d12=n,b;d3d12core=n,b' \
+  D4R_RR_ENABLE=1 D4R_RR_PRESET=5 \
+  D4R_SHIM_VRAM_INTEROP=1 D4R_SHIM_SPLIT_FRAME=1 D4R_SHIM_LINEAR_INPUTS=1 \
+  D4R_ZLUDA_WMMA=1 D4R_ZLUDA_WMMA_FP8=1 D4R_ZLUDA_WMMA_FP8_NATIVE=1 \
+  scripts/d4r_play.sh
+```
+
+Merge these overrides with any existing `WINEDLLOVERRIDES`; do not discard overrides needed by other mods. Keep the patched vkd3d DLLs current, including game-local copies as described above. Select DLSS, Ray Reconstruction and path tracing in the game. `D4R_SHIM_RR_VRAM_GUIDES` defaults to `1` with VRAM interop; `0` selects host guide staging for A/B diagnostics.
+
+Leave `D4R_SHIM_VRAM_VERIFY`, `D4R_SHIM_ALPHA_VERIFY` and output capture disabled for normal play or benchmarking. The in-game diagnostic run enabled verification and reported zero differing bytes for all six supplied RR guides: normals, diffuse/specular albedo, specular hit distance, pre-particle color and the subsurface-scattering guide. Verification itself downloads GPU data.
+
+
 ## 7. Package a release
 
 ```sh
@@ -160,3 +179,29 @@ Run `bash scripts/build_release_glibc241.sh` inside the container. The script ch
   - `D4R_HARNESS_RECREATE_OUTPUT=1` releases and recreates the game's output texture between completed frames; compare its copy and in-place sequences to catch imported-memory handle reuse.
   - `D4R_HARNESS_RECREATE=4 D4R_HARNESS_VERIFY_RECREATION=1` checks repeated feature/quality recreation. `D4R_HARNESS_SKIP_RECORDED_INPUT=1` checks discarded command-list input readiness without injecting stale history.
 - Native kernels have their own validation path; see [native-kernels.md](native-kernels.md).
+
+### Ray Reconstruction VRAM comparison
+
+On the validated gfx1201/native-FP8 runtime, build the harness and shim, then compare host and GPU guide transport:
+
+```sh
+scripts/build_d3d12_dlss_harness.sh
+D4R_SHIM_SPLIT_FRAME=1 D4R_SHIM_LINEAR_INPUTS=1 \
+  D4R_SHIM_VRAM_VERIFY=1 D4R_SHIM_ALPHA_VERIFY=1 \
+  D4R_RR_ALPHA=1 D4R_RR_GUIDE_PROBE=1 \
+  D4R_HARNESS_TEMPORAL=1 \
+  D4R_HARNESS_SIZE='193 109 288 162' \
+  scripts/run_rr_guide_compare.sh /tmp/rr-compare \
+    rgba16f,rgba16f,rgba8unorm,rgba8unorm \
+    rgba8snorm,rgba16unorm,bgra8unorm,rgb10a2unorm \
+    rgba32f,r32f,rgb11b10float,rgba8unorm \
+    rgba16f,r32uint,bgra8unorm,rgba16f
+```
+
+The script stages the matching vkd3d DLLs, real DXVK-NVAPI, shim, and feature libraries together. It defaults to RR preset E and enables the required native-FP8 flags. Override `D4R_RUNTIME_DIR`, `D4R_PROTON_DIR`, or `D4R_VKD3D_DIR` for an isolated runtime. Neither feature discovery nor failed evaluation is bypassed.
+
+Every saved RGB and alpha frame is compared. The reset guide probe requires an image response, not spatial confinement: transformer attention may legitimately change both halves. `D4R_HARNESS_RR_ALPHA_FORMAT` selects `r32f`, `r16f`, `r8unorm`, or `r16unorm`; alpha captures are always decoded float32, with format-appropriate outside-subrect sentinels.
+
+Verification intentionally downloads GPU data. Unset `D4R_SHIM_VRAM_VERIFY` and `D4R_SHIM_ALPHA_VERIFY` for performance measurements and games. For same-frame conversion checks, combine alpha verification with `D4R_SHIM_OUTPUT_DUMP_DIR` and the existing dump frame selectors; compare each saved alpha region with the corresponding presented alpha capture, allowing one destination quantization step for blit rounding.
+
+`python3 -m unittest discover -s tests -v` includes output-comparator regressions for channel swaps, nonfinite pixels, missing/truncated captures, alpha frame mismatches, and writes outside the output subrect.

docs/performance.md

@@ -1,6 +1,6 @@
 # Performance
 
-Unless stated otherwise, the frame rates and kernel timings on this page were measured on an RX 7700 XT (gfx1101). Native FP8 changes both arithmetic and cost, so the gfx11 results cannot be projected to RDNA4; the one RDNA4 measurement is in [RDNA4](#rdna4). No RDNA4 game frame rate has been measured.
+Unless stated otherwise, the frame rates and kernel timings on this page were measured on an RX 7700 XT (gfx1101). Native FP8 changes both arithmetic and cost, so the gfx11 results cannot be projected to RDNA4; the RDNA4 Super Resolution measurement is in [RDNA4](#rdna4). The Ray Reconstruction measurements and Cyberpunk verification use an RX 9070 XT (gfx1201); the RR timings are synthetic harness measurements, not RDNA4 game-FPS benchmarks.
 
 ## Method
 
@@ -142,3 +142,26 @@ DLSS 4.5 (L) on the same card and harness, with enc0 and dec0 as ZLUDA's compile
 | **all kernels** | **5.83** | **4.06** | **5.93** | **4.34** | **8.63** | **5.69** | **5.99** | **4.14** |
 
 L's post kernel (1.2–1.5 ms) is the largest kernel left; it has no matrix multiplies. The 1920×1080 runs were taken in one of the two clock states the driver's governor settles in at that load (about 13% apart), so compare within the pair, not across resolutions.
+
+## Ray Reconstruction VRAM transport
+
+Measured separately from the Super Resolution game benchmarks above: RX 9070 XT (gfx1201), GE-Proton11-3, CUDA-capable DLSS-Denoiser 310.7, RR preset E, native FP8 WMMA and native Swin encoders. The synthetic D3D12 harness rendered 640×360 into 1280×720 with separate R32F alpha. Split-frame presentation and pitch-linear inputs were enabled; verification/capture downloads were disabled.
+
+Four back-to-back 40-frame runs used host guides, GPU guides, GPU guides, then host guides. The first five frames of each run were excluded; values below are warm-frame medians in milliseconds:
+
+| Guide transport | Worker time, first/repeat | Frame interval, first/repeat |
+|---|---:|---:|
+| Host staging | 14.967 / 14.296 | 17.373 / 16.795 |
+| Shared VRAM | 13.960 / 13.953 | 16.482 / 16.680 |
+
+All four final RGBA captures were byte-identical. The GPU guide runs recorded no host staging readbacks. This is a small synthetic transport comparison, not a game-FPS claim; network execution and clocks contribute to run-to-run variation.
+
+With the usual two RGBA16F and two RGBA8 guides, VRAM transport eliminates approximately 11.1 MB of guide payload crossing GPU↔CPU per frame at this render size (5.5 MB in each direction, excluding padding). Separate alpha also no longer forces RGB through host staging. Unsupported raw-integer guide/alpha formats retain their existing host conversion without disabling the other GPU routes.
+
+Correctness checks additionally covered five guide-format sets at an odd 193-pixel input width: 35 final/per-frame RGBA files were byte-identical between host and GPU guide transport. Six-frame source/presentation captures preserved RGB bytes and alpha subrect sentinels. R32F alpha was exact; half/UNORM blits can differ from the CPU quantizer by one destination step.
+
+An aligned 192×108→288×162 synthetic capture against native CUDA on RTX 4090 measured RGB PSNR 42.15 dB, mean absolute component error 0.00357, and maximum error 0.13623; neither image contained nonfinite RGB values. This spot check does not establish RTX image-quality parity or game-wide temporal correctness. Transport A/B comparisons on the same AMD backend were exact; cross-backend neural arithmetic remains a separate accuracy limitation.
+
+The optimized route also rendered a loaded Cyberpunk 2077 2.31 save at 640×360→1920×1080 Ultra Performance with path tracing and RR preset E on gfx1201. The overlay identified DLSSD 310.7.0; the shim created CUDA feature 13 with split-frame VRAM interop. In-game verification found zero differing bytes for all six supplied guide arrays, and the user verified gameplay. This diagnostic run enabled GPU readbacks and does not establish an FPS improvement or a game-wide artifact/latency audit.
+
+The extended diagnostic log also recorded prolonged split-frame waits and a GPU-marker timeout later in the run; their cause was not isolated. The successful rendering and guide comparisons are not evidence of stall-free operation.