#pragma once

#include "esp_err.h"
#include "platform.h"

/**
 * @brief Initialize the LCD device and LVGL display pipeline.
 */
esp_err_t lcd_init_device(void);

/**
 * @brief Enable LCD backlight.
 */
void lcd_backlight_on(void);

/**
 * @brief Start the LVGL render loop and show the default screen.
 *
 * This function is blocking and is expected to run in a dedicated task.
 * Calling it while the render loop is already running is a no-op.
 */
void lcd_start_render_loop(void);

/**
 * @brief Request the running LVGL render loop to stop.
 *
 * This API is idempotent; calling it when the render loop is not running is safe.
 * `timeout_ms < 0` is invalid; `0` requests async stop; positive values wait
 * up to the bound and force-delete the render task on timeout.
 */
esp_err_t lcd_stop_render_loop(int timeout_ms);

/**
 * @brief Queue a LCD presentation request.
 *
 * This API is non-blocking and safe to call from non-LVGL tasks.
 */
esp_err_t lcd_request_presentation(const platform_lcd_presentation_request_t *request);

/**
 * @brief Queue a LCD presentation asset preload.
 *
 * This API is non-blocking and safe to call from non-LVGL tasks.
 */
esp_err_t lcd_preheat_presentation(const platform_lcd_presentation_request_t *request);

/**
 * @brief Read the LCD presentation completion counter.
 *
 * Incremented each time a finite asset-sequence presentation finishes its
 * configured cycles. Safe to call from non-LVGL tasks.
 */
uint32_t lcd_presentation_completion_count(void);

/**
 * @brief Block until the completion counter advances past @p since_count or
 *        @p timeout_ms elapses.
 *
 * Pair with a lcd_presentation_completion_count() snapshot taken before queuing
 * a finite asset sequence. Returns ESP_OK on completion, ESP_ERR_TIMEOUT on
 * timeout, ESP_ERR_INVALID_STATE if the LCD is not running or is stopping. A
 * zero timeout polls once. Safe to call from non-LVGL tasks; never call from
 * the LVGL render task.
 */
esp_err_t lcd_wait_presentation_completion(uint32_t since_count, uint32_t timeout_ms);