VulkanStagedBuffer.cpp

Go to the documentation of this file.

#include "Engine/Renderer/VulkanStagedBuffer.h"
 
#include <cstring>
#include <optional>
#include <stdexcept>
#include <vulkan/vulkan.h>
 
#include "Engine/Core/ApplicationContext.h"
 
namespace EngineCore
{
 
#if !defined(HEADLESS) && !defined(COMPUTE_DEBUG)
    constexpr VkPipelineStageFlags2 STAGED_BUFFER_DST_STAGES =
        VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT | VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT | VK_PIPELINE_STAGE_2_VERTEX_SHADER_BIT;
#else
    constexpr VkPipelineStageFlags2 STAGED_BUFFER_DST_STAGES =
        VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT | VK_PIPELINE_STAGE_2_VERTEX_SHADER_BIT;
#endif
 
constexpr VkDeviceSize MIN_BUFFER_SIZE = 64;
 
VulkanStagedBuffer::VulkanStagedBuffer() = default;
 
void VulkanStagedBuffer::create(ApplicationContext* context, const VkDeviceSize size, const VkBufferUsageFlags usage, const bool persistentMapping)
{
    context_ = context;
    usePersistentMapping_ = persistentMapping;
    buffer.emplace(context);
    stagingBuffer.emplace(context);
    buffer->create(size, usage | VK_BUFFER_USAGE_TRANSFER_DST_BIT, VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT);
    stagingBuffer->create(size, VK_BUFFER_USAGE_TRANSFER_SRC_BIT, VK_MEMORY_PROPERTY_HOST_COHERENT_BIT | VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT);
 
    if (usePersistentMapping_) {
        // Persistently map staging buffer - avoids expensive map/unmap on every upload
        // HOST_COHERENT memory can stay mapped indefinitely per Vulkan spec
        stagingBuffer->map();
    }
}
 
void VulkanStagedBuffer::destroy()
{
    if (buffer) buffer->destroy();
    if (stagingBuffer) stagingBuffer->destroy();
}
 
VulkanStagedBufferSyncObjects VulkanStagedBuffer::upload(const ApplicationContext* context, const void* data, const VkDeviceSize size)
{
    // Full upload starting at offset 0
    return uploadPartial(context, data, size, 0);
}
 
VulkanStagedBufferSyncObjects VulkanStagedBuffer::uploadPartial(const ApplicationContext* context, const void* data, const VkDeviceSize size, const VkDeviceSize offset)
{
    if (usePersistentMapping_) {
        // Direct memcpy to persistently mapped staging buffer - no map/unmap overhead
        // Staging buffer uses HOST_COHERENT memory, so no flush needed
        void* mappedMemory = stagingBuffer->getMappedMemory();
        memcpy(mappedMemory, data, size);
    } else {
        // Traditional map/copy/unmap approach
        stagingBuffer->uploadData(data, size);
    }
 
    VulkanStagedBufferSyncObjects stagedBufferSyncObjects{};
 
    // Release barrier: Graphics queue releases ownership to Transfer queue
    // This barrier is recorded in the graphics command buffer before transfer begins
    VkBufferMemoryBarrier2 releaseBarrier{VK_STRUCTURE_TYPE_BUFFER_MEMORY_BARRIER_2};
    releaseBarrier.srcAccessMask = VK_ACCESS_2_SHADER_READ_BIT | VK_ACCESS_2_SHADER_WRITE_BIT;
    releaseBarrier.srcStageMask = VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT;
    releaseBarrier.dstAccessMask = VK_ACCESS_2_NONE;  // Release doesn't need dst access
    releaseBarrier.dstStageMask = VK_PIPELINE_STAGE_2_NONE;  // Release doesn't need dst stage
    releaseBarrier.srcQueueFamilyIndex = context->getVkGraphicsQueueFamilyIndex();
    releaseBarrier.dstQueueFamilyIndex = context->getVkTransferQueueFamilyIndex();
    releaseBarrier.buffer = buffer->getBuffer();
    releaseBarrier.offset = offset;  // Only barrier the region being updated
    releaseBarrier.size = size;
 
    // Acquire barrier: Graphics queue acquires ownership from Transfer queue
    // This barrier is recorded in the graphics command buffer after transfer completes
    VkBufferMemoryBarrier2 acquireBarrier{VK_STRUCTURE_TYPE_BUFFER_MEMORY_BARRIER_2};
    acquireBarrier.srcAccessMask = VK_ACCESS_2_NONE;  // Acquire doesn't need src access
    acquireBarrier.srcStageMask = VK_PIPELINE_STAGE_2_NONE;  // Acquire doesn't need src stage
    acquireBarrier.dstAccessMask = VK_ACCESS_2_SHADER_READ_BIT;
    acquireBarrier.dstStageMask = STAGED_BUFFER_DST_STAGES;
    acquireBarrier.srcQueueFamilyIndex = context->getVkTransferQueueFamilyIndex();
    acquireBarrier.dstQueueFamilyIndex = context->getVkGraphicsQueueFamilyIndex();
    acquireBarrier.buffer = buffer->getBuffer();
    acquireBarrier.offset = offset;  // Only barrier the region being updated
    acquireBarrier.size = size;
 
    stagedBufferSyncObjects.releaseBarrier = releaseBarrier;
    stagedBufferSyncObjects.acquireBarrier = acquireBarrier;
 
    BufferCopyObject copyObject{};
    copyObject.sourceBuffer = stagingBuffer->getBuffer();
    copyObject.destinationBuffer = buffer->getBuffer();
    copyObject.size = size;
    copyObject.dstOffset = offset;  // Copy to offset in destination buffer
    stagedBufferSyncObjects.copyObject = copyObject;
 
    return stagedBufferSyncObjects;
}
 
void VulkanStagedBuffer::setDebugName(const std::string& name, const std::optional<uint32_t> index ) {
    debugName_ = name + (index.has_value() ? std::to_string(index.value()) : "");
    buffer->setDebugName(name + " buffer" + (index.has_value() ? std::to_string(index.value()) : ""));
    stagingBuffer->setDebugName(name + " staging" + (index.has_value() ? std::to_string(index.value()) : ""));
}
 
bool VulkanStagedBuffer::ensureSize(VkDeviceSize requiredSize, VkBufferUsageFlags usage)
{
    // Enforce minimum size
    if (requiredSize < MIN_BUFFER_SIZE) {
        requiredSize = MIN_BUFFER_SIZE;
    }
 
    // Check if current buffer is sufficient
    if (buffer.has_value() && buffer->getBufferSize() >= requiredSize) {
        return false;
    }
 
    // Calculate new size with 2x growth strategy for amortized O(1) resizing
    // This avoids expensive buffer recreation on every small growth
    VkDeviceSize currentSize = buffer.has_value() ? buffer->getBufferSize() : 0;
    VkDeviceSize newSize = requiredSize;
 
    // If we have an existing buffer, grow by at least 2x to avoid frequent resizes
    if (currentSize > 0) {
        VkDeviceSize doubledSize = currentSize * 2;
        if (doubledSize > newSize) {
            newSize = doubledSize;
        }
    }
 
    // Cap at a reasonable maximum to avoid over-allocation (512 MB per buffer)
    // If required size exceeds cap, allocate exactly what's needed
    constexpr VkDeviceSize MAX_BUFFER_SIZE = 512 * 1024 * 1024;
    if (newSize > MAX_BUFFER_SIZE && requiredSize <= MAX_BUFFER_SIZE) {
        newSize = MAX_BUFFER_SIZE;
    }
 
    // Need to recreate - move old buffers to pending deletion
    if (buffer.has_value() && stagingBuffer.has_value()) {
        // Use aggregate initialization to avoid default-constructing VulkanBuffers
        // (VulkanBuffer default constructor requires Engine which may not be available in tests)
        pendingDeletions.push_back(PendingDeletion{
            std::move(buffer.value()),
            std::move(stagingBuffer.value()),
            DELETION_DELAY_FRAMES
        });
        buffer.reset();
        stagingBuffer.reset();
    }
 
    // Create new buffers with grown size
    buffer.emplace(context_);
    stagingBuffer.emplace(context_);
    buffer->create(newSize, usage | VK_BUFFER_USAGE_TRANSFER_DST_BIT, VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT);
    stagingBuffer->create(newSize, VK_BUFFER_USAGE_TRANSFER_SRC_BIT, VK_MEMORY_PROPERTY_HOST_COHERENT_BIT | VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT);
 
    if (usePersistentMapping_) {
        // Persistently map staging buffer for fast uploads
        stagingBuffer->map();
    }
 
    // Restore debug name if set
    if (!debugName_.empty()) {
        buffer->setDebugName(debugName_ + " buffer");
        stagingBuffer->setDebugName(debugName_ + " staging");
    }
 
    return true;
}
 
void VulkanStagedBuffer::processPendingDeletions()
{
    // Decrement frame counter and delete buffers that have waited long enough
    auto it = pendingDeletions.begin();
    while (it != pendingDeletions.end()) {
        if (it->framesRemaining == 0) {
            it->deviceBuffer.destroy();
            it->stagingBuffer.destroy();
            it = pendingDeletions.erase(it);
        } else {
            it->framesRemaining--;
            ++it;
        }
    }
}
 
VkDeviceSize VulkanStagedBuffer::getSize() const
{
    if (!buffer.has_value()) {
        return 0;
    }
    return buffer->getBufferSize();
}
 
} // namespace EngineCore