Merge branch 'doc/esp_lcd_class_diagram' into 'master'

RGB LCD multi-framebuffer support

Closes IDF-5309, IDF-5939, and IDF-6336

See merge request espressif/esp-idf!20975

components/esp_lcd/CMakeLists.txt

@@ -14,7 +14,7 @@ if(CONFIG_SOC_I2S_LCD_I80_VARIANT)
 endif()
 
 if(CONFIG_SOC_LCDCAM_SUPPORTED)
-    list(APPEND srcs "src/esp_lcd_panel_io_i80.c" "src/esp_lcd_rgb_panel.c")
+    list(APPEND srcs "src/esp_lcd_panel_io_i80.c" "src/esp_lcd_panel_rgb.c")
 endif()
 
 idf_component_register(SRCS ${srcs}

components/esp_lcd/README.md

@@ -0,0 +1,83 @@
+# esp_lcd Driver Design
+
+## Class Diagram
+
+`esp_lcd` driver focuses on two parts: panel driver and IO driver. The panel driver is a bunch of operations on the **frame-buffer**, no matter where the frame-buffer is located. The IO driver is mainly consumed by the controller-based LCD panel drivers (e.g. ST7789). Usually such LCD controller can support various IO interfaces (e.g. I80, SPI, I2C, etc). So we define an abstract interface for the IO driver.
+
+```mermaid
+classDiagram
+    class esp_lcd_panel_t {
+        <<interface>>
+        +reset() esp_err_t
+        +init() esp_err_t
+        +draw_bitmap(int x_start, int y_start, int x_end, int y_end, const void *color_data) esp_err_t
+        +mirror(bool x_axis, bool y_axis) esp_err_t
+        +swap_xy(bool swap_axes) esp_err_t
+        +set_gap(int x_gap, int y_gap) esp_err_t
+        +invert_color(bool invert_color_data) esp_err_t
+        +disp_on_off(bool on_off) esp_err_t
+    }
+
+    esp_lcd_rgb_panel_t --|> esp_lcd_panel_t : Inheritance
+    class esp_lcd_rgb_panel_t {
+        -int panel_id
+        -size_t data_width
+        -int disp_gpio
+        -intr_handle_t intr
+        -uint8_t* frame_buffer
+        -gdma_channel_handle_t gdma_channel
+        -dma_descriptor_t* dma_nodes
+        -on_vsync(void* user_data) bool
+    }
+
+    esp_lcd_panel_model_t --|> esp_lcd_panel_t : Inheritance
+    esp_lcd_panel_model_t "1" --> "1" esp_lcd_panel_io_t : Use
+    class esp_lcd_panel_model_t {
+        -esp_lcd_panel_io_t* io
+        -int reset_gpio_num
+    }
+
+    class esp_lcd_panel_io_t {
+        <<interface>>
+        +rx_param(int lcd_cmd, void *param, size_t param_size)
+        +tx_param(int lcd_cmd, const void *param, size_t param_size)
+        +tx_color(int lcd_cmd, const void *color, size_t color_size)
+    }
+
+    esp_lcd_panel_io_i2c_t --|> esp_lcd_panel_io_t : Inheritance
+    class esp_lcd_panel_io_i2c_t {
+        -int i2c_bus_id
+        -int ctrl_phase_cmd
+        -int ctrl_phase_data
+        -on_color_trans_done(void* user_data) bool
+    }
+
+    esp_lcd_panel_io_spi_t --|> esp_lcd_panel_io_t : Inheritance
+    class esp_lcd_panel_io_spi_t {
+        -spi_device_handle_t spi_dev
+        -int dc_gpio_num
+        -spi_transaction_t trans_worker
+        -on_color_trans_done(void* user_data) bool
+    }
+
+    esp_lcd_panel_io_i80_t --|> esp_lcd_panel_io_t : Inheritance
+    class esp_lcd_panel_io_i80_t {
+        -esp_lcd_i80_bus_t* bus
+        -int cs_gpio_num
+        -int dc_level
+        -size_t pclk_hz
+        -QueueHandle_t trans_queue
+        -QueueHandle_t done_queue
+        -on_color_trans_done(void* user_data) bool
+    }
+
+    esp_lcd_i80_bus_t "1" --> "1..*" esp_lcd_panel_io_i80_t : Has
+    class esp_lcd_i80_bus_t {
+        -int bus_id
+        -size_t data_width
+        -intr_handle_t intr
+        -gdma_cannel_handle_t dma_chan
+        -dma_descriptor_t* dma_nodes
+        -list_t i80_devices
+    }
+```

components/esp_lcd/include/esp_lcd_panel_rgb.h

@@ -118,6 +118,7 @@ typedef struct {
     size_t data_width;            /*!< Number of data lines */
     size_t bits_per_pixel;        /*!< Frame buffer color depth, in bpp, specially, if set to zero, it will default to `data_width`.
                                        When using a Serial RGB interface, this value could be different from `data_width` */
+    size_t num_fbs;               /*!< Number of screen-sized frame buffers that allocated by the driver. By default (set to either 0 or 1) only one frame buffer will be used. Maximum number of buffers are 3 */
     size_t bounce_buffer_size_px; /*!< If it's non-zero, the driver allocates two DRAM bounce buffers for DMA use.
                                        DMA fetching from DRAM bounce buffer is much faster than PSRAM frame buffer. */
     size_t sram_trans_align;      /*!< Alignment of buffers (frame buffer or bounce buffer) that allocated in SRAM */
@@ -133,7 +134,7 @@ typedef struct {
         uint32_t refresh_on_demand: 1;   /*!< If this flag is enabled, the host only refresh the frame buffer when `esp_lcd_panel_draw_bitmap` is called.
                                               This is useful when the LCD screen has a GRAM and can refresh the LCD by itself. */
         uint32_t fb_in_psram: 1;         /*!< If this flag is enabled, the frame buffer will be allocated from PSRAM, preferentially */
-        uint32_t double_fb: 1;           /*!< If this flag is enabled, the driver will allocate two screen sized frame buffer */
+        uint32_t double_fb: 1;           /*!< If this flag is enabled, the driver will allocate two screen sized frame buffer, same as num_fbs=2 */
         uint32_t no_fb: 1;               /*!< If this flag is enabled, the driver won't allocate frame buffer.
                                               Instead, user should fill in the bounce buffer manually in the `on_bounce_empty` callback */
         uint32_t bb_invalidate_cache: 1; /*!< If this flag is enabled, in bounce back mode we'll do a cache invalidate on the read data, freeing the cache.