refactor(display): introduce begin/end paint lifecycle

include/display/display.h

@@ -31,30 +31,13 @@ extern "C" {
 
 typedef enum
 {
-    /*
-     * SAFE:
-     * - сменой буферов управляет движок
-     * - нет разрывов кадра при 2 буферах
-     * - возможны блокировки
-     */
+    /* Безопасный режим: движок сам управляет сменой буферов. */
     DISPLAY_MODE_SAFE = 0,
 
-    /*
-     * RAW:
-     * - сменой буферов управляет пользователь
-     * - движок не блокирует
-     * - возможны разрывы кадра
-     */
+    /* Ручной режим: приложению нужно управлять буферами самостоятельно. */
     DISPLAY_MODE_RAW
 
-} display_mode_t;
-
-
-/* ============================================================
-   === Колбэк
-   ============================================================ */
-
-typedef void (*display_frame_done_cb_t)(void);
+} display_mode_t; /* Тип режима работы подсистемы дисплея. */
 
 
 /* ============================================================
@@ -63,68 +46,43 @@ typedef void (*display_frame_done_cb_t)(void);
 
 typedef struct
 {
-    uint16_t width;
-    uint16_t height;
+    uint16_t width;  /* Ширина кадра в пикселях. */
+    uint16_t height; /* Высота кадра в пикселях. */
 
     /*
      * 1 или 2.
      * Должно быть <= DISPLAY_MAX_BUFFERS.
      */
-    uint8_t buffer_count;
+    uint8_t buffer_count; /* Количество используемых кадровых буферов. */
 
-    display_mode_t mode;
+    display_mode_t mode; /* Выбранный режим работы буферизации. */
 
-    /*
-     * Вызывается после завершения DMA
-     * через display_poll().
-     * Может быть NULL.
-     */
-    display_frame_done_cb_t frame_done_cb;
-
-} display_config_t;
+} display_config_t; /* Параметры инициализации подсистемы дисплея. */
 
 
 /* ============================================================
    === Жизненный цикл
    ============================================================ */
 
-/*
- * Инициализация движка дисплея.
- * Выделяет буферы и инициализирует HW.
- */
+/* Инициализирует подсистему дисплея и выделяет нужные ресурсы. */
 void display_init(const display_config_t* cfg);
 
 
 /* ============================================================
-   === Доступ к буферам
+   === Новый paint-контракт
    ============================================================ */
 
-/*
- * Неблокирующая попытка получить буфер для рисования.
- *
- * Возвращает NULL если буфер сейчас недоступен
- * (например, SAFE + 1 буфер и DMA активен).
- */
-uint16_t* display_try_acquire_draw_buffer(void);
+/* Неблокирующе начинает рисование кадра и возвращает буфер, либо NULL. */
+uint16_t* display_begin_paint_try(void);
+
+/* Блокирующе начинает рисование кадра и возвращает валидный буфер. */
+uint16_t* display_begin_paint_blocking(void);
+
+/* Завершает рисование кадра и запускает его отправку; false при ошибке контракта. */
+bool display_end_paint(void);
 
 
-/*
- * Блокирующее получение буфера для рисования.
- */
-uint16_t* display_acquire_draw_buffer_blocking(void);
-
-
-/*
- * Совместимость со старым API.
- * Начиная с текущей версии работает как non-blocking alias:
- * эквивалентно display_try_acquire_draw_buffer().
- */
-uint16_t* display_get_draw_buffer(void);
-
-
-/*
- * Буфер, который сейчас передаётся DMA.
- */
+/* Возвращает буфер, который в данный момент отправляется через DMA. */
 uint16_t* display_get_scanout_buffer(void);
 
 
@@ -132,14 +90,7 @@ uint16_t* display_get_scanout_buffer(void);
    === Управление буферами (только режим RAW)
    ============================================================ */
 
-/*
- * Явная смена ролей буферов рисования и вывода.
- *
- * Возвращает false если:
- *  - не RAW режим
- *  - меньше 2 буферов
- *  - DMA активен
- */
+/* Меняет местами draw/scanout буферы; false при недопустимых условиях. */
 bool display_swap_buffers(void);
 
 
@@ -147,40 +98,24 @@ bool display_swap_buffers(void);
    === Управление кадром
    ============================================================ */
 
-/*
- * Запуск передачи текущего буфера вывода.
- *
- * Возвращает false если DMA активен.
- */
+/* Запускает DMA-передачу текущего scanout-буфера. */
+/* Возвращает false, если DMA занят или сейчас открыта paint-секция. */
 bool display_submit(void);
 
 
-/*
- * true если DMA не активен.
- */
+/* Возвращает true, когда DMA неактивен и можно отправлять следующий кадр. */
 bool display_ready(void);
 
 
-/*
- * Блокирующее ожидание завершения DMA.
- */
+/* Блокирует выполнение до полного завершения текущей DMA-передачи. */
 void display_wait(void);
 
 
-/*
- * Обработка отложенного события завершения кадра.
- * Должна вызываться из основного цикла.
- */
-void display_poll(void);
-
-
 /* ============================================================
    === Хук IRQ
    ============================================================ */
 
-/*
- * Должен вызываться из реального обработчика DMA IRQ.
- */
+/* Вызывается из реального DMA IRQ-обработчика для уведомления движка. */
 void display_dma_irq_handler(void);