/**
 * @file LvScreenshot.hpp
 * @brief Board-independent LVGL screen capture. Renders any lv_obj (typically the active screen)
 *        into a tightly-packed RGB565 buffer via lv_snapshot_take(). Works with ANY LVGL 9 display
 *        driver -- partial-flush, full-frame, RGB panel -- because it re-renders the object tree
 *        rather than reading a panel framebuffer. Requires LV_USE_SNAPSHOT=1 in your lv_conf.h.
 */
#pragma once
#include <lvgl.h>
#include <cstddef>
#include <cstdint>

/** A captured image: tightly-packed RGB565 (2 bytes/pixel, row-major, no stride padding). */
struct LvScreenshot {
    uint8_t * data;    ///< RGB565 pixels; nullptr if capture failed. Free with lvScreenshotFree().
    uint32_t  width;   ///< pixels
    uint32_t  height;  ///< pixels
    size_t    length;  ///< bytes (== width * height * 2)
};

/**
 * @brief Capture @p obj and its subtree as tight RGB565 into @p out.
 * @warning The caller MUST hold the LVGL lock (LVGL is single-threaded) for the whole call.
 * @return true on success (then free @p out->data with lvScreenshotFree); false on failure (@p out
 *         is zeroed). Fails and warns at compile time if LV_USE_SNAPSHOT is disabled.
 */
bool lvScreenshotCapture(lv_obj_t * obj, LvScreenshot * out);

/**
 * @brief Capture whatever is visible on top: lv_layer_top() when it has children (an active overlay),
 *        otherwise lv_screen_active(). The caller MUST hold the LVGL lock.
 */
bool lvScreenshotCaptureTop(LvScreenshot * out);

/** @brief Free a buffer from a successful capture and zero the struct. Safe on a zeroed/failed one. */
void lvScreenshotFree(LvScreenshot * shot);