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)

The rectangle is cropped host-side from the full surface published by the per-window readback thread. The data is one frame late relative to the current render, not synchronously captured at call time. No GPU work and no staging buffer: the function reads the cached frame, validates the region against the swapchain extent, and copies the rows out. Safe to call without stalling the render pipeline. Returns failure if no frame has been captured yet or the region exceeds the surface bounds.

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 121 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();
    if (!display)
        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);
 
    uint32_t full_w = 0, full_h = 0;
    display->get_swapchain_extent(window_handle, full_w, full_h);
    if (full_w == 0 || full_h == 0)
        return s_fail;
 
    auto frame = display->get_last_frame(window_handle);
    if (!frame || frame->empty()) {
        MF_RT_ERROR(Journal::Component::Kakshya, Journal::Context::ContainerProcessing,
            "SurfaceUtils::readback_region: no captured frame for '{}'",
            window->get_create_info().title);
        return s_fail;
    }
 
    if (x_offset + pixel_width > full_w || y_offset + pixel_height > full_h) {
        MF_RT_ERROR(Journal::Component::Kakshya, Journal::Context::ContainerProcessing,
            "SurfaceUtils::readback_region: region {}x{} at ({},{}) exceeds surface {}x{} for '{}'",
            pixel_width, pixel_height, x_offset, y_offset, full_w, full_h,
            window->get_create_info().title);
        return s_fail;
    }
 
    const size_t full_row = static_cast<size_t>(full_w) * bpp;
    const size_t region_row = static_cast<size_t>(pixel_width) * bpp;
    const size_t byte_count = region_row * pixel_height;
 
    const size_t expected = full_row * full_h;
    if (frame->size() < expected) {
        MF_RT_ERROR(Journal::Component::Kakshya, Journal::Context::ContainerProcessing,
            "SurfaceUtils::readback_region: frame {} bytes, expected {} for '{}'",
            frame->size(), expected, window->get_create_info().title);
        return s_fail;
    }
 
    std::vector<uint8_t> region(byte_count);
    const uint8_t* base = frame->data()
        + static_cast<size_t>(y_offset) * full_row
        + static_cast<size_t>(x_offset) * bpp;
 
    for (uint32_t row = 0; row < pixel_height; ++row) {
        std::memcpy(region.data() + row * region_row,
            base + row * full_row,
            region_row);
    }
 
    fill_variant_from_raw(region.data(), byte_count, traits, out_variant);
 
    auto dims = make_pixel_dimensions(pixel_width, pixel_height, traits.channel_count);
    return { out_variant, dims, DataModality::IMAGE_COLOR };
}

References MayaFlux::Journal::ContainerProcessing, 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: