download_image()

std::optional< ImageData > MayaFlux::IO::download_image

(

const std::shared_ptr< Core::VKImage > &

image

)

Download pixel data from a GPU-resident VKImage into host ImageData.

Performs a blocking GPU->host transfer via TextureLoom::download_data, allocating a host buffer of the appropriate variant for the image format. The source image is restored to eShaderReadOnlyOptimal / eFragmentShader after the copy; pass a different restore layout/stage via the overload if the image was, for example, in a compute write state.

Multi-layer and multi-mip images are downloaded at layer 0, mip 0 only. Array and mipmap export is a separate concern.

Parameters

image

Fully-initialized VKImage to read from.

Returns

Populated ImageData, or std::nullopt on failure.

Definition at line 51 of file ImageExport.cpp.

{
    if (!image) {
        MF_ERROR(Journal::Component::IO, Journal::Context::FileIO,
            "download_image: null image");
        return std::nullopt;
    }
 
    const vk::Format vk_format = image->get_format();
    const auto format_opt = Portal::Graphics::TextureLoom::from_vulkan_format(vk_format);
    if (!format_opt) {
        MF_ERROR(Journal::Component::IO, Journal::Context::FileIO,
            "download_image: vk::Format {} has no ImageFormat mapping",
            vk::to_string(vk_format));
        return std::nullopt;
    }
 
    const ImageFormat format = *format_opt;
    const uint32_t channels = Portal::Graphics::TextureLoom::get_channel_count(format);
    if (channels == 0) {
        MF_ERROR(Journal::Component::IO, Journal::Context::FileIO,
            "download_image: zero channels for format {}",
            static_cast<int>(format));
        return std::nullopt;
    }
 
    const uint32_t width = image->get_width();
    const uint32_t height = image->get_height();
    if (width == 0 || height == 0) {
        MF_ERROR(Journal::Component::IO, Journal::Context::FileIO,
            "download_image: zero dimensions {}x{}", width, height);
        return std::nullopt;
    }
 
    const size_t pixel_count = static_cast<size_t>(width) * height;
    const size_t mip0_bytes = pixel_count * TextureLoom::get_bytes_per_pixel(format);
 
    ImageData result;
    result.width = width;
    result.height = height;
    result.channels = channels;
    result.format = format;
 
    if (!emplace_variant_for_format(result, format, pixel_count, channels)) {
        MF_ERROR(Journal::Component::IO, Journal::Context::FileIO,
            "download_image: unsupported bytes-per-element for format {}",
            static_cast<int>(format));
        return std::nullopt;
    }
 
    TextureLoom::instance().download_data_async(
        image,
        const_cast<void*>(result.data()),
        mip0_bytes);
 
    if (!result.is_consistent()) {
        MF_ERROR(Journal::Component::IO, Journal::Context::FileIO,
            "download_image: resulting ImageData failed is_consistent()");
        return std::nullopt;
    }
 
    MF_DEBUG(Journal::Component::IO, Journal::Context::FileIO,
        "download_image: {}x{}, {} channels, {} bytes",
        width, height, channels, mip0_bytes);
 
    return result;
}

References MayaFlux::IO::ImageData::channels, MayaFlux::IO::ImageData::data(), MayaFlux::Journal::FileIO, MayaFlux::IO::ImageData::format, MayaFlux::Portal::Graphics::TextureLoom::from_vulkan_format(), MayaFlux::Portal::Graphics::TextureLoom::get_channel_count(), MayaFlux::IO::ImageData::height, image, MayaFlux::Journal::IO, MayaFlux::IO::ImageData::is_consistent(), MF_DEBUG, MF_ERROR, MayaFlux::IO::ImageData::width, and width.

Referenced by download_texture_buffer(), save_image(), and MayaFlux::IO::IOManager::save_image().

Here is the call graph for this function:

Here is the caller graph for this function: