readback_region()

MAYAFLUX_API DataAccess MayaFlux::Kakshya::readback_region	(	const std::shared_ptr< Core::Window > &	window,
		uint32_t	x_offset,
		uint32_t	y_offset,
		uint32_t	pixel_width,
		uint32_t	pixel_height,
		DataVariant &	out_variant
	)

Read a pixel rectangle from the last completed swapchain frame into a DataVariant whose element type matches the live swapchain format.

Format → DataVariant mapping: B8G8R8A8_SRGB / R8G8B8A8_SRGB / B8G8R8A8_UNORM / R8G8B8A8_UNORM → std::vector<uint8_t> (4 bytes/pixel) R16G16B16A16_SFLOAT → std::vector<uint16_t> (8 bytes/pixel, raw half-float bits) A2B10G10R10_UNORM → std::vector<uint32_t> (4 bytes/pixel, packed word) R32G32B32A32_SFLOAT → std::vector<float> (16 bytes/pixel)

"Last completed frame" semantics: the swapchain image whose in-flight fence has already signaled. Safe to call without stalling the render pipeline.

Dimensions on the returned DataAccess (IMAGE_COLOR convention): [0] SPATIAL_Y — pixel_height [1] SPATIAL_X — pixel_width [2] CHANNEL — channel_count derived from format traits

Parameters

window	Window whose surface is being read.
x_offset	Left edge of the pixel rectangle (inclusive).
y_offset	Top edge of the pixel rectangle (inclusive).
pixel_width	Width of the rectangle in pixels.
pixel_height	Height of the rectangle in pixels.
out_variant	Receives the typed pixel data. Left unchanged on failure.

Returns

DataAccess wrapping out_variant with IMAGE_COLOR modality. Returns a default-constructed DataAccess on failure.

Definition at line 122 of file SurfaceUtils.cpp.

{
    static std::vector<DataDimension> s_empty_dims;
    static DataVariant s_empty_var = std::vector<uint8_t> {};
    static DataAccess s_fail { s_empty_var, s_empty_dims, DataModality::UNKNOWN };
 
    auto* display = get_display_service();
    auto* buf_svc = get_buffer_service();
    if (!display || !buf_svc)
        return s_fail;
 
    const auto window_handle = std::static_pointer_cast<void>(window);
 
    const int raw_fmt = display->get_swapchain_format(window_handle);
    const auto vk_fmt = static_cast<vk::Format>(raw_fmt);
    const auto mf_fmt = Core::from_vk_format(vk_fmt);
    const auto traits = Core::get_surface_format_traits(mf_fmt);
    const uint32_t bpp = Core::vk_format_bytes_per_pixel(vk_fmt);
 
    const size_t byte_count = static_cast<size_t>(pixel_width) * pixel_height * bpp;
 
    auto staging = Buffers::create_staging_buffer(byte_count);
    if (!staging) {
        MF_RT_ERROR(Journal::Component::Kakshya, Journal::Context::ContainerProcessing,
            "SurfaceUtils::readback_region: staging allocation failed ({} bytes) for '{}'",
            byte_count, window->get_create_info().title);
        return s_fail;
    }
 
    const auto& res = staging->get_buffer_resources();
 
    buf_svc->invalidate_range(res.memory, 0, byte_count);
    void* mapped = buf_svc->map_buffer(res.memory, 0, byte_count);
    if (!mapped) {
        buf_svc->destroy_buffer(std::static_pointer_cast<void>(staging));
        MF_RT_ERROR(Journal::Component::Kakshya, Journal::Context::ContainerProcessing,
            "SurfaceUtils::readback_region: staging map failed for '{}'",
            window->get_create_info().title);
        return s_fail;
    }
 
    const bool ok = display->readback_swapchain_region(
        window_handle,
        mapped,
        x_offset, y_offset,
        pixel_width, pixel_height,
        byte_count);
 
    if (!ok) {
        buf_svc->unmap_buffer(res.memory);
        buf_svc->destroy_buffer(std::static_pointer_cast<void>(staging));
        MF_RT_ERROR(Journal::Component::Kakshya, Journal::Context::ContainerProcessing,
            "SurfaceUtils::readback_region: GPU copy failed for '{}'",
            window->get_create_info().title);
        return s_fail;
    }
 
    fill_variant_from_raw(mapped, byte_count, traits, out_variant);
    buf_svc->unmap_buffer(res.memory);
    buf_svc->destroy_buffer(std::static_pointer_cast<void>(staging));
 
    auto dims = make_pixel_dimensions(pixel_width, pixel_height, traits.channel_count);
    return { out_variant, dims, DataModality::IMAGE_COLOR };
}

References MayaFlux::Journal::ContainerProcessing, MayaFlux::Buffers::create_staging_buffer(), MayaFlux::Core::from_vk_format(), MayaFlux::Core::get_surface_format_traits(), IMAGE_COLOR, MayaFlux::Journal::Kakshya, MF_RT_ERROR, UNKNOWN, and MayaFlux::Core::vk_format_bytes_per_pixel().

Referenced by MayaFlux::Kakshya::WindowAccessProcessor::process().

Here is the call graph for this function:

Here is the caller graph for this function: