fix(vk): make frame dump copies visible to host reads #1621

Merged

Arkex-ai merged 2 commits from fix/dump-readback into main

2026-11-10 12:47:17 +00:00

Arkex-ai commented

2026-11-10 11:23:45 +00:00

(Migrated from github.com)

Record a COPY/TRANSFER_WRITE to HOST/HOST_READ dependency for each dump staging copy, then invalidate its copied allocation range before the existing CPU consumers run. Cover typed color, packed depth/RGB9E5 and storage-buffer dumps. Depth is invalidated before conversion changes the dimensions/map. Existing GPU barriers, allocation policy, submission waits, conversions and cleanup are preserved; no host/renderer ABI or intended visual change.

Validation at 1ea25d452c852d51023cd5dd365d6fb20a951d95, based on main 779bdcf:

Actual baseline dump producers/consumers and full_barrier, with authored copy/cache/wait behavior: permissive coherent control passes; explicit host visibility or non-coherent cache requirements return stale output. This models the protocol; it is not a claim of observed corruption on NVIDIA.
56 game-free scenarios pass Windows LLVM, Linux GCC and Linux ASan/UBSan. They cover float/uint/sint, NaN/Inf, D16/D24/D32/RGB9E5, downscaled depth, capped buffer tail, raw float and statistics-only output, open-burst deferral, completion ordering and cleanup. Nine deliberately incorrect variants fail on output or invalidation ordering/range.
Complete Windows suite: 232 passed, 2 failed, 20 skipped; exact main: 231 passed, the same 2 failures and 20 skips. Local limitations remain NUP symlink privileges and unavailable native Windows SDK headers for the precompile guard. No assertions or checks were relaxed.
Official matching API12 host/backend build passes, reusing the clean official guest lift with identical generation inputs. An isolated serial/FG2 checkpoint run consumed one file trigger, produced six PNG/raw-float pairs and 41 buffer-statistic records, remained playable and exited0. PNG CRC/zlib decoding and independent raw-to-RGB interpretation agree; original checkpoint hashes remain unchanged. An earlier run also exited0 but its F9 request was not observed, so it is not counted as a successful dump.

This fixes opt-in diagnostic readback, not ultrawide framing itself. Native coverage is one checkpoint and does not prove physical non-coherent hardware, campaign coverage, performance or generic device-loss handling. Game-derived dumps and raw data stay private; only authored tests, source and documentation are included.

Details and primary references: docs/dump-readback.md. Existing capture-readback work (#1502), PNG publication (#1604), stage diagnostics (#1541), and control bridges (#926/#1025) were checked for scope overlap: this package changes the separate frame-dump staging producers/consumers. Exact-head fork source, Windows-builder and AppImage checks will be reported when available.

Native Windows compiler follow-up

The first source workflow exposed an existing packed-depth aspect enum ternary that native Windows clang rejects as a narrowing aggregate initializer. 08b6610 explicitly converts that expression to VkImageAspectFlags; both selected Vulkan values and readback behavior are unchanged. All 56 LLVM/GCC/ASan/UBSan scenarios and nine negative variants pass again, and the official matching API12 build passes. The native checkpoint evidence above remains tied to 1ea25d4; it is not relabeled as a new game run. Three new exact-head workflows are dispatched. No compiler diagnostics or test assertions were disabled.

Current-head validation

Current head f445caa, based on main ba40a1a. Earlier local/runtime results describe their recorded source hashes.

The standalone contribution patch is unchanged after the audited main refresh; exact-head build/source checks are refreshed below. Earlier runtime evidence remains tied to its recorded hash.

Fork runs are separate from upstream Actions approval; no maintainer approval gate is bypassed.

Frame dumps read mapped GPU copy destinations without invalidating non-coherent host caches, and their post-copy barriers cover device commands rather than host reads. Stale diagnostic pixels or buffer words can mislead investigations even after the submission has completed. Record a COPY/TRANSFER_WRITE to HOST/HOST_READ dependency for each dump staging copy, then invalidate its copied allocation range before the existing CPU consumers run. Cover typed color, packed depth/RGB9E5 and storage-buffer dumps. Depth is invalidated before conversion changes the dimensions/map. Existing GPU barriers, allocation policy, submission waits, conversions and cleanup are preserved; no host/renderer ABI or intended visual change. Validation at `1ea25d452c852d51023cd5dd365d6fb20a951d95`, based on main `779bdcf`: - Actual baseline dump producers/consumers and full_barrier, with authored copy/cache/wait behavior: permissive coherent control passes; explicit host visibility or non-coherent cache requirements return stale output. This models the protocol; it is not a claim of observed corruption on NVIDIA. - 56 game-free scenarios pass Windows LLVM, Linux GCC and Linux ASan/UBSan. They cover float/uint/sint, NaN/Inf, D16/D24/D32/RGB9E5, downscaled depth, capped buffer tail, raw float and statistics-only output, open-burst deferral, completion ordering and cleanup. Nine deliberately incorrect variants fail on output or invalidation ordering/range. - Complete Windows suite: 232 passed, 2 failed, 20 skipped; exact main: 231 passed, the same 2 failures and 20 skips. Local limitations remain NUP symlink privileges and unavailable native Windows SDK headers for the precompile guard. No assertions or checks were relaxed. - Official matching API12 host/backend build passes, reusing the clean official guest lift with identical generation inputs. An isolated serial/FG2 checkpoint run consumed one file trigger, produced six PNG/raw-float pairs and 41 buffer-statistic records, remained playable and exited0. PNG CRC/zlib decoding and independent raw-to-RGB interpretation agree; original checkpoint hashes remain unchanged. An earlier run also exited0 but its F9 request was not observed, so it is not counted as a successful dump. This fixes opt-in diagnostic readback, not ultrawide framing itself. Native coverage is one checkpoint and does not prove physical non-coherent hardware, campaign coverage, performance or generic device-loss handling. Game-derived dumps and raw data stay private; only authored tests, source and documentation are included. Details and primary references: `docs/dump-readback.md`. Existing capture-readback work (#1502), PNG publication (#1604), stage diagnostics (#1541), and control bridges (#926/#1025) were checked for scope overlap: this package changes the separate frame-dump staging producers/consumers. Exact-head fork source, Windows-builder and AppImage checks will be reported when available. ### Native Windows compiler follow-up The first source workflow exposed an existing packed-depth aspect enum ternary that native Windows clang rejects as a narrowing aggregate initializer. `08b6610` explicitly converts that expression to `VkImageAspectFlags`; both selected Vulkan values and readback behavior are unchanged. All 56 LLVM/GCC/ASan/UBSan scenarios and nine negative variants pass again, and the official matching API12 build passes. The native checkpoint evidence above remains tied to `1ea25d4`; it is not relabeled as a new game run. Three new exact-head workflows are dispatched. No compiler diagnostics or test assertions were disabled.  ### Current-head validation Current head `f445caa`, based on main `ba40a1a`. Earlier local/runtime results describe their recorded source hashes. The standalone contribution patch is unchanged after the audited main refresh; exact-head build/source checks are refreshed below. Earlier runtime evidence remains tied to its recorded hash. - [Linux AppImage](https://github.com/Arkex-ai/Hookshot/actions/runs/42809521849): success. - [Windows builder](https://github.com/Arkex-ai/Hookshot/actions/runs/42809518380): success. - [Game-free source regressions](https://github.com/Arkex-ai/Hookshot/actions/runs/42809514580): success. Fork runs are separate from upstream Actions approval; no maintainer approval gate is bypassed.