WIP: fix(vk): six Vulkan calls checked against what the device allows (blits, ASTC clears, mesh ranges, texel views, sparse binds) #1160

Draft
TrashPanda wants to merge 6 commits from TrashPanda/Longshot:fix/vk-validity into main
Contributor

Type: fix · Risk: low · Tested on: Linux, RTX 4070 Ti (game-free checks) · Needs: AMD and Intel (RADV, ANV, Windows)

Why

In six places the renderer could hand the driver a call the Vulkan spec forbids on some devices: a blit between formats the device cannot blit, a clear of a texture kept in ASTC blocks, overlapping mesh indirect ranges, a texel buffer view of an unsupported format, and sparse blocks left unbound when staging ran out or a bind failed. The spec leaves the result undefined: some drivers tolerate it, others draw garbage or lose the device.

Restored from Hookshot 2691, Hookshot 2718, Hookshot 2719, Hookshot 2741, Hookshot 3031, Hookshot 2743, by juliotec, and split out of #287 so it can be reviewed and merged on its own.

What changed

Each call is checked first and skipped or done another way when the device does not allow it: copy_t2t's blit branch checks the format features and the integer/depth rules, ASTC-kept textures are not cleared, mesh indirect argument ranges no longer overlap, texel buffer views are made only for formats the device supports, and sparse blocks are bound when staging runs out and retried when their bind failed.

Commits, each with its original author and message:

bbddf618 fix(vk): validate texture blits before vkCmdBlitImage (juliotec)

The bug

copy_t2t (gpu/vk/vk_xfer.cpp) makes a texture-to-texture copy in one
of three ways:

  1. vkCmdResolveImage: a multisampled source into a single-sampled
    destination of the same size.
  2. vkCmdCopyImage: same size, same block size, same sample count.
  3. vkCmdBlitImage: everything else, which means scaled or converting
    copies.

Branch 3 called vkCmdBlitImage without checking any of the rules the
spec puts on it. Step by step, with one example:

  1. The game copies a texture into another of a different size or a
    different format, for example an unsigned-integer texture into a
    normalized-colour one.
  2. Neither the resolve nor the copy branch applies, so the copy goes to
    vkCmdBlitImage.
    Linear is used when the game asks for it, or when the destination keeps
    its level at a smaller size than the source (d.down > s.down).
  3. When one of those rules is broken, the command is invalid usage and
    the result is undefined. Some drivers tolerate it; others may write
    garbage or lose the device.

The rules, with their exact text from the spec (validusage.json):

VUID Text
VUID-vkCmdBlitImage-srcImage-01999 The format features of srcImage
must contain VK_FORMAT_FEATURE_BLIT_SRC_BIT
VUID-vkCmdBlitImage-dstImage-02000 The format features of dstImage
must contain VK_FORMAT_FEATURE_BLIT_DST_BIT
VUID-vkCmdBlitImage-filter-02001 If filter is VK_FILTER_LINEAR, then
the format features of srcImage must contain
VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT
VUID-vkCmdBlitImage-srcImage-00229 If either of srcImage or dstImage
was created with a signed integer VkFormat, the other must also have
been created with a signed integer VkFormat
VUID-vkCmdBlitImage-srcImage-00230 If either of srcImage or dstImage
was created with an unsigned integer color VkFormat, the other must also
have been created with an unsigned integer color VkFormat
VUID-vkCmdBlitImage-srcImage-00231 If either of srcImage or dstImage
was created with a depth/stencil format and the maintenance12 feature is
not enabled the other must have exactly the same format
VUID-vkCmdBlitImage-srcImage-00233 srcImage must have been created
with a samples value of VK_SAMPLE_COUNT_1_BIT
VUID-vkCmdBlitImage-dstImage-00234 dstImage must have been created
with a samples value of VK_SAMPLE_COUNT_1_BIT

Hookshot does not enable maintenance12, so -00231 applies as written.
The images are created with VK_IMAGE_TILING_OPTIMAL, so the format
features that matter are optimalTilingFeatures.

What changed (gpu/vk/vk_xfer.cpp)

Before, branch 3 went straight to the blit:

} else {   // scaled or converting
	VkImageBlit bl{};
	...
	const bool linear = ((p.flags & NVN_COPY_FLAGS_LINEAR_FILTER_BIT) || d.down > s.down) && color;
	vkCmdBlitImage(..., linear ? VK_FILTER_LINEAR : VK_FILTER_NEAREST);
}

Now it first checks the rules above, and skips a blit that breaks any of
them:

if (!(tiling_features(s.tex->format) & VK_FORMAT_FEATURE_BLIT_SRC_BIT) ||        // -01999
	!(tiling_features(d.tex->format) & VK_FORMAT_FEATURE_BLIT_DST_BIT) ||        // -02000
	format_class(s.tex->format) != format_class(d.tex->format) ||                // -00229, -00230
	(!color && s.tex->format != d.tex->format) ||                                // -00231
	s.tex->samples != VK_SAMPLE_COUNT_1_BIT || d.tex->samples != VK_SAMPLE_COUNT_1_BIT) {   // -00233, -00234
	warn(13, "texture blit the device cannot make: skipped");
	full_barrier(cmd);
	return;
}

Linear filtering is only used when the source format supports it
(-02001), and only for float or normalized formats:

const bool linear = ((p.flags & NVN_COPY_FLAGS_LINEAR_FILTER_BIT) || d.down > s.down) && color &&
					(tiling_features(s.tex->format) & VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT) &&
					format_class(s.tex->format) == 0;

Two new helpers in the same file:

  • format_class(VkFormat) returns:
    • 1 for the unsigned-integer formats,
    • 2 for the signed-integer formats,
    • 0 for everything else (float, normalized, sRGB).
  • tiling_features(VkFormat) returns the format's
    optimalTilingFeatures:
  • For the core formats (values below 256), it asks the driver once per
    format and keeps the answer in a lock-free std::atomic<uint64_t>
    table. Bit 63 marks a format as already asked.
    • Formats from extensions (256 and above) are asked each time.
  • A scaled copy checks both sides, so the cache avoids querying the
    driver twice per copy on the replay thread.

The depth/stencil condition is already caught earlier in copy_t2t, by
warn 7 ("texture copy between unlike depth formats: skipped"), so it
never fires here. It is kept in the check so the blit's own rules stay
in one place.

warn logs each key at most 3 times.

Behaviour

  • A blit that follows the rules goes through exactly as before.
  • A blit that breaks a rule is skipped, and its destination is left as
    it was. Before, it was undefined: it may have looked right on some
    drivers, for example an integer/float mix or a multisampled image on a
    driver that tolerates it. Now the destination is stale instead.
  • This matters most on devices with a narrower format list (mobile and
    integrated GPUs, layered drivers such as MoltenVK), and for games or
    scenes that blit less common formats.

Changes after review

  • The format features come from the tiling_features cache, so they are
    not queried twice per scaled copy.
  • The first push of that change left one use of the old local variable
    in the linear-filter check. The vk_xfer tests don't compile that code;
    the full release build caught it, and it is fixed.

Test

There is no dedicated unit test for these rules. The change is reviewed
against the VUIDs above. The existing checks that compile or read
vk_xfer.cpp pass (6, including test_vulkan_copy_span_gpu_compile).

How tested

  • Release build (nx2/build.py --standalone, Windows, llvm-mingw).
  • The 6 vk_xfer.cpp checks pass.
  • Zelda OoT on Radeon RX 9070 XT (Windows, Adrenalin):
    • Two full sessions on build g54d01844.
  • One session of about 40 minutes on nightly g57471723, which includes
    this change.
    • No visible regression, no device loss.
  • "texture blit the device cannot make" does not appear in any of those
    logs. Every blit OoT makes on this device follows the rules, so the skip
    path is not reached there. This change guards against invalid usage; it
    does not fix a visible glitch in OoT.

Assisted-by: GitHub Copilot
Restored-from: https://github.com/NotRexed/Hookshot/pull/2691

244140cd fix(vk): skip clears of textures kept in ASTC blocks (juliotec)

The bug

ASTC textures are kept in one of three ways, depending on the GPU:

  • Decoded to RGBA8 on most GPUs.
  • Re-encoded as BC3 for some big textures.
  • Kept as ASTC blocks when the device samples ASTC natively
    (textureCompressionASTC_LDR, astc_native()). The image then has an
    ASTC VkFormat.

clear_tex (gpu/vk/vk_xfer.cpp) clears a texture in one of two ways:

  1. Whole level: when the clear covers the whole level, the image is
    not 3D, and the format is not BC (raw), it uses vkCmdClearColorImage
    for colour, or vkCmdClearDepthStencilImage.
  2. Region: otherwise, a render pass over that level and layer with
    vkCmdClearAttachments. For BC images (raw) the rectangle is
    converted to blocks.

raw is computed only for the BC range, so an image kept in ASTC blocks
was treated as uncompressed. Step by step:

  1. On a device with native ASTC, the game clears an ASTC texture.
  2. If the clear covers the whole level, clear_tex calls
    vkCmdClearColorImage on the ASTC image. This breaks
    VUID-vkCmdClearColorImage-image-00007: "image must not have a
    compressed or depth/stencil format".
  3. If it covers part of the level, the region path below only converts
    the rectangle to blocks for BC formats, not for ASTC.
  4. Either way, a colour written over ASTC blocks would be garbage, since
    the blocks are compressed data, not texels.

What changed (gpu/vk/vk_xfer.cpp, clear_tex)

Before, no ASTC check:

full_barrier(cmd);
const bool volume = s.tex->type == VK_IMAGE_TYPE_3D;
const bool raw = s.tex->format >= VK_FORMAT_BC1_RGB_UNORM_BLOCK && s.tex->format <= VK_FORMAT_BC7_SRGB_BLOCK;

After:

full_barrier(cmd);
if (s.tex->format >= VK_FORMAT_ASTC_4x4_UNORM_BLOCK && s.tex->format <= VK_FORMAT_ASTC_12x12_SRGB_BLOCK) {
	warn(14, "clear of an ASTC texture: skipped");
	return;
}
const bool volume = s.tex->type == VK_IMAGE_TYPE_3D;

A clear of an image whose format is ASTC is skipped, and the image is
left as it was. warn logs it at most 3 times.

The early return also skips texture_written at the end of clear_tex,
so the texture is not marked as GPU-written. That is on purpose, because
nothing was written to it.

ASTC textures decoded to RGBA8, ASTC kept as BC3, and every other format
are cleared exactly as before.

Who reaches this

Only devices that expose textureCompressionASTC_LDR and sample ASTC
natively, such as Intel iGPUs. AMD and NVIDIA desktop drivers don't
expose it, so on them the image is never in an ASTC format and the new
check never matches.

Changes after review

  • The description no longer claims that drivers hang. The rule comes
    from the spec (the VUID above).
  • Skipping texture_written was confirmed as intended.

Test

There is no dedicated unit test. In the review run,
test_bc_raw_targets.py and test_vulkan_clear_mip.py pass with this
change.

How tested

  • Release build.
  • Zelda OoT on Radeon RX 9070 XT (Windows, Adrenalin), including about
    40 minutes on nightly g57471723, which includes this change. Log clean,
    and "clear of an ASTC texture" does not appear.
  • This GPU has no native ASTC, so the new path was not run. The test
    only checks that a GPU without native ASTC is unaffected.

Assisted-by: GitHub Copilot
Restored-from: https://github.com/NotRexed/Hookshot/pull/2718

1987fad5 fix(vk): keep mesh indirect argument ranges from overlapping (juliotec)

The bug

mesh_args_take(n) (gpu/vk/vk_draw.cpp) hands out n consecutive
16-byte entries of the mesh-argument ring (kMeshArgs entries). Each
indirect mesh draw gets its own range: the GPU copies the draw's counts
and firsts into it, and the draw reads them from there. The code was:

const uint32_t at = next.fetch_add(n) % (kMeshArgs - n);
return at + 1;

The modulus depends on n, so two draws taken one after another with
different counts can land on the same entries. A worked example with the
old kMeshArgs = 262144:

  1. The counter is at 262130, and a draw takes n = 100. The modulus is
    262144 - 100 = 262044, so at = 262130 % 262044 = 86. The draw gets
    entries 87..186.
  2. The counter is now 262230, and the next draw takes n = 1. The
    modulus is 262143, so at = 262230 % 262143 = 87. The draw gets entry
    88.
  3. Entry 88 is inside the first draw's range. The second draw is a
    direct draw with a first task, so it writes its first into entry 88 from
    the CPU while recording (mesh_args_words[at * 4 + 3] = first). The
    first draw's GPU copy, which runs later, writes its own count and first
    over entry 88. The second draw then reads the first draw's values
    instead of its own. Two indirect draws that overlap overwrite each other
    in the same way, through their GPU copies.
  4. On screen, this shows as wrong, flickering or missing mesh geometry.

Who calls mesh_args_take:

  • Without RX_VK_MESH_ARGS (the default): only direct mesh draws
    with a non-zero first task, always with n = 1. With a constant n,
    the modulus is constant and nothing overlaps.
  • With RX_VK_MESH_ARGS=1: the rewritten indirect draws also call
    it, with n = d.max (from 1 up to the old kMeshArgs - 1). They mix
    with the n = 1 calls, and that mix is what overlaps.

What changed (gpu/vk/vk_draw.cpp)

The modulus is now fixed at kMeshArgs / 2, and n is clamped to at
most kMeshArgs / 2:

// before
const uint32_t at = next.fetch_add(n) % (kMeshArgs - n);
// after
n = std::clamp<uint32_t>(n, 1, kMeshArgs / 2);
const uint32_t at = next.fetch_add(n) % (kMeshArgs / 2);
  • Every range starts in the first half of the ring and is at most half a
    ring long, so it never runs past the end.
  • With one modulus for every n, ranges handed out one after another
    follow each other in the ring. An entry is only reused when the counter
    has advanced by a whole modulus.
  • The indirect caller clamps n the same way: std::clamp(d.max, 1, (int)(kMeshArgs / 2)) instead of kMeshArgs - 1.
    That keeps the reuse distance at 262144 entries, as before; halving the
    modulus alone would have halved it.
  • A power-of-two modulus also stays continuous when the 32-bit counter
    wraps, which the old one did not.

Cost

  • The ring buffer is host-visible and grows from 4 MB to 8 MB. It is
    also created for direct mesh draws with a non-zero first task, flag or
    not, so the extra 4 MB applies to everyone who reaches that path.
  • The RX_VK_LOG_MESH_PERPROG diagnostic prog_at vector (kMeshArgs
    entries) doubles too.

Test

tests/mesh_args_cleanup_test.cpp checked that the ring allocation was
at most 4 MB, which the new size breaks. It now requires the allocation
to be exactly kMeshArgs * 16 bytes, computed from the kMeshArgs the
test extracts from vk_draw.cpp, so it follows the real size instead of a
fixed bound. tests/test_mesh_args_cleanup.py passes its 5 cases.

Changes after review

  • The test fixture's 4 MB bound was replaced by the size computed from
    kMeshArgs.
  • The description now covers the extra 4 MB on the direct-draw path and
    the doubled prog_at vector.

How tested

  • Release build.
  • tests/test_mesh_args_cleanup.py: 5 cases pass.
  • Zelda OoT on Radeon RX 9070 XT (Windows, Adrenalin):
  • With the flag off (the default; the n = 1 direct-draw path),
    including about 40 minutes on nightly g57471723, which includes this
    change. Log clean.
  • With RX_VK_MESH_ARGS=1 (the rewritten indirect draws, mixed counts).

Assisted-by: GitHub Copilot
Restored-from: https://github.com/NotRexed/Hookshot/pull/2719

9b72521c fix(vk): skip texel buffer views of formats the device cannot use (juliotec)

The bug

texel_buffer_view (gpu/vk/vk_texture.cpp) creates the VkBufferView
for a texture the game binds as a texel buffer:

  • as a uniform texel buffer when it is sampled,
  • as a storage texel buffer when it is written.

The view's format is the one the texture maps to
(vk_format(nf).format). The only check was that the format is not
VK_FORMAT_UNDEFINED. Nothing checked whether the device supports texel
buffers of that format. Step by step:

  1. The game binds a texture as a texel buffer, in a format such as
    VK_FORMAT_R32G32B32_SFLOAT.
  2. The device does not list VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT
    (or STORAGE_TEXEL_BUFFER_BIT) for it in the format's bufferFeatures.
    Which formats are listed varies by driver.
  3. texel_buffer_view creates the view anyway. This is invalid usage:
VUID Text
VUID-VkBufferViewCreateInfo-format-08778 If the buffer view usage
contains VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT, then format features
of format must contain VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT
VUID-VkBufferViewCreateInfo-format-08779 If the buffer view usage
contains VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT, then format features
of format must contain VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BIT
  1. What the shader then reads or writes through that view is undefined.

What changed (gpu/vk/vk_texture.cpp, texel_buffer_view)

A check right after the format is known, before anything is created,
looked up, or marked as written:

VkFormat f = vk_format(nf).format;
if (f == VK_FORMAT_UNDEFINED) return VK_NULL_HANDLE;
// new:
if (!(format_props(f).bufferFeatures & (storage ? VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BIT
												: VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT))) {
	static std::atomic<int> logged{0};
	if (logged.fetch_add(1, std::memory_order_relaxed) < 8)
		logf("vk: texel buffer of format %d (%s) not supported by the device: unbound", (int)f, storage ? "storage" : "uniform");
	return VK_NULL_HANDLE;
}
  • A format without the needed feature gets no view, and the slot stays
    unbound. Callers already handle a null view; it is the same result as
    the existing VK_FORMAT_UNDEFINED case.
  • Because it returns before texture_gpu_wrote, a storage bind that is
    refused does not mark the texture as written by the GPU.
  • The answer comes from the existing format_props cache, which takes
    one short lock (fmt_mu) per texel-buffer bind but does not query the
    driver again.
  • The message is logged at most 8 times.
  • Supported formats follow the same path as before.

Test

tests/test_texel_buffer_ownership.py cuts texel_buffer_view out of
vk_texture.cpp and compiles it against the stubs in
tests/texel_buffer_ownership_test.cpp:

  • The fixture gets a format_props stub. It reports both texel-buffer
    features for every format except the one mapped from NVN format 44
    (VK_FORMAT_R32G32B32_SFLOAT).
  • A new case, unsupported, binds format 44 as uniform and as storage.
    It checks that:
    • neither returns a view;
    • no view is created (creates == 0);
    • no buffer is looked up (lookups == 0);
    • the texture is not marked as written (writes == 0).
  • All 24 cases pass. On main, the case list has 23.

Changes after review

  • The first version did not add the stub, so the test failed to compile
    ("'format_props' was not declared in this scope"). The stub and the
    unsupported case were added.

How tested

  • Release build (nx2/build.py --standalone, Windows, llvm-mingw).
  • tests/test_texel_buffer_ownership.py: 24 cases pass.
  • Zelda OoT on Radeon RX 9070 XT (Windows, Adrenalin):
    • Two full sessions on build g54d01844.
  • One session of about 40 minutes on nightly g57471723, which includes
    this change.
    • No regression.
  • "texel buffer of format" does not appear in any of those logs. Every
    texel-buffer format OoT uses is supported on this device, so the new
    path is not reached there. This change guards against invalid usage; it
    does not fix a visible glitch in OoT.

Assisted-by: GitHub Copilot
Restored-from: https://github.com/NotRexed/Hookshot/pull/2741

83a60d35 fix(vk): bind a sparse texture's queued blocks when its upload runs out of staging (juliotec)

The bug

upload_inner (gpu/vk/vk_texture.cpp) uploads a texture in runs of
rows. For a sparse texture, each run first queues the binds of the tiles
it touches with texture_resident_queue: the tiles are marked bound at
once, and the binds go into sparse_binds, one list shared by every
texture. texture_resident_flush later binds the whole list with
vkQueueBindSparse, into one image only: VkSparseImageMemoryBindInfo
takes a single image for the list.

Each run takes its staging memory with staging(). When that failed
part-way, the code was:

if (!st.buffer) return false;

so it returned with the binds of the earlier rows still in
sparse_binds. Step by step:

  1. Texture A (sparse) uploads. Rows 0..N queue the binds of their tiles;
    those tiles are marked bound.
  2. The staging for row N+1 fails, and upload_inner returns false. A's
    binds are still in sparse_binds and were never made.
  3. Texture B (sparse) uploads. Its texture_resident_flush binds the
    whole list into B's image, including A's binds. The memory meant for
    A's tiles goes to the same coordinates of B's image.
  4. A's tiles stay marked bound, so no later write queues them again. A's
    later copies into those tiles land in unbacked memory, and B gets memory
    it did not ask for.

The other exits of that loop (a new staging arena, the end of the
upload) already call texture_resident_flush(&tex) first. Only the
staging-failure exit did not.

What changed

Only that exit, in upload_inner:

if (!st.buffer) {
	texture_resident_flush(&tex);
	return false;
}

The binds the earlier rows queued are now made into A's own image before
giving up, as the other exits do. The success path is unchanged.

A texture is only sparse when it is a 2D array over RX_VK_TEX_MAX_MB
(1.5 GB) on a device with sparse support, which is MKW's course-map
case.

Test

tests/test_sparse_staging_failure.py is a source check on
upload_inner. In the part of the loop after the first staging() call
and before texture_resident_queue, every return false; must have a
texture_resident_flush(&tex); in the same block. The old if (!st.buffer) return false; must be gone. On main it fails with "a
staging failure returns without binding the sparse blocks queued before
it"; with the fix it passes.

How tested

  • The new test fails on main and passes with the fix.
  • The tests that reference vk_texture.cpp pass.
  • Release build OK.
  • Zelda OoT on Radeon RX 9070 XT (Windows, Adrenalin), nightly with this
    change, about 40 minutes, log clean. This checks that non-sparse uploads
    are unaffected; the sparse path itself is not reached there.

Assisted-by: GitHub Copilot
Restored-from: https://github.com/NotRexed/Hookshot/pull/3031

c9c28c5c fix(vk): retry sparse blocks whose bind failed (juliotec)

The bug

A sparse texture gets device memory per block (tile) as it is written,
instead of all at once (gpu/vk/vk_texture.cpp):

  • sparse_queue walks the tiles a write reaches. For each tile that has
    no memory yet, it takes memory with sparse_take, appends a bind to
    sparse_binds, and marks the tile bound at once (bound = 1). The
    mip tail works the same way, with sparse_opaque and tail_bound.
  • sparse_flush then binds the whole list with vkQueueBindSparse and
    waits on a fence.

When the bind failed, sparse_flush only logged it:

res = vkQueueBindSparse(dev.queue, 1, &bi, fence);
...
if (res == VK_SUCCESS) {
	vkWaitForFences(...); vkResetFences(...);
} else {
	logf("vk: sparse texture %#llx: binding failed (%d)", ...);
}
...
sparse_binds.clear(); sparse_opaque.clear();
return res == VK_SUCCESS;

Step by step:

  1. A write to a sparse texture queues the binds of tiles A, B and C.
    Their tiles[...] entries are set to 1.
  2. vkQueueBindSparse fails (for example, out of memory). The list is
    cleared, but the tiles stay marked bound.
  3. The upload's copies go ahead and write tiles A, B and C, which have
    no memory behind them.
  4. Every later write to those tiles sees them marked bound, so it never
    queues them again. Those tiles stay unbacked for the life of the
    texture, and every write to them is lost.

Two more problems were in the same function:

  • The fence was created without checking. If vkCreateFence failed,
    every bind was submitted and waited on with a null fence.
    vkWaitForFences requires valid handles
    (VUID-vkWaitForFences-pFences-parameter: "pFences must be a valid
    pointer to an array of fenceCount valid VkFence handles").
  • The memory sparse_take gave for the failed binds was simply lost to
    that texture.

What changed (gpu/vk/vk_texture.cpp and vk_texture.h)

  • New sparse_unqueue(tex). When the binds are not made, it:
  • marks every queued tile unbound again (map[i] = 0), finding the tile
    with the same math sparse_queue uses;
    • marks every queued mip tail unbound again (tail_bound[layer] = 0);
    • puts the memory those binds had taken on the texture's free list;
    • clears the queue, and counts sparse_added as sparse_flush does.

The next write to those tiles queues them again, so the bind is retried.

  • sparse_flush calls it in both failure cases, and returns false:

    if (vkCreateFence(dev.device, &fi, nullptr, &fence) != VK_SUCCESS) {
        fence = VK_NULL_HANDLE;
        static int logged;
    

if (logged++ < 8) logf("vk: sparse texture %#llx: no fence for its
binds", ...);
sparse_unqueue(tex);
return false;
}
...
} else {
static int failed;
if (failed++ < 8) logf("vk: sparse texture %#llx: binding failed (%d)",
...);
sparse_unqueue(tex);
return false;
}


- **New per-texture free list** (`Texture::sparse_free`, with memory,
offset and size). `sparse_take` gives it out before taking new chunk
memory. A bind that keeps failing reuses the same memory instead of
taking new memory on every retry. The list only points at the texture's
own chunks, which are freed with the texture.

- **Both messages are capped at 8.** A failing bind is now retried on
later writes, so without the cap it would log on every write to that
texture.

The success path is unchanged.

### Who reaches this

A texture is only sparse when it is a 2D array larger than
`RX_VK_TEX_MAX_MB` (1.5 GB) on a device with sparse support. That is
MKW's course-map case. OoT likely never makes one.

### Changes after review

- The "binding failed" and "no fence for its binds" messages are capped
at 8, like the other sparse messages.
- The description now says when a texture is sparse, and that the OoT
test does not reach this path.

### Test

There is no dedicated unit test. The failure needs `vkQueueBindSparse`
or `vkCreateFence` to fail on a sparse texture.

### How tested

- Release build.
- Zelda OoT on Radeon RX 9070 XT (Windows, Adrenalin), including about
40 minutes on nightly g57471723, which includes this change. Log clean,
with no "sparse texture" line.
- The sparse path itself was not run. The test only shows that
non-sparse textures are unaffected.

Assisted-by: GitHub Copilot
Restored-from: https://github.com/NotRexed/Hookshot/pull/2743

</details>

## Measurements

**Verdict:** nothing to measure: a correctness fix off the frame path, covered by game-free checks.

### Flags and settings

None.

## Testing

**Tested:** On Linux (kernel 7.0), RTX 4070 Ti, `main` @ 71b1edd8, this PR @ c9c28c5c: `the checks that read the changed files (`tests/run_all.py --changed origin/main`)` pass. The full suite (`tests/run_all.py`) has not been run on this branch yet; a comment will follow when it has.

**Not tested:** The game on a GPU where these calls were invalid. Opened as work in progress until it runs in the game.

**Must be tested:**
- AMD on Linux (Test Farm: @Beanstalk radv): Kokiri Forest and Hyrule Field for 5 minutes, expecting no device lost and no validation errors with `VK_LAYER_KHRONOS_validation`
- Intel on Windows (Test Farm: @Beanstalk windows, an Intel GPU): the same

## Risks

**What could break:** texture copies, clears and sparse textures where a check is wrong.

**Turning it off:** revert the commit.

**Compatibility:** Nothing changes.

## 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).
- [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] 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.
- [ ] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named).

### When it applies

- [x] A game-free test added for the fix, failing on `main` and passing here.
**Type:** fix · **Risk:** low · **Tested on:** Linux, RTX 4070 Ti (game-free checks) · **Needs:** AMD and Intel (RADV, ANV, Windows) ## Why In six places the renderer could hand the driver a call the Vulkan spec forbids on some devices: a blit between formats the device cannot blit, a clear of a texture kept in ASTC blocks, overlapping mesh indirect ranges, a texel buffer view of an unsupported format, and sparse blocks left unbound when staging ran out or a bind failed. The spec leaves the result undefined: some drivers tolerate it, others draw garbage or lose the device. Restored from [Hookshot 2691](https://github.com/NotRexed/Hookshot/pull/2691), [Hookshot 2718](https://github.com/NotRexed/Hookshot/pull/2718), [Hookshot 2719](https://github.com/NotRexed/Hookshot/pull/2719), [Hookshot 2741](https://github.com/NotRexed/Hookshot/pull/2741), [Hookshot 3031](https://github.com/NotRexed/Hookshot/pull/3031), [Hookshot 2743](https://github.com/NotRexed/Hookshot/pull/2743), by juliotec, and split out of [#287](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/287) so it can be reviewed and merged on its own. ## What changed Each call is checked first and skipped or done another way when the device does not allow it: `copy_t2t`'s blit branch checks the format features and the integer/depth rules, ASTC-kept textures are not cleared, mesh indirect argument ranges no longer overlap, texel buffer views are made only for formats the device supports, and sparse blocks are bound when staging runs out and retried when their bind failed. Commits, each with its original author and message: <details><summary><code>bbddf618</code> fix(vk): validate texture blits before vkCmdBlitImage (juliotec)</summary> ### The bug `copy_t2t` (gpu/vk/vk_xfer.cpp) makes a texture-to-texture copy in one of three ways: 1. `vkCmdResolveImage`: a multisampled source into a single-sampled destination of the same size. 2. `vkCmdCopyImage`: same size, same block size, same sample count. 3. `vkCmdBlitImage`: everything else, which means scaled or converting copies. Branch 3 called `vkCmdBlitImage` without checking any of the rules the spec puts on it. Step by step, with one example: 1. The game copies a texture into another of a different size or a different format, for example an unsigned-integer texture into a normalized-colour one. 2. Neither the resolve nor the copy branch applies, so the copy goes to `vkCmdBlitImage`. Linear is used when the game asks for it, or when the destination keeps its level at a smaller size than the source (`d.down > s.down`). 4. When one of those rules is broken, the command is invalid usage and the result is undefined. Some drivers tolerate it; others may write garbage or lose the device. The rules, with their exact text from the spec (`validusage.json`): | VUID | Text | |---|---| | VUID-vkCmdBlitImage-srcImage-01999 | The format features of srcImage must contain VK_FORMAT_FEATURE_BLIT_SRC_BIT | | VUID-vkCmdBlitImage-dstImage-02000 | The format features of dstImage must contain VK_FORMAT_FEATURE_BLIT_DST_BIT | | VUID-vkCmdBlitImage-filter-02001 | If filter is VK_FILTER_LINEAR, then the format features of srcImage must contain VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT | | VUID-vkCmdBlitImage-srcImage-00229 | If either of srcImage or dstImage was created with a signed integer VkFormat, the other must also have been created with a signed integer VkFormat | | VUID-vkCmdBlitImage-srcImage-00230 | If either of srcImage or dstImage was created with an unsigned integer color VkFormat, the other must also have been created with an unsigned integer color VkFormat | | VUID-vkCmdBlitImage-srcImage-00231 | If either of srcImage or dstImage was created with a depth/stencil format and the maintenance12 feature is not enabled the other must have exactly the same format | | VUID-vkCmdBlitImage-srcImage-00233 | srcImage must have been created with a samples value of VK_SAMPLE_COUNT_1_BIT | | VUID-vkCmdBlitImage-dstImage-00234 | dstImage must have been created with a samples value of VK_SAMPLE_COUNT_1_BIT | Hookshot does not enable maintenance12, so -00231 applies as written. The images are created with `VK_IMAGE_TILING_OPTIMAL`, so the format features that matter are `optimalTilingFeatures`. ### What changed (gpu/vk/vk_xfer.cpp) Before, branch 3 went straight to the blit: ```cpp } else { // scaled or converting VkImageBlit bl{}; ... const bool linear = ((p.flags & NVN_COPY_FLAGS_LINEAR_FILTER_BIT) || d.down > s.down) && color; vkCmdBlitImage(..., linear ? VK_FILTER_LINEAR : VK_FILTER_NEAREST); } ``` Now it first checks the rules above, and skips a blit that breaks any of them: ```cpp if (!(tiling_features(s.tex->format) & VK_FORMAT_FEATURE_BLIT_SRC_BIT) || // -01999 !(tiling_features(d.tex->format) & VK_FORMAT_FEATURE_BLIT_DST_BIT) || // -02000 format_class(s.tex->format) != format_class(d.tex->format) || // -00229, -00230 (!color && s.tex->format != d.tex->format) || // -00231 s.tex->samples != VK_SAMPLE_COUNT_1_BIT || d.tex->samples != VK_SAMPLE_COUNT_1_BIT) { // -00233, -00234 warn(13, "texture blit the device cannot make: skipped"); full_barrier(cmd); return; } ``` Linear filtering is only used when the source format supports it (-02001), and only for float or normalized formats: ```cpp const bool linear = ((p.flags & NVN_COPY_FLAGS_LINEAR_FILTER_BIT) || d.down > s.down) && color && (tiling_features(s.tex->format) & VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT) && format_class(s.tex->format) == 0; ``` Two new helpers in the same file: - `format_class(VkFormat)` returns: - 1 for the unsigned-integer formats, - 2 for the signed-integer formats, - 0 for everything else (float, normalized, sRGB). - `tiling_features(VkFormat)` returns the format's `optimalTilingFeatures`: - For the core formats (values below 256), it asks the driver once per format and keeps the answer in a lock-free `std::atomic<uint64_t>` table. Bit 63 marks a format as already asked. - Formats from extensions (256 and above) are asked each time. - A scaled copy checks both sides, so the cache avoids querying the driver twice per copy on the replay thread. The depth/stencil condition is already caught earlier in `copy_t2t`, by warn 7 ("texture copy between unlike depth formats: skipped"), so it never fires here. It is kept in the check so the blit's own rules stay in one place. `warn` logs each key at most 3 times. ### Behaviour - A blit that follows the rules goes through exactly as before. - A blit that breaks a rule is skipped, and its destination is left as it was. Before, it was undefined: it may have looked right on some drivers, for example an integer/float mix or a multisampled image on a driver that tolerates it. Now the destination is stale instead. - This matters most on devices with a narrower format list (mobile and integrated GPUs, layered drivers such as MoltenVK), and for games or scenes that blit less common formats. ### Changes after review - The format features come from the `tiling_features` cache, so they are not queried twice per scaled copy. - The first push of that change left one use of the old local variable in the linear-filter check. The vk_xfer tests don't compile that code; the full release build caught it, and it is fixed. ### Test There is no dedicated unit test for these rules. The change is reviewed against the VUIDs above. The existing checks that compile or read vk_xfer.cpp pass (6, including `test_vulkan_copy_span_gpu_compile`). ### How tested - Release build (`nx2/build.py --standalone`, Windows, llvm-mingw). - The 6 vk_xfer.cpp checks pass. - Zelda OoT on Radeon RX 9070 XT (Windows, Adrenalin): - Two full sessions on build g54d01844. - One session of about 40 minutes on nightly g57471723, which includes this change. - No visible regression, no device loss. - "texture blit the device cannot make" does not appear in any of those logs. Every blit OoT makes on this device follows the rules, so the skip path is not reached there. This change guards against invalid usage; it does not fix a visible glitch in OoT. Assisted-by: GitHub Copilot Restored-from: https://github.com/NotRexed/Hookshot/pull/2691 </details> <details><summary><code>244140cd</code> fix(vk): skip clears of textures kept in ASTC blocks (juliotec)</summary> ### The bug ASTC textures are kept in one of three ways, depending on the GPU: - **Decoded to RGBA8** on most GPUs. - **Re-encoded as BC3** for some big textures. - **Kept as ASTC blocks** when the device samples ASTC natively (`textureCompressionASTC_LDR`, `astc_native()`). The image then has an ASTC `VkFormat`. `clear_tex` (gpu/vk/vk_xfer.cpp) clears a texture in one of two ways: 1. **Whole level**: when the clear covers the whole level, the image is not 3D, and the format is not BC (`raw`), it uses `vkCmdClearColorImage` for colour, or `vkCmdClearDepthStencilImage`. 2. **Region**: otherwise, a render pass over that level and layer with `vkCmdClearAttachments`. For BC images (`raw`) the rectangle is converted to blocks. `raw` is computed only for the BC range, so an image kept in ASTC blocks was treated as uncompressed. Step by step: 1. On a device with native ASTC, the game clears an ASTC texture. 2. If the clear covers the whole level, `clear_tex` calls `vkCmdClearColorImage` on the ASTC image. This breaks **VUID-vkCmdClearColorImage-image-00007**: "image must not have a compressed or depth/stencil format". 3. If it covers part of the level, the region path below only converts the rectangle to blocks for BC formats, not for ASTC. 4. Either way, a colour written over ASTC blocks would be garbage, since the blocks are compressed data, not texels. ### What changed (gpu/vk/vk_xfer.cpp, clear_tex) Before, no ASTC check: ```cpp full_barrier(cmd); const bool volume = s.tex->type == VK_IMAGE_TYPE_3D; const bool raw = s.tex->format >= VK_FORMAT_BC1_RGB_UNORM_BLOCK && s.tex->format <= VK_FORMAT_BC7_SRGB_BLOCK; ``` After: ```cpp full_barrier(cmd); if (s.tex->format >= VK_FORMAT_ASTC_4x4_UNORM_BLOCK && s.tex->format <= VK_FORMAT_ASTC_12x12_SRGB_BLOCK) { warn(14, "clear of an ASTC texture: skipped"); return; } const bool volume = s.tex->type == VK_IMAGE_TYPE_3D; ``` A clear of an image whose format is ASTC is skipped, and the image is left as it was. `warn` logs it at most 3 times. The early return also skips `texture_written` at the end of `clear_tex`, so the texture is not marked as GPU-written. That is on purpose, because nothing was written to it. ASTC textures decoded to RGBA8, ASTC kept as BC3, and every other format are cleared exactly as before. ### Who reaches this Only devices that expose `textureCompressionASTC_LDR` and sample ASTC natively, such as Intel iGPUs. AMD and NVIDIA desktop drivers don't expose it, so on them the image is never in an ASTC format and the new check never matches. ### Changes after review - The description no longer claims that drivers hang. The rule comes from the spec (the VUID above). - Skipping `texture_written` was confirmed as intended. ### Test There is no dedicated unit test. In the review run, `test_bc_raw_targets.py` and `test_vulkan_clear_mip.py` pass with this change. ### How tested - Release build. - Zelda OoT on Radeon RX 9070 XT (Windows, Adrenalin), including about 40 minutes on nightly g57471723, which includes this change. Log clean, and "clear of an ASTC texture" does not appear. - This GPU has no native ASTC, so the new path was not run. The test only checks that a GPU without native ASTC is unaffected. Assisted-by: GitHub Copilot Restored-from: https://github.com/NotRexed/Hookshot/pull/2718 </details> <details><summary><code>1987fad5</code> fix(vk): keep mesh indirect argument ranges from overlapping (juliotec)</summary> ### The bug `mesh_args_take(n)` (gpu/vk/vk_draw.cpp) hands out `n` consecutive 16-byte entries of the mesh-argument ring (`kMeshArgs` entries). Each indirect mesh draw gets its own range: the GPU copies the draw's counts and firsts into it, and the draw reads them from there. The code was: ```cpp const uint32_t at = next.fetch_add(n) % (kMeshArgs - n); return at + 1; ``` The modulus depends on `n`, so two draws taken one after another with different counts can land on the same entries. A worked example with the old `kMeshArgs = 262144`: 1. The counter is at 262130, and a draw takes `n = 100`. The modulus is 262144 - 100 = 262044, so `at = 262130 % 262044 = 86`. The draw gets entries **87..186**. 2. The counter is now 262230, and the next draw takes `n = 1`. The modulus is 262143, so `at = 262230 % 262143 = 87`. The draw gets entry **88**. 3. Entry 88 is inside the first draw's range. The second draw is a direct draw with a first task, so it writes its first into entry 88 from the CPU while recording (`mesh_args_words[at * 4 + 3] = first`). The first draw's GPU copy, which runs later, writes its own count and first over entry 88. The second draw then reads the first draw's values instead of its own. Two indirect draws that overlap overwrite each other in the same way, through their GPU copies. 4. On screen, this shows as wrong, flickering or missing mesh geometry. Who calls `mesh_args_take`: - **Without `RX_VK_MESH_ARGS` (the default):** only direct mesh draws with a non-zero first task, always with `n = 1`. With a constant `n`, the modulus is constant and nothing overlaps. - **With `RX_VK_MESH_ARGS=1`:** the rewritten indirect draws also call it, with `n = d.max` (from 1 up to the old `kMeshArgs - 1`). They mix with the `n = 1` calls, and that mix is what overlaps. ### What changed (gpu/vk/vk_draw.cpp) The modulus is now fixed at `kMeshArgs / 2`, and `n` is clamped to at most `kMeshArgs / 2`: ```cpp // before const uint32_t at = next.fetch_add(n) % (kMeshArgs - n); // after n = std::clamp<uint32_t>(n, 1, kMeshArgs / 2); const uint32_t at = next.fetch_add(n) % (kMeshArgs / 2); ``` - Every range starts in the first half of the ring and is at most half a ring long, so it never runs past the end. - With one modulus for every `n`, ranges handed out one after another follow each other in the ring. An entry is only reused when the counter has advanced by a whole modulus. - The indirect caller clamps `n` the same way: `std::clamp(d.max, 1, (int)(kMeshArgs / 2))` instead of `kMeshArgs - 1`. That keeps the reuse distance at 262144 entries, as before; halving the modulus alone would have halved it. - A power-of-two modulus also stays continuous when the 32-bit counter wraps, which the old one did not. ### Cost - The ring buffer is host-visible and grows from 4 MB to 8 MB. It is also created for direct mesh draws with a non-zero first task, flag or not, so the extra 4 MB applies to everyone who reaches that path. - The `RX_VK_LOG_MESH_PERPROG` diagnostic `prog_at` vector (`kMeshArgs` entries) doubles too. ### Test `tests/mesh_args_cleanup_test.cpp` checked that the ring allocation was at most 4 MB, which the new size breaks. It now requires the allocation to be exactly `kMeshArgs * 16` bytes, computed from the `kMeshArgs` the test extracts from vk_draw.cpp, so it follows the real size instead of a fixed bound. `tests/test_mesh_args_cleanup.py` passes its 5 cases. ### Changes after review - The test fixture's 4 MB bound was replaced by the size computed from `kMeshArgs`. - The description now covers the extra 4 MB on the direct-draw path and the doubled `prog_at` vector. ### How tested - Release build. - `tests/test_mesh_args_cleanup.py`: 5 cases pass. - Zelda OoT on Radeon RX 9070 XT (Windows, Adrenalin): - With the flag off (the default; the `n = 1` direct-draw path), including about 40 minutes on nightly g57471723, which includes this change. Log clean. - With `RX_VK_MESH_ARGS=1` (the rewritten indirect draws, mixed counts). Assisted-by: GitHub Copilot Restored-from: https://github.com/NotRexed/Hookshot/pull/2719 </details> <details><summary><code>9b72521c</code> fix(vk): skip texel buffer views of formats the device cannot use (juliotec)</summary> ### The bug `texel_buffer_view` (gpu/vk/vk_texture.cpp) creates the `VkBufferView` for a texture the game binds as a texel buffer: - as a **uniform** texel buffer when it is sampled, - as a **storage** texel buffer when it is written. The view's format is the one the texture maps to (`vk_format(nf).format`). The only check was that the format is not `VK_FORMAT_UNDEFINED`. Nothing checked whether the device supports texel buffers of that format. Step by step: 1. The game binds a texture as a texel buffer, in a format such as `VK_FORMAT_R32G32B32_SFLOAT`. 2. The device does not list `VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT` (or `STORAGE_TEXEL_BUFFER_BIT`) for it in the format's `bufferFeatures`. Which formats are listed varies by driver. 3. `texel_buffer_view` creates the view anyway. This is invalid usage: | VUID | Text | |---|---| | VUID-VkBufferViewCreateInfo-format-08778 | If the buffer view usage contains VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT, then format features of format must contain VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT | | VUID-VkBufferViewCreateInfo-format-08779 | If the buffer view usage contains VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT, then format features of format must contain VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BIT | 4. What the shader then reads or writes through that view is undefined. ### What changed (gpu/vk/vk_texture.cpp, texel_buffer_view) A check right after the format is known, before anything is created, looked up, or marked as written: ```cpp VkFormat f = vk_format(nf).format; if (f == VK_FORMAT_UNDEFINED) return VK_NULL_HANDLE; // new: if (!(format_props(f).bufferFeatures & (storage ? VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BIT : VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT))) { static std::atomic<int> logged{0}; if (logged.fetch_add(1, std::memory_order_relaxed) < 8) logf("vk: texel buffer of format %d (%s) not supported by the device: unbound", (int)f, storage ? "storage" : "uniform"); return VK_NULL_HANDLE; } ``` - A format without the needed feature gets no view, and the slot stays unbound. Callers already handle a null view; it is the same result as the existing `VK_FORMAT_UNDEFINED` case. - Because it returns before `texture_gpu_wrote`, a storage bind that is refused does not mark the texture as written by the GPU. - The answer comes from the existing `format_props` cache, which takes one short lock (`fmt_mu`) per texel-buffer bind but does not query the driver again. - The message is logged at most 8 times. - Supported formats follow the same path as before. ### Test `tests/test_texel_buffer_ownership.py` cuts `texel_buffer_view` out of vk_texture.cpp and compiles it against the stubs in `tests/texel_buffer_ownership_test.cpp`: - The fixture gets a `format_props` stub. It reports both texel-buffer features for every format except the one mapped from NVN format 44 (`VK_FORMAT_R32G32B32_SFLOAT`). - A new case, `unsupported`, binds format 44 as uniform and as storage. It checks that: - neither returns a view; - no view is created (`creates == 0`); - no buffer is looked up (`lookups == 0`); - the texture is not marked as written (`writes == 0`). - All 24 cases pass. On main, the case list has 23. ### Changes after review - The first version did not add the stub, so the test failed to compile ("'format_props' was not declared in this scope"). The stub and the `unsupported` case were added. ### How tested - Release build (`nx2/build.py --standalone`, Windows, llvm-mingw). - `tests/test_texel_buffer_ownership.py`: 24 cases pass. - Zelda OoT on Radeon RX 9070 XT (Windows, Adrenalin): - Two full sessions on build g54d01844. - One session of about 40 minutes on nightly g57471723, which includes this change. - No regression. - "texel buffer of format" does not appear in any of those logs. Every texel-buffer format OoT uses is supported on this device, so the new path is not reached there. This change guards against invalid usage; it does not fix a visible glitch in OoT. Assisted-by: GitHub Copilot Restored-from: https://github.com/NotRexed/Hookshot/pull/2741 </details> <details><summary><code>83a60d35</code> fix(vk): bind a sparse texture's queued blocks when its upload runs out of staging (juliotec)</summary> ### The bug `upload_inner` (gpu/vk/vk_texture.cpp) uploads a texture in runs of rows. For a sparse texture, each run first queues the binds of the tiles it touches with `texture_resident_queue`: the tiles are marked bound at once, and the binds go into `sparse_binds`, one list shared by every texture. `texture_resident_flush` later binds the whole list with `vkQueueBindSparse`, into one image only: `VkSparseImageMemoryBindInfo` takes a single `image` for the list. Each run takes its staging memory with `staging()`. When that failed part-way, the code was: ```cpp if (!st.buffer) return false; ``` so it returned with the binds of the earlier rows still in `sparse_binds`. Step by step: 1. Texture A (sparse) uploads. Rows 0..N queue the binds of their tiles; those tiles are marked bound. 2. The staging for row N+1 fails, and `upload_inner` returns false. A's binds are still in `sparse_binds` and were never made. 3. Texture B (sparse) uploads. Its `texture_resident_flush` binds the whole list into **B's** image, including A's binds. The memory meant for A's tiles goes to the same coordinates of B's image. 4. A's tiles stay marked bound, so no later write queues them again. A's later copies into those tiles land in unbacked memory, and B gets memory it did not ask for. The other exits of that loop (a new staging arena, the end of the upload) already call `texture_resident_flush(&tex)` first. Only the staging-failure exit did not. ### What changed Only that exit, in `upload_inner`: ```cpp if (!st.buffer) { texture_resident_flush(&tex); return false; } ``` The binds the earlier rows queued are now made into A's own image before giving up, as the other exits do. The success path is unchanged. A texture is only sparse when it is a 2D array over `RX_VK_TEX_MAX_MB` (1.5 GB) on a device with sparse support, which is MKW's course-map case. ### Test `tests/test_sparse_staging_failure.py` is a source check on `upload_inner`. In the part of the loop after the first `staging()` call and before `texture_resident_queue`, every `return false;` must have a `texture_resident_flush(&tex);` in the same block. The old `if (!st.buffer) return false;` must be gone. On main it fails with "a staging failure returns without binding the sparse blocks queued before it"; with the fix it passes. ### How tested - The new test fails on main and passes with the fix. - The tests that reference vk_texture.cpp pass. - Release build OK. - Zelda OoT on Radeon RX 9070 XT (Windows, Adrenalin), nightly with this change, about 40 minutes, log clean. This checks that non-sparse uploads are unaffected; the sparse path itself is not reached there. Assisted-by: GitHub Copilot Restored-from: https://github.com/NotRexed/Hookshot/pull/3031 </details> <details><summary><code>c9c28c5c</code> fix(vk): retry sparse blocks whose bind failed (juliotec)</summary> ### The bug A sparse texture gets device memory per block (tile) as it is written, instead of all at once (gpu/vk/vk_texture.cpp): - `sparse_queue` walks the tiles a write reaches. For each tile that has no memory yet, it takes memory with `sparse_take`, appends a bind to `sparse_binds`, and **marks the tile bound at once** (`bound = 1`). The mip tail works the same way, with `sparse_opaque` and `tail_bound`. - `sparse_flush` then binds the whole list with `vkQueueBindSparse` and waits on a fence. When the bind failed, `sparse_flush` only logged it: ```cpp res = vkQueueBindSparse(dev.queue, 1, &bi, fence); ... if (res == VK_SUCCESS) { vkWaitForFences(...); vkResetFences(...); } else { logf("vk: sparse texture %#llx: binding failed (%d)", ...); } ... sparse_binds.clear(); sparse_opaque.clear(); return res == VK_SUCCESS; ``` Step by step: 1. A write to a sparse texture queues the binds of tiles A, B and C. Their `tiles[...]` entries are set to 1. 2. `vkQueueBindSparse` fails (for example, out of memory). The list is cleared, but the tiles stay marked bound. 3. The upload's copies go ahead and write tiles A, B and C, which have no memory behind them. 4. Every later write to those tiles sees them marked bound, so it never queues them again. Those tiles stay unbacked for the life of the texture, and every write to them is lost. Two more problems were in the same function: - The fence was created without checking. If `vkCreateFence` failed, every bind was submitted and waited on with a null fence. `vkWaitForFences` requires valid handles (VUID-vkWaitForFences-pFences-parameter: "pFences must be a valid pointer to an array of fenceCount valid VkFence handles"). - The memory `sparse_take` gave for the failed binds was simply lost to that texture. ### What changed (gpu/vk/vk_texture.cpp and vk_texture.h) - **New `sparse_unqueue(tex)`.** When the binds are not made, it: - marks every queued tile unbound again (`map[i] = 0`), finding the tile with the same math `sparse_queue` uses; - marks every queued mip tail unbound again (`tail_bound[layer] = 0`); - puts the memory those binds had taken on the texture's free list; - clears the queue, and counts `sparse_added` as `sparse_flush` does. The next write to those tiles queues them again, so the bind is retried. - **`sparse_flush` calls it in both failure cases**, and returns false: ```cpp if (vkCreateFence(dev.device, &fi, nullptr, &fence) != VK_SUCCESS) { fence = VK_NULL_HANDLE; static int logged; if (logged++ < 8) logf("vk: sparse texture %#llx: no fence for its binds", ...); sparse_unqueue(tex); return false; } ... } else { static int failed; if (failed++ < 8) logf("vk: sparse texture %#llx: binding failed (%d)", ...); sparse_unqueue(tex); return false; } ``` - **New per-texture free list** (`Texture::sparse_free`, with memory, offset and size). `sparse_take` gives it out before taking new chunk memory. A bind that keeps failing reuses the same memory instead of taking new memory on every retry. The list only points at the texture's own chunks, which are freed with the texture. - **Both messages are capped at 8.** A failing bind is now retried on later writes, so without the cap it would log on every write to that texture. The success path is unchanged. ### Who reaches this A texture is only sparse when it is a 2D array larger than `RX_VK_TEX_MAX_MB` (1.5 GB) on a device with sparse support. That is MKW's course-map case. OoT likely never makes one. ### Changes after review - The "binding failed" and "no fence for its binds" messages are capped at 8, like the other sparse messages. - The description now says when a texture is sparse, and that the OoT test does not reach this path. ### Test There is no dedicated unit test. The failure needs `vkQueueBindSparse` or `vkCreateFence` to fail on a sparse texture. ### How tested - Release build. - Zelda OoT on Radeon RX 9070 XT (Windows, Adrenalin), including about 40 minutes on nightly g57471723, which includes this change. Log clean, with no "sparse texture" line. - The sparse path itself was not run. The test only shows that non-sparse textures are unaffected. Assisted-by: GitHub Copilot Restored-from: https://github.com/NotRexed/Hookshot/pull/2743 </details> ## Measurements **Verdict:** nothing to measure: a correctness fix off the frame path, covered by game-free checks. ### Flags and settings None. ## Testing **Tested:** On Linux (kernel 7.0), RTX 4070 Ti, `main` @ 71b1edd8, this PR @ c9c28c5c: `the checks that read the changed files (`tests/run_all.py --changed origin/main`)` pass. The full suite (`tests/run_all.py`) has not been run on this branch yet; a comment will follow when it has. **Not tested:** The game on a GPU where these calls were invalid. Opened as work in progress until it runs in the game. **Must be tested:** - AMD on Linux (Test Farm: @Beanstalk radv): Kokiri Forest and Hyrule Field for 5 minutes, expecting no device lost and no validation errors with `VK_LAYER_KHRONOS_validation` - Intel on Windows (Test Farm: @Beanstalk windows, an Intel GPU): the same ## Risks **What could break:** texture copies, clears and sparse textures where a check is wrong. **Turning it off:** revert the commit. **Compatibility:** Nothing changes. ## 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). - [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] 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. - [ ] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). ### When it applies - [x] A game-free test added for the fix, failing on `main` and passing here.
### The bug

`copy_t2t` (gpu/vk/vk_xfer.cpp) makes a texture-to-texture copy in one
of three ways:

1. `vkCmdResolveImage`: a multisampled source into a single-sampled
destination of the same size.
2. `vkCmdCopyImage`: same size, same block size, same sample count.
3. `vkCmdBlitImage`: everything else, which means scaled or converting
copies.

Branch 3 called `vkCmdBlitImage` without checking any of the rules the
spec puts on it. Step by step, with one example:

1. The game copies a texture into another of a different size or a
different format, for example an unsigned-integer texture into a
normalized-colour one.
2. Neither the resolve nor the copy branch applies, so the copy goes to
`vkCmdBlitImage`.
Linear is used when the game asks for it, or when the destination keeps
its level at a smaller size than the source (`d.down > s.down`).
4. When one of those rules is broken, the command is invalid usage and
the result is undefined. Some drivers tolerate it; others may write
garbage or lose the device.

The rules, with their exact text from the spec (`validusage.json`):

| VUID | Text |
|---|---|
| VUID-vkCmdBlitImage-srcImage-01999 | The format features of srcImage
must contain VK_FORMAT_FEATURE_BLIT_SRC_BIT |
| VUID-vkCmdBlitImage-dstImage-02000 | The format features of dstImage
must contain VK_FORMAT_FEATURE_BLIT_DST_BIT |
| VUID-vkCmdBlitImage-filter-02001 | If filter is VK_FILTER_LINEAR, then
the format features of srcImage must contain
VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT |
| VUID-vkCmdBlitImage-srcImage-00229 | If either of srcImage or dstImage
was created with a signed integer VkFormat, the other must also have
been created with a signed integer VkFormat |
| VUID-vkCmdBlitImage-srcImage-00230 | If either of srcImage or dstImage
was created with an unsigned integer color VkFormat, the other must also
have been created with an unsigned integer color VkFormat |
| VUID-vkCmdBlitImage-srcImage-00231 | If either of srcImage or dstImage
was created with a depth/stencil format and the maintenance12 feature is
not enabled the other must have exactly the same format |
| VUID-vkCmdBlitImage-srcImage-00233 | srcImage must have been created
with a samples value of VK_SAMPLE_COUNT_1_BIT |
| VUID-vkCmdBlitImage-dstImage-00234 | dstImage must have been created
with a samples value of VK_SAMPLE_COUNT_1_BIT |

Hookshot does not enable maintenance12, so -00231 applies as written.
The images are created with `VK_IMAGE_TILING_OPTIMAL`, so the format
features that matter are `optimalTilingFeatures`.

### What changed (gpu/vk/vk_xfer.cpp)

Before, branch 3 went straight to the blit:

```cpp
} else {   // scaled or converting
	VkImageBlit bl{};
	...
	const bool linear = ((p.flags & NVN_COPY_FLAGS_LINEAR_FILTER_BIT) || d.down > s.down) && color;
	vkCmdBlitImage(..., linear ? VK_FILTER_LINEAR : VK_FILTER_NEAREST);
}
```

Now it first checks the rules above, and skips a blit that breaks any of
them:

```cpp
if (!(tiling_features(s.tex->format) & VK_FORMAT_FEATURE_BLIT_SRC_BIT) ||        // -01999
	!(tiling_features(d.tex->format) & VK_FORMAT_FEATURE_BLIT_DST_BIT) ||        // -02000
	format_class(s.tex->format) != format_class(d.tex->format) ||                // -00229, -00230
	(!color && s.tex->format != d.tex->format) ||                                // -00231
	s.tex->samples != VK_SAMPLE_COUNT_1_BIT || d.tex->samples != VK_SAMPLE_COUNT_1_BIT) {   // -00233, -00234
	warn(13, "texture blit the device cannot make: skipped");
	full_barrier(cmd);
	return;
}
```

Linear filtering is only used when the source format supports it
(-02001), and only for float or normalized formats:

```cpp
const bool linear = ((p.flags & NVN_COPY_FLAGS_LINEAR_FILTER_BIT) || d.down > s.down) && color &&
					(tiling_features(s.tex->format) & VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT) &&
					format_class(s.tex->format) == 0;
```

Two new helpers in the same file:

- `format_class(VkFormat)` returns:
  - 1 for the unsigned-integer formats,
  - 2 for the signed-integer formats,
  - 0 for everything else (float, normalized, sRGB).
- `tiling_features(VkFormat)` returns the format's
`optimalTilingFeatures`:
- For the core formats (values below 256), it asks the driver once per
format and keeps the answer in a lock-free `std::atomic<uint64_t>`
table. Bit 63 marks a format as already asked.
  - Formats from extensions (256 and above) are asked each time.
- A scaled copy checks both sides, so the cache avoids querying the
driver twice per copy on the replay thread.

The depth/stencil condition is already caught earlier in `copy_t2t`, by
warn 7 ("texture copy between unlike depth formats: skipped"), so it
never fires here. It is kept in the check so the blit's own rules stay
in one place.

`warn` logs each key at most 3 times.

### Behaviour

- A blit that follows the rules goes through exactly as before.
- A blit that breaks a rule is skipped, and its destination is left as
it was. Before, it was undefined: it may have looked right on some
drivers, for example an integer/float mix or a multisampled image on a
driver that tolerates it. Now the destination is stale instead.
- This matters most on devices with a narrower format list (mobile and
integrated GPUs, layered drivers such as MoltenVK), and for games or
scenes that blit less common formats.

### Changes after review

- The format features come from the `tiling_features` cache, so they are
not queried twice per scaled copy.
- The first push of that change left one use of the old local variable
in the linear-filter check. The vk_xfer tests don't compile that code;
the full release build caught it, and it is fixed.

### Test

There is no dedicated unit test for these rules. The change is reviewed
against the VUIDs above. The existing checks that compile or read
vk_xfer.cpp pass (6, including `test_vulkan_copy_span_gpu_compile`).

### How tested

- Release build (`nx2/build.py --standalone`, Windows, llvm-mingw).
- The 6 vk_xfer.cpp checks pass.
- Zelda OoT on Radeon RX 9070 XT (Windows, Adrenalin):
  - Two full sessions on build g54d01844.
- One session of about 40 minutes on nightly g57471723, which includes
this change.
  - No visible regression, no device loss.
- "texture blit the device cannot make" does not appear in any of those
logs. Every blit OoT makes on this device follows the rules, so the skip
path is not reached there. This change guards against invalid usage; it
does not fix a visible glitch in OoT.

Assisted-by: GitHub Copilot
Restored-from: https://github.com/NotRexed/Hookshot/pull/2691
### The bug

ASTC textures are kept in one of three ways, depending on the GPU:

- **Decoded to RGBA8** on most GPUs.
- **Re-encoded as BC3** for some big textures.
- **Kept as ASTC blocks** when the device samples ASTC natively
(`textureCompressionASTC_LDR`, `astc_native()`). The image then has an
ASTC `VkFormat`.

`clear_tex` (gpu/vk/vk_xfer.cpp) clears a texture in one of two ways:

1. **Whole level**: when the clear covers the whole level, the image is
not 3D, and the format is not BC (`raw`), it uses `vkCmdClearColorImage`
for colour, or `vkCmdClearDepthStencilImage`.
2. **Region**: otherwise, a render pass over that level and layer with
`vkCmdClearAttachments`. For BC images (`raw`) the rectangle is
converted to blocks.

`raw` is computed only for the BC range, so an image kept in ASTC blocks
was treated as uncompressed. Step by step:

1. On a device with native ASTC, the game clears an ASTC texture.
2. If the clear covers the whole level, `clear_tex` calls
`vkCmdClearColorImage` on the ASTC image. This breaks
**VUID-vkCmdClearColorImage-image-00007**: "image must not have a
compressed or depth/stencil format".
3. If it covers part of the level, the region path below only converts
the rectangle to blocks for BC formats, not for ASTC.
4. Either way, a colour written over ASTC blocks would be garbage, since
the blocks are compressed data, not texels.

### What changed (gpu/vk/vk_xfer.cpp, clear_tex)

Before, no ASTC check:

```cpp
full_barrier(cmd);
const bool volume = s.tex->type == VK_IMAGE_TYPE_3D;
const bool raw = s.tex->format >= VK_FORMAT_BC1_RGB_UNORM_BLOCK && s.tex->format <= VK_FORMAT_BC7_SRGB_BLOCK;
```

After:

```cpp
full_barrier(cmd);
if (s.tex->format >= VK_FORMAT_ASTC_4x4_UNORM_BLOCK && s.tex->format <= VK_FORMAT_ASTC_12x12_SRGB_BLOCK) {
	warn(14, "clear of an ASTC texture: skipped");
	return;
}
const bool volume = s.tex->type == VK_IMAGE_TYPE_3D;
```

A clear of an image whose format is ASTC is skipped, and the image is
left as it was. `warn` logs it at most 3 times.

The early return also skips `texture_written` at the end of `clear_tex`,
so the texture is not marked as GPU-written. That is on purpose, because
nothing was written to it.

ASTC textures decoded to RGBA8, ASTC kept as BC3, and every other format
are cleared exactly as before.

### Who reaches this

Only devices that expose `textureCompressionASTC_LDR` and sample ASTC
natively, such as Intel iGPUs. AMD and NVIDIA desktop drivers don't
expose it, so on them the image is never in an ASTC format and the new
check never matches.

### Changes after review

- The description no longer claims that drivers hang. The rule comes
from the spec (the VUID above).
- Skipping `texture_written` was confirmed as intended.

### Test

There is no dedicated unit test. In the review run,
`test_bc_raw_targets.py` and `test_vulkan_clear_mip.py` pass with this
change.

### How tested

- Release build.
- Zelda OoT on Radeon RX 9070 XT (Windows, Adrenalin), including about
40 minutes on nightly g57471723, which includes this change. Log clean,
and "clear of an ASTC texture" does not appear.
- This GPU has no native ASTC, so the new path was not run. The test
only checks that a GPU without native ASTC is unaffected.

Assisted-by: GitHub Copilot
Restored-from: https://github.com/NotRexed/Hookshot/pull/2718
### The bug

`mesh_args_take(n)` (gpu/vk/vk_draw.cpp) hands out `n` consecutive
16-byte entries of the mesh-argument ring (`kMeshArgs` entries). Each
indirect mesh draw gets its own range: the GPU copies the draw's counts
and firsts into it, and the draw reads them from there. The code was:

```cpp
const uint32_t at = next.fetch_add(n) % (kMeshArgs - n);
return at + 1;
```

The modulus depends on `n`, so two draws taken one after another with
different counts can land on the same entries. A worked example with the
old `kMeshArgs = 262144`:

1. The counter is at 262130, and a draw takes `n = 100`. The modulus is
262144 - 100 = 262044, so `at = 262130 % 262044 = 86`. The draw gets
entries **87..186**.
2. The counter is now 262230, and the next draw takes `n = 1`. The
modulus is 262143, so `at = 262230 % 262143 = 87`. The draw gets entry
**88**.
3. Entry 88 is inside the first draw's range. The second draw is a
direct draw with a first task, so it writes its first into entry 88 from
the CPU while recording (`mesh_args_words[at * 4 + 3] = first`). The
first draw's GPU copy, which runs later, writes its own count and first
over entry 88. The second draw then reads the first draw's values
instead of its own. Two indirect draws that overlap overwrite each other
in the same way, through their GPU copies.
4. On screen, this shows as wrong, flickering or missing mesh geometry.

Who calls `mesh_args_take`:

- **Without `RX_VK_MESH_ARGS` (the default):** only direct mesh draws
with a non-zero first task, always with `n = 1`. With a constant `n`,
the modulus is constant and nothing overlaps.
- **With `RX_VK_MESH_ARGS=1`:** the rewritten indirect draws also call
it, with `n = d.max` (from 1 up to the old `kMeshArgs - 1`). They mix
with the `n = 1` calls, and that mix is what overlaps.

### What changed (gpu/vk/vk_draw.cpp)

The modulus is now fixed at `kMeshArgs / 2`, and `n` is clamped to at
most `kMeshArgs / 2`:

```cpp
// before
const uint32_t at = next.fetch_add(n) % (kMeshArgs - n);
// after
n = std::clamp<uint32_t>(n, 1, kMeshArgs / 2);
const uint32_t at = next.fetch_add(n) % (kMeshArgs / 2);
```

- Every range starts in the first half of the ring and is at most half a
ring long, so it never runs past the end.
- With one modulus for every `n`, ranges handed out one after another
follow each other in the ring. An entry is only reused when the counter
has advanced by a whole modulus.
- The indirect caller clamps `n` the same way: `std::clamp(d.max, 1,
(int)(kMeshArgs / 2))` instead of `kMeshArgs - 1`.
That keeps the reuse distance at 262144 entries, as before; halving the
modulus alone would have halved it.
- A power-of-two modulus also stays continuous when the 32-bit counter
wraps, which the old one did not.

### Cost

- The ring buffer is host-visible and grows from 4 MB to 8 MB. It is
also created for direct mesh draws with a non-zero first task, flag or
not, so the extra 4 MB applies to everyone who reaches that path.
- The `RX_VK_LOG_MESH_PERPROG` diagnostic `prog_at` vector (`kMeshArgs`
entries) doubles too.

### Test

`tests/mesh_args_cleanup_test.cpp` checked that the ring allocation was
at most 4 MB, which the new size breaks. It now requires the allocation
to be exactly `kMeshArgs * 16` bytes, computed from the `kMeshArgs` the
test extracts from vk_draw.cpp, so it follows the real size instead of a
fixed bound. `tests/test_mesh_args_cleanup.py` passes its 5 cases.

### Changes after review

- The test fixture's 4 MB bound was replaced by the size computed from
`kMeshArgs`.
- The description now covers the extra 4 MB on the direct-draw path and
the doubled `prog_at` vector.

### How tested

- Release build.
- `tests/test_mesh_args_cleanup.py`: 5 cases pass.
- Zelda OoT on Radeon RX 9070 XT (Windows, Adrenalin):
- With the flag off (the default; the `n = 1` direct-draw path),
including about 40 minutes on nightly g57471723, which includes this
change. Log clean.
- With `RX_VK_MESH_ARGS=1` (the rewritten indirect draws, mixed counts).

Assisted-by: GitHub Copilot
Restored-from: https://github.com/NotRexed/Hookshot/pull/2719
### The bug

`texel_buffer_view` (gpu/vk/vk_texture.cpp) creates the `VkBufferView`
for a texture the game binds as a texel buffer:

- as a **uniform** texel buffer when it is sampled,
- as a **storage** texel buffer when it is written.

The view's format is the one the texture maps to
(`vk_format(nf).format`). The only check was that the format is not
`VK_FORMAT_UNDEFINED`. Nothing checked whether the device supports texel
buffers of that format. Step by step:

1. The game binds a texture as a texel buffer, in a format such as
`VK_FORMAT_R32G32B32_SFLOAT`.
2. The device does not list `VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT`
(or `STORAGE_TEXEL_BUFFER_BIT`) for it in the format's `bufferFeatures`.
Which formats are listed varies by driver.
3. `texel_buffer_view` creates the view anyway. This is invalid usage:

| VUID | Text |
|---|---|
| VUID-VkBufferViewCreateInfo-format-08778 | If the buffer view usage
contains VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT, then format features
of format must contain VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT |
| VUID-VkBufferViewCreateInfo-format-08779 | If the buffer view usage
contains VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT, then format features
of format must contain VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BIT |

4. What the shader then reads or writes through that view is undefined.

### What changed (gpu/vk/vk_texture.cpp, texel_buffer_view)

A check right after the format is known, before anything is created,
looked up, or marked as written:

```cpp
VkFormat f = vk_format(nf).format;
if (f == VK_FORMAT_UNDEFINED) return VK_NULL_HANDLE;
// new:
if (!(format_props(f).bufferFeatures & (storage ? VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BIT
												: VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT))) {
	static std::atomic<int> logged{0};
	if (logged.fetch_add(1, std::memory_order_relaxed) < 8)
		logf("vk: texel buffer of format %d (%s) not supported by the device: unbound", (int)f, storage ? "storage" : "uniform");
	return VK_NULL_HANDLE;
}
```

- A format without the needed feature gets no view, and the slot stays
unbound. Callers already handle a null view; it is the same result as
the existing `VK_FORMAT_UNDEFINED` case.
- Because it returns before `texture_gpu_wrote`, a storage bind that is
refused does not mark the texture as written by the GPU.
- The answer comes from the existing `format_props` cache, which takes
one short lock (`fmt_mu`) per texel-buffer bind but does not query the
driver again.
- The message is logged at most 8 times.
- Supported formats follow the same path as before.

### Test

`tests/test_texel_buffer_ownership.py` cuts `texel_buffer_view` out of
vk_texture.cpp and compiles it against the stubs in
`tests/texel_buffer_ownership_test.cpp`:

- The fixture gets a `format_props` stub. It reports both texel-buffer
features for every format except the one mapped from NVN format 44
(`VK_FORMAT_R32G32B32_SFLOAT`).
- A new case, `unsupported`, binds format 44 as uniform and as storage.
It checks that:
  - neither returns a view;
  - no view is created (`creates == 0`);
  - no buffer is looked up (`lookups == 0`);
  - the texture is not marked as written (`writes == 0`).
- All 24 cases pass. On main, the case list has 23.

### Changes after review

- The first version did not add the stub, so the test failed to compile
("'format_props' was not declared in this scope"). The stub and the
`unsupported` case were added.

### How tested

- Release build (`nx2/build.py --standalone`, Windows, llvm-mingw).
- `tests/test_texel_buffer_ownership.py`: 24 cases pass.
- Zelda OoT on Radeon RX 9070 XT (Windows, Adrenalin):
  - Two full sessions on build g54d01844.
- One session of about 40 minutes on nightly g57471723, which includes
this change.
  - No regression.
- "texel buffer of format" does not appear in any of those logs. Every
texel-buffer format OoT uses is supported on this device, so the new
path is not reached there. This change guards against invalid usage; it
does not fix a visible glitch in OoT.

Assisted-by: GitHub Copilot
Restored-from: https://github.com/NotRexed/Hookshot/pull/2741
### The bug

`upload_inner` (gpu/vk/vk_texture.cpp) uploads a texture in runs of
rows. For a sparse texture, each run first queues the binds of the tiles
it touches with `texture_resident_queue`: the tiles are marked bound at
once, and the binds go into `sparse_binds`, one list shared by every
texture. `texture_resident_flush` later binds the whole list with
`vkQueueBindSparse`, into one image only: `VkSparseImageMemoryBindInfo`
takes a single `image` for the list.

Each run takes its staging memory with `staging()`. When that failed
part-way, the code was:

```cpp
if (!st.buffer) return false;
```

so it returned with the binds of the earlier rows still in
`sparse_binds`. Step by step:

1. Texture A (sparse) uploads. Rows 0..N queue the binds of their tiles;
those tiles are marked bound.
2. The staging for row N+1 fails, and `upload_inner` returns false. A's
binds are still in `sparse_binds` and were never made.
3. Texture B (sparse) uploads. Its `texture_resident_flush` binds the
whole list into **B's** image, including A's binds. The memory meant for
A's tiles goes to the same coordinates of B's image.
4. A's tiles stay marked bound, so no later write queues them again. A's
later copies into those tiles land in unbacked memory, and B gets memory
it did not ask for.

The other exits of that loop (a new staging arena, the end of the
upload) already call `texture_resident_flush(&tex)` first. Only the
staging-failure exit did not.

### What changed

Only that exit, in `upload_inner`:

```cpp
if (!st.buffer) {
	texture_resident_flush(&tex);
	return false;
}
```

The binds the earlier rows queued are now made into A's own image before
giving up, as the other exits do. The success path is unchanged.

A texture is only sparse when it is a 2D array over `RX_VK_TEX_MAX_MB`
(1.5 GB) on a device with sparse support, which is MKW's course-map
case.

### Test

`tests/test_sparse_staging_failure.py` is a source check on
`upload_inner`. In the part of the loop after the first `staging()` call
and before `texture_resident_queue`, every `return false;` must have a
`texture_resident_flush(&tex);` in the same block. The old `if
(!st.buffer) return false;` must be gone. On main it fails with "a
staging failure returns without binding the sparse blocks queued before
it"; with the fix it passes.

### How tested

- The new test fails on main and passes with the fix.
- The tests that reference vk_texture.cpp pass.
- Release build OK.
- Zelda OoT on Radeon RX 9070 XT (Windows, Adrenalin), nightly with this
change, about 40 minutes, log clean. This checks that non-sparse uploads
are unaffected; the sparse path itself is not reached there.

Assisted-by: GitHub Copilot
Restored-from: https://github.com/NotRexed/Hookshot/pull/3031
fix(vk): retry sparse blocks whose bind failed
Some checks are pending
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
CI / Conventional Commit title (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 5s
Website / Website on Cloudflare (pull_request_target) Has been skipped
c9c28c5c74
### The bug

A sparse texture gets device memory per block (tile) as it is written,
instead of all at once (gpu/vk/vk_texture.cpp):

- `sparse_queue` walks the tiles a write reaches. For each tile that has
no memory yet, it takes memory with `sparse_take`, appends a bind to
`sparse_binds`, and **marks the tile bound at once** (`bound = 1`). The
mip tail works the same way, with `sparse_opaque` and `tail_bound`.
- `sparse_flush` then binds the whole list with `vkQueueBindSparse` and
waits on a fence.

When the bind failed, `sparse_flush` only logged it:

```cpp
res = vkQueueBindSparse(dev.queue, 1, &bi, fence);
...
if (res == VK_SUCCESS) {
	vkWaitForFences(...); vkResetFences(...);
} else {
	logf("vk: sparse texture %#llx: binding failed (%d)", ...);
}
...
sparse_binds.clear(); sparse_opaque.clear();
return res == VK_SUCCESS;
```

Step by step:

1. A write to a sparse texture queues the binds of tiles A, B and C.
Their `tiles[...]` entries are set to 1.
2. `vkQueueBindSparse` fails (for example, out of memory). The list is
cleared, but the tiles stay marked bound.
3. The upload's copies go ahead and write tiles A, B and C, which have
no memory behind them.
4. Every later write to those tiles sees them marked bound, so it never
queues them again. Those tiles stay unbacked for the life of the
texture, and every write to them is lost.

Two more problems were in the same function:

- The fence was created without checking. If `vkCreateFence` failed,
every bind was submitted and waited on with a null fence.
`vkWaitForFences` requires valid handles
(VUID-vkWaitForFences-pFences-parameter: "pFences must be a valid
pointer to an array of fenceCount valid VkFence handles").
- The memory `sparse_take` gave for the failed binds was simply lost to
that texture.

### What changed (gpu/vk/vk_texture.cpp and vk_texture.h)

- **New `sparse_unqueue(tex)`.** When the binds are not made, it:
- marks every queued tile unbound again (`map[i] = 0`), finding the tile
with the same math `sparse_queue` uses;
  - marks every queued mip tail unbound again (`tail_bound[layer] = 0`);
  - puts the memory those binds had taken on the texture's free list;
  - clears the queue, and counts `sparse_added` as `sparse_flush` does.

The next write to those tiles queues them again, so the bind is retried.

- **`sparse_flush` calls it in both failure cases**, and returns false:

  ```cpp
  if (vkCreateFence(dev.device, &fi, nullptr, &fence) != VK_SUCCESS) {
	  fence = VK_NULL_HANDLE;
	  static int logged;
if (logged++ < 8) logf("vk: sparse texture %#llx: no fence for its
binds", ...);
	  sparse_unqueue(tex);
	  return false;
  }
  ...
  } else {
	  static int failed;
if (failed++ < 8) logf("vk: sparse texture %#llx: binding failed (%d)",
...);
	  sparse_unqueue(tex);
	  return false;
  }
  ```

- **New per-texture free list** (`Texture::sparse_free`, with memory,
offset and size). `sparse_take` gives it out before taking new chunk
memory. A bind that keeps failing reuses the same memory instead of
taking new memory on every retry. The list only points at the texture's
own chunks, which are freed with the texture.

- **Both messages are capped at 8.** A failing bind is now retried on
later writes, so without the cap it would log on every write to that
texture.

The success path is unchanged.

### Who reaches this

A texture is only sparse when it is a 2D array larger than
`RX_VK_TEX_MAX_MB` (1.5 GB) on a device with sparse support. That is
MKW's course-map case. OoT likely never makes one.

### Changes after review

- The "binding failed" and "no fence for its binds" messages are capped
at 8, like the other sparse messages.
- The description now says when a texture is sparse, and that the OoT
test does not reach this path.

### Test

There is no dedicated unit test. The failure needs `vkQueueBindSparse`
or `vkCreateFence` to fail on a sparse texture.

### How tested

- Release build.
- Zelda OoT on Radeon RX 9070 XT (Windows, Adrenalin), including about
40 minutes on nightly g57471723, which includes this change. Log clean,
with no "sparse texture" line.
- The sparse path itself was not run. The test only shows that
non-sparse textures are unaffected.

Assisted-by: GitHub Copilot
Restored-from: https://github.com/NotRexed/Hookshot/pull/2743
Author
Contributor

Tested in game: Linux (Ubuntu 26.04.1, kernel 7.0.0-43), RTX 4070 Ti 12 GB, NVIDIA 595.99.02, Ryzen 7 9800X3D: this branch built together with the other 18 split from #218 and #284-#288, merged onto main @ 71b1edd8 (make_game.py --update, build v3.0.0-rc.5-82-g5952bb3d), then played by a scripted tour through the control bridge (scripts/memtour.py: a save loaded, Zora's Domain, the Market, Hyrule Field and Death Mountain Trail, 40 s each with walking and camera swings). All 4 stops reached, a clean quit, and no device loss or Vulkan error in the log. The renderer ran with these checks in place; the cases they guard (a blit, ASTC clear or mesh limit the device does not allow) did not come up on this GPU.

Tested in game: Linux (Ubuntu 26.04.1, kernel 7.0.0-43), RTX 4070 Ti 12 GB, NVIDIA 595.99.02, Ryzen 7 9800X3D: this branch built together with the other 18 split from #218 and #284-#288, merged onto main @ 71b1edd8 (make_game.py --update, build v3.0.0-rc.5-82-g5952bb3d), then played by a scripted tour through the control bridge (scripts/memtour.py: a save loaded, Zora's Domain, the Market, Hyrule Field and Death Mountain Trail, 40 s each with walking and camera swings). All 4 stops reached, a clean quit, and no device loss or Vulkan error in the log. The renderer ran with these checks in place; the cases they guard (a blit, ASTC clear or mesh limit the device does not allow) did not come up on this GPU.
Collaborator

Possibly related, for context:

  • PR #671 fix(vk): make a sparse BC image with the usage its sparse residency was checked for — Overlaps sparse texture behavior in vk_texture.cpp
  • issue #395 Game: Crash in nvoglv64.dll after Vulkan 64 MB staging arena allocation failures during heavy texture uploads — Sparse staging fallback could address this reported crash
Possibly related, for context: - PR #671 fix(vk): make a sparse BC image with the usage its sparse residency was checked for — Overlaps sparse texture behavior in vk_texture.cpp - issue #395 Game: Crash in nvoglv64.dll after Vulkan 64 MB staging arena allocation failures during heavy texture uploads — Sparse staging fallback could address this reported crash
Some checks are pending
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
CI / Conventional Commit title (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 5s
Website / Website on Cloudflare (pull_request_target) Has been skipped
This pull request is marked as a work in progress.
Some workflows are waiting to be reviewed.
This branch is out-of-date with the base branch
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u 'fix/vk-validity:TrashPanda-fix/vk-validity'
git switch 'TrashPanda-fix/vk-validity'
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!1160
No description provided.