Catcrafts/Crafter.Graphics
2
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions

perf(image): release static texture staging after upload (#114)

Browse source 
ImageVulkan kept its host-visible staging `buffer` (sized w*h, persistently
mapped) alive for the whole life of the image and Destroy() never freed it, so
static textures (e.g. Sponza albedo) pinned HOST_VISIBLE / small-BAR memory
forever.

Update now releases the staging via VulkanBuffer::DeferredClear() right after
recording the buffer→image copy — the same fence-keyed deletion queue
(#101/#102) the compressed Mesh path already uses — so it is freed once the
upload submit's frame has cleared. A new `streamed` flag (set by FontAtlas)
keeps the persistent map for images re-uploaded from a CPU-side staging buffer
every frame; its uploads go through UpdateRegion, which never releases. Destroy
now also frees any staging the image still owns, gated on a live handle so a
released static texture can't double-free.

Adds tests/ImageStagingRelease driving the real upload + readback on a headless
device: asserts the staging is enqueued (not pinned), the image reads back
byte-equal (released staging outlived the submit), the entry retires only after
framesInFlight frames, and a streamed image keeps then frees its staging.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
catbot 2026-06-17 19:40:35 +00:00
commit b4fa6e596e
4 changed files with 314 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

238
tests/ImageStagingRelease/main.cpp Normal file
View file

@ -0,0 +1,238 @@
/*
Crafter®.Graphics
Copyright (C) 2026 Catcrafts®
catcrafts.net
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License version 3.0 as published by the Free Software Foundation;
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*/
// Issue #114: a static ImageVulkan used to keep its host-visible staging
// `buffer` (sized w*h, persistently mapped) alive for the whole life of the
// image, pinning HOST_VISIBLE / small-BAR memory long after the one upload that
// reads it has retired — and Destroy() never freed it. Update now releases it
// via VulkanBuffer::DeferredClear() right after recording the buffer→image
// copy, so the fence-keyed deletion queue (#101/#102) frees it once that
// submit's frame has cleared. A `streamed` image (the FontAtlas) keeps its
// staging, since it re-fills the persistent map and re-uploads every frame.
//
// This drives the real upload path on a headless device — no swapchain/window
// needed, a buffer→image copy only touches the queue + command pool — and
// asserts:
// - After a static Update, image.buffer owns no handle (released), and
// exactly that one allocation was handed to the deletion queue tagged with
// the current frame (so it retires later, not now).
// - The upload + readback still complete with ZERO validation errors and the
// image reads back byte-equal to the staged source — proof the staging
// genuinely outlived the submit (the queue had not yet retired it), so
// releasing it is no use-after-free.
// - The deferred entry retires (and frees) only once framesInFlight frames
// elapse, and not before.
// - A `streamed` image keeps its staging across Update and UpdateRegion (the
// FontAtlas contract), and Destroy() then frees it validation-clean.
#include "vulkan/vulkan.h"
#include <cstring>
import Crafter.Graphics;
import std;
using namespace Crafter;
namespace {
int failures = 0;
void Check(bool ok, std::string_view what) {
std::println("{} {}", ok ? "PASS" : "FAIL", what);
if (!ok) ++failures;
}
VkCommandBuffer BeginCmd() {
VkCommandBufferAllocateInfo allocInfo {
.sType = VK_STRUCTURE_TYPE_COMMAND_BUFFER_ALLOCATE_INFO,
.commandPool = Device::commandPool,
.level = VK_COMMAND_BUFFER_LEVEL_PRIMARY,
.commandBufferCount = 1,
};
VkCommandBuffer cmd = VK_NULL_HANDLE;
Device::CheckVkResult(vkAllocateCommandBuffers(Device::device, &allocInfo, &cmd));
VkCommandBufferBeginInfo beginInfo {
.sType = VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO,
.flags = VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT,
};
Device::CheckVkResult(vkBeginCommandBuffer(cmd, &beginInfo));
return cmd;
}
void SubmitWait(VkCommandBuffer cmd) {
Device::CheckVkResult(vkEndCommandBuffer(cmd));
VkSubmitInfo submitInfo {
.sType = VK_STRUCTURE_TYPE_SUBMIT_INFO,
.commandBufferCount = 1,
.pCommandBuffers = &cmd,
};
Device::CheckVkResult(vkQueueSubmit(Device::queue, 1, &submitInfo, VK_NULL_HANDLE));
Device::CheckVkResult(vkQueueWaitIdle(Device::queue));
vkFreeCommandBuffers(Device::device, Device::commandPool, 1, &cmd);
}
// RGBA8 texel as a 4-byte word, matching VK_FORMAT_R8G8B8A8_UNORM.
using Texel = std::uint32_t;
constexpr std::uint16_t kW = 4;
constexpr std::uint16_t kH = 4;
constexpr std::uint32_t kCount = static_cast<std::uint32_t>(kW) * kH;
} // namespace
int main() {
Device::Initialize();
Device::validationErrorCount = 0;
// Control the deferred-deletion clock: enqueue at frame 0, retire after 2.
Device::framesInFlight = 2;
Device::frameCounter = 0;
Device::deletionQueue.clear();
// ── Static texture: staging is released right after the upload copy. ──────
ImageVulkan<Texel> tex;
{
VkCommandBuffer cmd = BeginCmd();
tex.Create(kW, kH, /*mipLevels*/ 1, cmd,
VK_FORMAT_R8G8B8A8_UNORM,
VK_IMAGE_USAGE_TRANSFER_DST_BIT | VK_IMAGE_USAGE_TRANSFER_SRC_BIT
| VK_IMAGE_USAGE_SAMPLED_BIT,
VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL);
Check(tex.buffer.buffer != VK_NULL_HANDLE,
"Create allocated the host-visible staging buffer");
Check(!tex.streamed, "a default ImageVulkan is not streamed");
// Fill the staging map with a known pattern, then upload.
for (std::uint32_t i = 0; i < kCount; ++i) {
tex.buffer.value[i] = 0xA0B0C0D0u + i;
}
tex.Update(cmd, VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL);
// ── The fix: staging released to the queue at record time, not pinned. ─
Check(tex.buffer.buffer == VK_NULL_HANDLE,
"static Update releases the staging buffer (no handle pinned)");
Check(Device::deletionQueue.size() == 1,
"exactly one allocation (the staging) handed to the deletion queue");
const bool taggedNow = !Device::deletionQueue.empty()
&& Device::deletionQueue.front().retireAfter == 0
&& Device::deletionQueue.front().buffer != VK_NULL_HANDLE;
Check(taggedNow,
"deferred staging is tagged with the enqueue frame and still a live handle");
// Read the image back to prove the copy saw valid staging. The upload's
// recorded copy still references the now-released staging; it must
// outlive THIS submit (queue retires at frame 2, we're at 0). Move the
// image to TRANSFER_SRC and copy into a host-visible readback buffer in
// the same command buffer.
VkImageMemoryBarrier toSrc {
.sType = VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER,
.srcAccessMask = VK_ACCESS_SHADER_READ_BIT,
.dstAccessMask = VK_ACCESS_TRANSFER_READ_BIT,
.oldLayout = VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL,
.newLayout = VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL,
.srcQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED,
.dstQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED,
.image = tex.image,
.subresourceRange = { VK_IMAGE_ASPECT_COLOR_BIT, 0, 1, 0, 1 },
};
vkCmdPipelineBarrier(cmd, VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR,
VK_PIPELINE_STAGE_TRANSFER_BIT, 0, 0, nullptr,
0, nullptr, 1, &toSrc);
VulkanBuffer<Texel, true> readback;
readback.Create(VK_BUFFER_USAGE_TRANSFER_DST_BIT | VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT,
VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT, kCount);
VkBufferImageCopy region {};
region.imageSubresource = { VK_IMAGE_ASPECT_COLOR_BIT, 0, 0, 1 };
region.imageExtent = { kW, kH, 1 };
vkCmdCopyImageToBuffer(cmd, tex.image, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL,
readback.buffer, 1, &region);
SubmitWait(cmd);
Check(Device::validationErrorCount == 0,
"static upload + readback raised no validation errors");
readback.FlushHost();
bool match = true;
for (std::uint32_t i = 0; i < kCount; ++i) {
if (readback.value[i] != 0xA0B0C0D0u + i) { match = false; break; }
}
Check(match,
"image reads back byte-equal to the staged source "
"(released staging outlived the submit)");
}
// ── Retire timing: the staging frees once framesInFlight frames elapse,
// and not a frame before. We've already wait-idled, so freeing is safe. ─
Device::ReclaimDeletions();
Check(Device::deletionQueue.size() == 1,
"staging is NOT freed before framesInFlight frames have elapsed");
Device::frameCounter = 2; // retireAfter(0) + framesInFlight(2) <= 2
Device::ReclaimDeletions();
Check(Device::deletionQueue.empty(),
"staging is freed once its retire frame is reached");
// Destroying the image after its staging was released must not double-free
// (buffer handle is already null) and must stay validation-clean.
Device::validationErrorCount = 0;
tex.Destroy();
Check(Device::validationErrorCount == 0,
"Destroy after a released-staging upload is validation-clean");
// ── Streamed image: the persistent staging is kept across uploads. ────────
Device::frameCounter = 0;
Device::deletionQueue.clear();
Device::validationErrorCount = 0;
{
ImageVulkan<Texel> atlas;
VkCommandBuffer cmd = BeginCmd();
atlas.Create(kW, kH, /*mipLevels*/ 1, cmd,
VK_FORMAT_R8G8B8A8_UNORM,
VK_IMAGE_USAGE_TRANSFER_DST_BIT | VK_IMAGE_USAGE_SAMPLED_BIT,
VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL,
VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT,
/*streamed*/ true);
Check(atlas.streamed, "streamed=true is recorded on the image");
for (std::uint32_t i = 0; i < kCount; ++i) atlas.buffer.value[i] = i;
atlas.Update(cmd, VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL);
Check(atlas.buffer.buffer != VK_NULL_HANDLE,
"streamed Update keeps the persistent staging buffer");
// UpdateRegion (the FontAtlas re-upload path) must also keep it.
atlas.UpdateRegion(cmd, VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, 0, 0, kW, kH);
Check(atlas.buffer.buffer != VK_NULL_HANDLE,
"streamed UpdateRegion keeps the persistent staging buffer");
Check(Device::deletionQueue.empty(),
"a streamed image enqueues nothing for deferred deletion");
SubmitWait(cmd);
Check(Device::validationErrorCount == 0,
"streamed upload raised no validation errors");
// Destroy frees the still-live persistent staging (the leak #114 names).
atlas.Destroy();
Check(atlas.buffer.buffer == VK_NULL_HANDLE,
"Destroy frees the streamed image's persistent staging buffer");
Check(Device::validationErrorCount == 0,
"streamed Destroy (freeing live staging) is validation-clean");
}
std::println("{}", failures == 0 ? "ALL PASS" : "FAILURES PRESENT");
return failures == 0 ? 0 : 1;
}