download_image_data()

void MayaFlux::Core::BackendResourceManager::download_image_data	(	std::shared_ptr< VKImage >	image,
		void *	data,
		size_t	size,
		const std::shared_ptr< Buffers::VKBuffer > &	staging = nullptr,
		bool	deferred = false,
		vk::ImageLayout	restore_layout = vk::ImageLayout::eShaderReadOnlyOptimal,
		vk::PipelineStageFlags	restore_stage = vk::PipelineStageFlagBits::eFragmentShader
	)

Download image data to a host pointer.

When staging is null, allocates and destroys a per-call staging buffer internally. When staging is supplied, it is used as-is and not destroyed after — the caller owns its lifetime.

When deferred is false (default), submits under a fence and blocks the calling thread on vkWaitForFences. This is non-blocking relative to the graphics queue (waitIdle is never called). When deferred is true and staging is supplied, records commands for deferred submission; the caller is responsible for flushing.

Parameters

image	Source image.
data	Destination host pointer, at least size bytes.
size	Byte count to read.
staging	Persistent host-visible buffer, or nullptr for per-call allocation.
deferred	Record for deferred submission (requires staging).
restore_layout	Layout to restore after the copy.
restore_stage	Pipeline stage that consumes the image after restore.

Definition at line 862 of file BackendResoureManager.cpp.

{
    if (!image || !data) {
        MF_ERROR(Journal::Component::Core, Journal::Context::GraphicsBackend,
            "download_image_data: invalid parameters");
        return;
    }
 
    std::shared_ptr<Buffers::VKBuffer> local_staging;
    Buffers::VKBuffer* active_staging {};
    if (!staging) {
        local_staging = std::make_shared<Buffers::VKBuffer>(
            size,
            Buffers::VKBuffer::Usage::STAGING,
            Kakshya::DataModality::IMAGE_COLOR);
        initialize_buffer(local_staging);
        active_staging = local_staging.get();
    } else {
        active_staging = staging.get();
    }
 
    auto record_command = [&](vk::CommandBuffer cmd) {
        vk::ImageMemoryBarrier barrier {};
        barrier.oldLayout = image->get_current_layout();
        barrier.newLayout = vk::ImageLayout::eTransferSrcOptimal;
        barrier.srcQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED;
        barrier.dstQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED;
        barrier.image = image->get_image();
        barrier.subresourceRange.aspectMask = image->get_aspect_flags();
        barrier.subresourceRange.baseMipLevel = 0;
        barrier.subresourceRange.levelCount = image->get_mip_levels();
        barrier.subresourceRange.baseArrayLayer = 0;
        barrier.subresourceRange.layerCount = image->get_array_layers();
        barrier.srcAccessMask = vk::AccessFlagBits::eShaderWrite | vk::AccessFlagBits::eShaderRead;
        barrier.dstAccessMask = vk::AccessFlagBits::eTransferRead;
 
        cmd.pipelineBarrier(
            vk::PipelineStageFlagBits::eFragmentShader | vk::PipelineStageFlagBits::eComputeShader,
            vk::PipelineStageFlagBits::eTransfer,
            vk::DependencyFlags {}, {}, {}, barrier);
 
        vk::BufferImageCopy region {};
        region.bufferOffset = 0;
        region.bufferRowLength = 0;
        region.bufferImageHeight = 0;
        region.imageSubresource.aspectMask = image->get_aspect_flags();
        region.imageSubresource.mipLevel = 0;
        region.imageSubresource.baseArrayLayer = 0;
        region.imageSubresource.layerCount = image->get_array_layers();
        region.imageOffset = vk::Offset3D { 0, 0, 0 };
        region.imageExtent = vk::Extent3D {
            image->get_width(),
            image->get_height(),
            image->get_depth()
        };
 
        cmd.copyImageToBuffer(
            image->get_image(),
            vk::ImageLayout::eTransferSrcOptimal,
            active_staging->get_buffer(),
            1, &region);
 
        barrier.oldLayout = vk::ImageLayout::eTransferSrcOptimal;
        barrier.newLayout = restore_layout;
        barrier.srcAccessMask = vk::AccessFlagBits::eTransferRead;
        barrier.dstAccessMask = vk::AccessFlagBits::eMemoryRead;
 
        cmd.pipelineBarrier(
            vk::PipelineStageFlagBits::eTransfer,
            restore_stage,
            vk::DependencyFlags {}, {}, {}, barrier);
    };
 
    if (deferred && staging) {
        record_deferred_commands(record_command);
        image->set_current_layout(restore_layout);
        return;
    }
 
    auto device = m_context.get_device();
 
    vk::CommandBuffer cmd = m_command_manager.begin_single_time_commands();
    record_command(cmd);
    cmd.end();
 
    vk::FenceCreateInfo fence_info {};
    vk::Fence fence = device.createFence(fence_info);
 
    vk::SubmitInfo submit_info {};
    submit_info.commandBufferCount = 1;
    submit_info.pCommandBuffers = &cmd;
 
    if (auto result = m_context.get_graphics_queue().submit(1, &submit_info, fence);
        result != vk::Result::eSuccess) {
        MF_ERROR(Journal::Component::Core, Journal::Context::GraphicsBackend,
            "download_image_data: queue submit failed: {}", vk::to_string(result));
        device.destroyFence(fence);
        m_command_manager.free_command_buffer(cmd);
        if (local_staging)
            cleanup_buffer(local_staging);
        return;
    }
 
    image->set_current_layout(restore_layout);
 
    if (auto result = device.waitForFences(1, &fence, VK_TRUE, UINT64_MAX);
        result != vk::Result::eSuccess) {
        MF_ERROR(Journal::Component::Core, Journal::Context::GraphicsBackend,
            "download_image_data: waitForFences failed: {}", vk::to_string(result));
    }
 
    vk::MappedMemoryRange range { active_staging->get_buffer_resources().memory, 0, VK_WHOLE_SIZE };
    if (auto result = device.invalidateMappedMemoryRanges(1, &range);
        result != vk::Result::eSuccess) {
        MF_ERROR(Journal::Component::Core, Journal::Context::GraphicsBackend,
            "download_image_data: invalidate failed: {}", vk::to_string(result));
    }
 
    void* mapped = active_staging->get_mapped_ptr();
    if (mapped) {
        std::memcpy(data, mapped, size);
    } else {
        MF_ERROR(Journal::Component::Core, Journal::Context::GraphicsBackend,
            "download_image_data: staging buffer has no mapped pointer");
    }
 
    device.destroyFence(fence);
    m_command_manager.free_command_buffer(cmd);
 
    if (local_staging)
        cleanup_buffer(local_staging);
 
    MF_DEBUG(Journal::Component::Core, Journal::Context::GraphicsBackend,
        "download_image_data: {} bytes from image {}x{}",
        size, image->get_width(), image->get_height());
}

References MayaFlux::Core::VKCommandManager::begin_single_time_commands(), cleanup_buffer(), cmd, MayaFlux::Journal::Core, device, fence, MayaFlux::Core::VKCommandManager::free_command_buffer(), MayaFlux::Core::VKContext::get_device(), MayaFlux::Core::VKContext::get_graphics_queue(), MayaFlux::Journal::GraphicsBackend, image, MayaFlux::Kakshya::IMAGE_COLOR, initialize_buffer(), m_command_manager, m_context, MF_DEBUG, MF_ERROR, record_deferred_commands(), and size.

Referenced by MayaFlux::Portal::Graphics::TextureLoom::download_data(), and MayaFlux::Core::BackendWindowHandler::setup_backend_service().

Here is the call graph for this function:

Here is the caller graph for this function: