From a9e38528916e6a4841e3693e9004a7245bdd0615 Mon Sep 17 00:00:00 2001
From: Stanislav N Mikhailov <stas@enso.pro>
Date: Mon, 23 Feb 2026 14:00:16 +0300
Subject: [PATCH] display: refine public display API header

---
 include/display/display.h | 40 +++++++++++++++++++--------------------
 1 file changed, 20 insertions(+), 20 deletions(-)

diff --git a/include/display/display.h b/include/display/display.h
index bfedc31..0972a6d 100644
--- a/include/display/display.h
+++ b/include/display/display.h
@@ -10,7 +10,7 @@ extern "C" {
 
 
 /* ============================================================
-   === Compile-time configuration
+   === Конфигурация времени компиляции
    ============================================================ */
 
 /*
@@ -26,24 +26,24 @@ extern "C" {
 
 
 /* ============================================================
-   === Modes
+   === Режимы
    ============================================================ */
 
 typedef enum
 {
     /*
      * SAFE:
-     * - swap управляется engine
-     * - нет tearing при 2 буферах
+     * - сменой буферов управляет движок
+     * - нет разрывов кадра при 2 буферах
      * - возможны блокировки
      */
     DISPLAY_MODE_SAFE = 0,
 
     /*
      * RAW:
-     * - swap управляется пользователем
-     * - engine не блокирует
-     * - tearing возможен
+     * - сменой буферов управляет пользователь
+     * - движок не блокирует
+     * - возможны разрывы кадра
      */
     DISPLAY_MODE_RAW
 
@@ -51,14 +51,14 @@ typedef enum
 
 
 /* ============================================================
-   === Callback
+   === Колбэк
    ============================================================ */
 
 typedef void (*display_frame_done_cb_t)(void);
 
 
 /* ============================================================
-   === Configuration
+   === Конфигурация
    ============================================================ */
 
 typedef struct
@@ -85,24 +85,24 @@ typedef struct
 
 
 /* ============================================================
-   === Lifecycle
+   === Жизненный цикл
    ============================================================ */
 
 /*
- * Инициализация display engine.
+ * Инициализация движка дисплея.
  * Выделяет буферы и инициализирует HW.
  */
 void display_init(const display_config_t* cfg);
 
 
 /* ============================================================
-   === Buffer access
+   === Доступ к буферам
    ============================================================ */
 
 /*
  * Буфер для рисования.
  *
- * SAFE + 1 buffer:
+ * SAFE + 1 буфер:
  *     может блокировать пока DMA активен.
  *
  * RAW:
@@ -118,11 +118,11 @@ uint16_t* display_get_scanout_buffer(void);
 
 
 /* ============================================================
-   === Buffer control (RAW mode only)
+   === Управление буферами (только режим RAW)
    ============================================================ */
 
 /*
- * Явная смена ролей draw/scanout.
+ * Явная смена ролей буферов рисования и вывода.
  *
  * Возвращает false если:
  *  - не RAW режим
@@ -133,11 +133,11 @@ bool display_swap_buffers(void);
 
 
 /* ============================================================
-   === Frame control
+   === Управление кадром
    ============================================================ */
 
 /*
- * Запуск передачи текущего scanout буфера.
+ * Запуск передачи текущего буфера вывода.
  *
  * Возвращает false если DMA активен.
  */
@@ -164,15 +164,15 @@ void display_poll(void);
 
 
 /* ============================================================
-   === IRQ hook
+   === Хук IRQ
    ============================================================ */
 
 /*
- * Должен вызываться из реального DMA IRQ handler.
+ * Должен вызываться из реального обработчика DMA IRQ.
  */
 void display_dma_irq_handler(void);
 
 
 #ifdef __cplusplus
 }
-#endif
\ No newline at end of file
+#endif