feat(vk): write back DEPTH24 kept as D32_SFLOAT as 24-bit unorm #1051

Open
jcabarca wants to merge 2 commits from jcabarca/Longshot:feat/vk-d24-readback into main
Contributor

Type: feat · Risk: low · Tested on: Windows, AMD Radeon RX 9070 XT · Needs: none

Why

When a DEPTH24 texture is kept as D32_SFLOAT (a GPU without 24-bit depth attachments), the depth the GPU draws is never written back to the game's memory, so a game that reads its depth buffer back gets stale data. This makes flushable() take that image, copy its depth aspect and hand the game its own 24-bit unorm words.

How to reproduce

Seen on: reading gpu/vk/vk_texture.cpp: flushable() returns false for any image whose aspect is not COLOR. On main vk_format() maps DEPTH24 to X8_D24_UNORM_PACK32 on every GPU, so this path acts only where DEPTH24 is kept as D32_SFLOAT
Settings and switches: defaults
Steps: game-free: python -I -B tests/test_d24_readback.py --source <main checkout> --headers <Vulkan headers> --cxx clang++ (the test from this PR)
Expected: a DEPTH24 kept as D32_SFLOAT is flushable, its depth aspect is copied out and each float becomes the game's 24-bit unorm word
Actual: on main the test fails with "flushable takes colour images only: a DEPTH24 kept as D32_SFLOAT is never written back"

What changed

A DEPTH24 texture kept as D32_SFLOAT is written back to guest memory like a colour render target, converted to the game's 24-bit unorm layout.

  • vk: flushable() in gpu/vk/vk_texture.cpp: also takes an image with nvn_format == DEPTH24, format == D32_SFLOAT and aspect DEPTH (DEPTH24_STENCIL8 stays out).
  • vk: flush_record(): the VkBufferImageCopy aspect is DEPTH for a depth image, COLOR otherwise.
  • vk: flush_finish(): after the mapped range is invalidated, each 32-bit float is clamped to [0, 1] (NaN as 0) and written back as (uint32_t)(v * 16777215.0 + 0.5); the top 8 bits, unused by DEPTH24, are zero.
  • tests: tests/test_d24_readback.py (new).

How it works, step by step:

  1. A DEPTH24 render target kept as D32_SFLOAT is drawn by the GPU.
  2. Before: flushable() saw aspect != COLOR and returned false; the guest memory kept what the game wrote before, never the depth drawn.
  3. Now flushable() takes it; flush_record() records vkCmdCopyImageToBuffer with aspectMask = DEPTH.
  4. The buffer for a depth aspect copy is laid out in the aspect's format (copies.adoc, Depth/Stencil Aspect Copy: D32_SFLOAT depth is copied as D32_SFLOAT), so the buffer holds floats.
  5. flush_finish() turns each float into the 24-bit unorm word the game expects, the inverse of the upload's (v & 0xffffff) / 16777215.0f. The conversion is done in double, since in float 1.0f * 16777215.0f + 0.5f rounds to 1 << 24.

The Vulkan rules for the copy this changes, from validusage.json:

  • VUID-VkBufferImageCopy-aspectMask-09103: "The aspectMask member of imageSubresource must only have a single bit set": met, DEPTH only.
  • VUID-vkCmdCopyImageToBuffer-imageSubresource-09105: "For each element of pRegions, imageSubresource.aspectMask must specify aspects present in srcImage": met, D32_SFLOAT has the depth aspect.
  • VUID-vkCmdCopyImageToBuffer-srcImage-07978: "If srcImage has a depth/stencil format, the bufferOffset member of any element of pRegions must be a multiple of 4": met, each part's offset p.at is 16-byte aligned.

Before (flushable() and flush_record()):

    if (!t.guest_size || t.guest_size > kFlushMax || t.astc || t.bc || t.sparse || t.skip ||
        t.samples != VK_SAMPLE_COUNT_1_BIT || t.aspect != VK_IMAGE_ASPECT_COLOR_BIT || t.bpb <= 0 || !t.image ||
...
        r.imageSubresource = {VK_IMAGE_ASPECT_COLOR_BIT, p.level, t.type == VK_IMAGE_TYPE_3D ? 0 : p.layer, 1};

After:

    const bool d24_as_d32 = t.nvn_format == NVN_FORMAT_DEPTH24 && t.format == VK_FORMAT_D32_SFLOAT &&
                            t.aspect == VK_IMAGE_ASPECT_DEPTH_BIT;
    if (!t.guest_size || t.guest_size > kFlushMax || t.astc || t.bc || t.sparse || t.skip ||
        t.samples != VK_SAMPLE_COUNT_1_BIT || (t.aspect != VK_IMAGE_ASPECT_COLOR_BIT && !d24_as_d32) || t.bpb <= 0 || !t.image ||
...
        r.imageSubresource = {t.aspect == VK_IMAGE_ASPECT_DEPTH_BIT ? VK_IMAGE_ASPECT_DEPTH_BIT : VK_IMAGE_ASPECT_COLOR_BIT,
                              p.level, t.type == VK_IMAGE_TYPE_3D ? 0 : p.layer, 1};
...
    if (ok && t.nvn_format == NVN_FORMAT_DEPTH24 && t.format == VK_FORMAT_D32_SFLOAT) {
        for (const Part& p : parts) {
            uint8_t* w = (uint8_t*)map + p.at;
            for (uint64_t k = 0; k + 4 <= p.n; k += 4) {
                float v;
                std::memcpy(&v, w + k, 4);
                v = v > 0.0f ? (v < 1.0f ? v : 1.0f) : 0.0f;   // (NaN to 0 too)
                const uint32_t u = (uint32_t)(v * 16777215.0 + 0.5);
                std::memcpy(w + k, &u, 4);
            }
        }
    }

Measurements

Verdict: it adds the write-back: tests/test_d24_readback.py fails on main and passes with this PR, in both interleaved runs. Colour textures are not converted (the test checks it).

Hardware: AMD Radeon RX 9070 XT, Windows; the test itself is game-free (it reads source and runs flush_finish()'s conversion, compiled out of the source); Python 3.12, clang++ (llvm-mingw)
Scene: none, game-free
Method: tests/test_d24_readback.py from this PR with --source set to each side's checkout, 2 runs each, interleaved (main, PR, main, PR); the result is pass/fail, so the median is the result both runs gave
How to reproduce: python -I -B tests/test_d24_readback.py --source <checkout> --headers <Vulkan headers> --cxx clang++ for each side

Before: main @ cefce0d1 After: this PR @ fd659584
tests/test_d24_readback.py, run 1 fails passes
tests/test_d24_readback.py, run 2 fails passes
Median fails passes
run 1, main @ cefce0d1:
flushable takes colour images only: a DEPTH24 kept as D32_SFLOAT is never written back
exit 1
run 1, this PR @ fd659584:
DEPTH24 kept as D32_SFLOAT is written back as 24-bit unorm words: ok
exit 0
run 2, main @ cefce0d1:
flushable takes colour images only: a DEPTH24 kept as D32_SFLOAT is never written back
exit 1
run 2, this PR @ fd659584:
DEPTH24 kept as D32_SFLOAT is written back as 24-bit unorm words: ok
exit 0

What the test checks:

  • flushable() takes a DEPTH24 kept as D32_SFLOAT with the depth aspect.
  • flush_record() copies the depth aspect of a depth image.
  • flush_finish() converts after invalidate_mapped(), not before.
  • The real conversion, compiled out of flush_finish(): 0, 1, 0.5, -0.25, 2, NaN, 1/16777215 and 0.75 become 0, 0xFFFFFF, 0x800000, 0, 0xFFFFFF, 0, 1 and 0xBFFFFF, over two parts; the bytes between parts are untouched, and a colour texture is left as it was.

Flags and settings

None.

Testing

Tested: on this branch, Windows, Python 3.12, clang++ (llvm-mingw): test_d24_readback passes (fails on main).

Built and played: this commit builds on Windows (llvm-mingw back end) and on Linux (longshot_vk.so, without and with AMD FSR 4). Played on Windows, AMD Radeon RX 9070 XT: the game runs normally.

Not tested: a scene that reads its depth buffer back on the CPU was not compared with main; on main DEPTH24 is never kept as D32_SFLOAT, so this path does not run there. Linux was built, not run.

Must be tested: None.

Risks

What could break: a DEPTH24 kept as D32_SFLOAT is now copied back to guest memory like colour targets are, which costs one copy per flush for those images. A float outside [0, 1] is clamped, as a 24-bit unorm depth cannot hold it.

Turning it off: revert the commit.

Compatibility: Nothing changes for colour images, DEPTH24_STENCIL8, or GPUs where DEPTH24 is X8_D24_UNORM_PACK32 (every GPU on main today).

Checklist

Everyone

  • One topic.
  • 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). (no issue fits)
  • Measurements has a verdict, or one line saying why there is nothing to measure.
  • Testing names what was tested, what wasn't, and what must still be tested, where and how.
  • Rebased on current main.
  • python -I -B tests/run_all.py passes (any failure that also fails on main is named). (the check that reads the changed code, on this PR, Windows: test_d24_readback passes)
  • 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.
  • A game-free test added for the fix, failing on main and passing here. (tests/test_d24_readback.py)
  • A check under tests/ that reads changed source updated in this PR, not weakened. (tests/test_d24_readback.py reads vk_texture.cpp; no other check reads the changed lines)
  • Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. (built on Windows with llvm-mingw and on Linux, longshot_vk.so without and with AMD FSR 4; no OS-specific code or paths)
**Type:** feat · **Risk:** low · **Tested on:** Windows, AMD Radeon RX 9070 XT · **Needs:** none ## Why When a DEPTH24 texture is kept as `D32_SFLOAT` (a GPU without 24-bit depth attachments), the depth the GPU draws is never written back to the game's memory, so a game that reads its depth buffer back gets stale data. This makes `flushable()` take that image, copy its depth aspect and hand the game its own 24-bit unorm words. ## How to reproduce **Seen on:** reading `gpu/vk/vk_texture.cpp`: `flushable()` returns false for any image whose aspect is not `COLOR`. On main `vk_format()` maps DEPTH24 to `X8_D24_UNORM_PACK32` on every GPU, so this path acts only where DEPTH24 is kept as `D32_SFLOAT` **Settings and switches:** defaults **Steps:** game-free: `python -I -B tests/test_d24_readback.py --source <main checkout> --headers <Vulkan headers> --cxx clang++` (the test from this PR) **Expected:** a DEPTH24 kept as `D32_SFLOAT` is flushable, its depth aspect is copied out and each float becomes the game's 24-bit unorm word **Actual:** on main the test fails with "flushable takes colour images only: a DEPTH24 kept as D32_SFLOAT is never written back" ## What changed A DEPTH24 texture kept as `D32_SFLOAT` is written back to guest memory like a colour render target, converted to the game's 24-bit unorm layout. - vk: `flushable()` in `gpu/vk/vk_texture.cpp`: also takes an image with `nvn_format == DEPTH24`, `format == D32_SFLOAT` and aspect `DEPTH` (DEPTH24_STENCIL8 stays out). - vk: `flush_record()`: the `VkBufferImageCopy` aspect is `DEPTH` for a depth image, `COLOR` otherwise. - vk: `flush_finish()`: after the mapped range is invalidated, each 32-bit float is clamped to [0, 1] (NaN as 0) and written back as `(uint32_t)(v * 16777215.0 + 0.5)`; the top 8 bits, unused by DEPTH24, are zero. - tests: `tests/test_d24_readback.py` (new). How it works, step by step: 1. A DEPTH24 render target kept as `D32_SFLOAT` is drawn by the GPU. 2. Before: `flushable()` saw `aspect != COLOR` and returned false; the guest memory kept what the game wrote before, never the depth drawn. 3. Now `flushable()` takes it; `flush_record()` records `vkCmdCopyImageToBuffer` with `aspectMask = DEPTH`. 4. The buffer for a depth aspect copy is laid out in the aspect's format (copies.adoc, Depth/Stencil Aspect Copy: `D32_SFLOAT` depth is copied as `D32_SFLOAT`), so the buffer holds floats. 5. `flush_finish()` turns each float into the 24-bit unorm word the game expects, the inverse of the upload's `(v & 0xffffff) / 16777215.0f`. The conversion is done in double, since in float `1.0f * 16777215.0f + 0.5f` rounds to `1 << 24`. The Vulkan rules for the copy this changes, from `validusage.json`: - VUID-VkBufferImageCopy-aspectMask-09103: "The aspectMask member of imageSubresource must only have a single bit set": met, `DEPTH` only. - VUID-vkCmdCopyImageToBuffer-imageSubresource-09105: "For each element of pRegions, imageSubresource.aspectMask must specify aspects present in srcImage": met, `D32_SFLOAT` has the depth aspect. - VUID-vkCmdCopyImageToBuffer-srcImage-07978: "If srcImage has a depth/stencil format, the bufferOffset member of any element of pRegions must be a multiple of 4": met, each part's offset `p.at` is 16-byte aligned. Before (`flushable()` and `flush_record()`): ```cpp if (!t.guest_size || t.guest_size > kFlushMax || t.astc || t.bc || t.sparse || t.skip || t.samples != VK_SAMPLE_COUNT_1_BIT || t.aspect != VK_IMAGE_ASPECT_COLOR_BIT || t.bpb <= 0 || !t.image || ... r.imageSubresource = {VK_IMAGE_ASPECT_COLOR_BIT, p.level, t.type == VK_IMAGE_TYPE_3D ? 0 : p.layer, 1}; ``` After: ```cpp const bool d24_as_d32 = t.nvn_format == NVN_FORMAT_DEPTH24 && t.format == VK_FORMAT_D32_SFLOAT && t.aspect == VK_IMAGE_ASPECT_DEPTH_BIT; if (!t.guest_size || t.guest_size > kFlushMax || t.astc || t.bc || t.sparse || t.skip || t.samples != VK_SAMPLE_COUNT_1_BIT || (t.aspect != VK_IMAGE_ASPECT_COLOR_BIT && !d24_as_d32) || t.bpb <= 0 || !t.image || ... r.imageSubresource = {t.aspect == VK_IMAGE_ASPECT_DEPTH_BIT ? VK_IMAGE_ASPECT_DEPTH_BIT : VK_IMAGE_ASPECT_COLOR_BIT, p.level, t.type == VK_IMAGE_TYPE_3D ? 0 : p.layer, 1}; ... if (ok && t.nvn_format == NVN_FORMAT_DEPTH24 && t.format == VK_FORMAT_D32_SFLOAT) { for (const Part& p : parts) { uint8_t* w = (uint8_t*)map + p.at; for (uint64_t k = 0; k + 4 <= p.n; k += 4) { float v; std::memcpy(&v, w + k, 4); v = v > 0.0f ? (v < 1.0f ? v : 1.0f) : 0.0f; // (NaN to 0 too) const uint32_t u = (uint32_t)(v * 16777215.0 + 0.5); std::memcpy(w + k, &u, 4); } } } ``` ## Measurements **Verdict:** it adds the write-back: `tests/test_d24_readback.py` fails on main and passes with this PR, in both interleaved runs. Colour textures are not converted (the test checks it). Hardware: AMD Radeon RX 9070 XT, Windows; the test itself is game-free (it reads source and runs `flush_finish()`'s conversion, compiled out of the source); Python 3.12, clang++ (llvm-mingw) Scene: none, game-free Method: `tests/test_d24_readback.py` from this PR with `--source` set to each side's checkout, 2 runs each, interleaved (main, PR, main, PR); the result is pass/fail, so the median is the result both runs gave How to reproduce: `python -I -B tests/test_d24_readback.py --source <checkout> --headers <Vulkan headers> --cxx clang++` for each side | | Before: main @ cefce0d1 | After: this PR @ fd659584 | |---|---|---| | `tests/test_d24_readback.py`, run 1 | fails | passes | | `tests/test_d24_readback.py`, run 2 | fails | passes | | Median | fails | passes | ``` run 1, main @ cefce0d1: flushable takes colour images only: a DEPTH24 kept as D32_SFLOAT is never written back exit 1 run 1, this PR @ fd659584: DEPTH24 kept as D32_SFLOAT is written back as 24-bit unorm words: ok exit 0 run 2, main @ cefce0d1: flushable takes colour images only: a DEPTH24 kept as D32_SFLOAT is never written back exit 1 run 2, this PR @ fd659584: DEPTH24 kept as D32_SFLOAT is written back as 24-bit unorm words: ok exit 0 ``` What the test checks: - `flushable()` takes a DEPTH24 kept as `D32_SFLOAT` with the depth aspect. - `flush_record()` copies the depth aspect of a depth image. - `flush_finish()` converts after `invalidate_mapped()`, not before. - The real conversion, compiled out of `flush_finish()`: 0, 1, 0.5, -0.25, 2, NaN, 1/16777215 and 0.75 become 0, 0xFFFFFF, 0x800000, 0, 0xFFFFFF, 0, 1 and 0xBFFFFF, over two parts; the bytes between parts are untouched, and a colour texture is left as it was. ### Flags and settings None. ## Testing **Tested:** on this branch, Windows, Python 3.12, clang++ (llvm-mingw): `test_d24_readback` passes (fails on main). **Built and played:** this commit builds on Windows (llvm-mingw back end) and on Linux (`longshot_vk.so`, without and with AMD FSR 4). Played on Windows, AMD Radeon RX 9070 XT: the game runs normally. **Not tested:** a scene that reads its depth buffer back on the CPU was not compared with main; on main DEPTH24 is never kept as `D32_SFLOAT`, so this path does not run there. Linux was built, not run. **Must be tested:** None. ## Risks **What could break:** a DEPTH24 kept as `D32_SFLOAT` is now copied back to guest memory like colour targets are, which costs one copy per flush for those images. A float outside [0, 1] is clamped, as a 24-bit unorm depth cannot hold it. **Turning it off:** revert the commit. **Compatibility:** Nothing changes for colour images, DEPTH24_STENCIL8, or GPUs where DEPTH24 is `X8_D24_UNORM_PACK32` (every GPU on main today). ## Checklist ### Everyone - [x] One topic. - [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). (no issue fits) - [x] Measurements has a verdict, or one line saying why there is nothing to measure. - [x] Testing names what was tested, what wasn't, and what must still be tested, where and how. - [x] Rebased on current `main`. - [x] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). (the check that reads the changed code, on this PR, Windows: `test_d24_readback` passes) - [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. - [x] A game-free test added for the fix, failing on `main` and passing here. (`tests/test_d24_readback.py`) - [x] A check under `tests/` that reads changed source updated in this PR, not weakened. (`tests/test_d24_readback.py` reads `vk_texture.cpp`; no other check reads the changed lines) - [x] Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. (built on Windows with llvm-mingw and on Linux, `longshot_vk.so` without and with AMD FSR 4; no OS-specific code or paths)
feat(vk): write back DEPTH24 kept as D32_SFLOAT as 24-bit unorm
Some checks failed
Website / Website on Cloudflare (pull_request_target) Has been skipped
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
fd65958409
flushable now takes a DEPTH24 image kept as D32_SFLOAT, flush_record copies its depth aspect and flush_finish turns each float into the game's 24-bit unorm word (clamped, NaN as 0, computed in double so 1.0 is 0xffffff). New tests/test_d24_readback.py.

Assisted-by: GitHub Copilot
Author
Contributor

Tested in game: Windows 11 IoT Enterprise LTSC 24H2 (build 26100.9711), AMD Radeon RX 9070 XT, AMD Software: Adrenalin Edition 26.10.1: played with this change; the game runs normally, no rendering errors or crashes seen.

Tested in game: Windows 11 IoT Enterprise LTSC 24H2 (build 26100.9711), AMD Radeon RX 9070 XT, AMD Software: Adrenalin Edition 26.10.1: played with this change; the game runs normally, no rendering errors or crashes seen.
Collaborator

Possibly related, for context:

  • PR #1033 feat(vk): fall back to D32 depth where the GPU lacks D24 — Adds the D32 fallback this PR's depth readback supports
Possibly related, for context: - PR #1033 feat(vk): fall back to D32 depth where the GPU lacks D24 — Adds the D32 fallback this PR's depth readback supports
jcabarca changed title from WIP: feat(vk): write back DEPTH24 kept as D32_SFLOAT as 24-bit unorm to feat(vk): write back DEPTH24 kept as D32_SFLOAT as 24-bit unorm 2026-11-16 05:04:46 +00:00
Merge branch 'main' into feat/vk-d24-readback
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
Website / Website on Cloudflare (pull_request) Blocked by required conditions
PR description / Description follows the template (pull_request_target) Successful in 8s
7f50b0fd21
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
Website / Website on Cloudflare (pull_request) Blocked by required conditions
PR description / Description follows the template (pull_request_target) Successful in 8s
This pull request doesn't have enough approvals yet. 0 of 1 approvals granted.
Some workflows are waiting to be reviewed.
This branch is out-of-date with the base branch
You are not authorized to merge this pull request.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u 'feat/vk-d24-readback:jcabarca-feat/vk-d24-readback'
git switch 'jcabarca-feat/vk-d24-readback'
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!1051
No description provided.