Merge branch 'refactor/reduce_bin_size_when_dsi_without_dma2d_v6.0' into 'release/v6.0'

feat(lcd): support draw bitmap hook function (v6.0)

See merge request espressif/esp-idf!44047

Author: suda-morris

components/esp_driver_i3c/i3c_master.c

@@ -768,7 +768,7 @@ static esp_err_t i3c_master_prepare_transaction(i3c_master_i2c_device_handle_t d
 
     // Check if async transaction requires DMA
     if (dev_handle->bus_handle->async_transaction && !dev_handle->bus_handle->dma_initialized) {
-        ESP_LOGE(TAG, "Async transaction requires DMA, please call i3c_master_bus_decorate_dma() first");
+        ESP_LOGE(TAG, "Async transaction requires DMA, please call `i3c_master_bus_decorate_dma()` first");
         return ESP_ERR_INVALID_STATE;
     }
 

components/esp_driver_parlio/src/parlio_tx.c

@@ -49,7 +49,7 @@ static esp_err_t parlio_tx_create_trans_queue(parlio_tx_unit_t *tx_unit, const p
 static esp_err_t parlio_destroy_tx_unit(parlio_tx_unit_t *tx_unit)
 {
     if (tx_unit->bs_handle) {
-        ESP_RETURN_ON_FALSE(false, ESP_ERR_INVALID_STATE, TAG, "please call parlio_tx_unit_undecorate_bitscrambler() before delete the tx unit");
+        ESP_RETURN_ON_FALSE(false, ESP_ERR_INVALID_STATE, TAG, "please call `parlio_tx_unit_undecorate_bitscrambler()` before deleting the tx unit");
     }
     if (tx_unit->intr) {
         ESP_RETURN_ON_ERROR(esp_intr_free(tx_unit->intr), TAG, "delete interrupt service failed");

components/esp_lcd/dsi/esp_lcd_panel_dpi.c

@@ -93,7 +93,6 @@ typedef struct {
     esp_lcd_video_timing_t video_timing;       /*!< Video timing */
     /// Extra configuration flags for MIPI DSI DPI panel
     struct extra_dpi_panel_flags {
-        uint32_t use_dma2d: 1; /*!< Use DMA2D to copy user buffer to the frame buffer when necessary */
         uint32_t disable_lp: 1;/*!< Disable low-power for DPI */
     } flags;                   /*!< Extra configuration flags */
 } esp_lcd_dpi_panel_config_t;
@@ -200,6 +199,92 @@ typedef struct {
  */
 esp_err_t esp_lcd_dpi_panel_register_event_callbacks(esp_lcd_panel_handle_t dpi_panel, const esp_lcd_dpi_panel_event_callbacks_t *cbs, void *user_ctx);
 
+/**
+ * @brief Type of draw bitmap hook data
+ */
+typedef struct {
+    void *dst_data;       /*!< Destination buffer (usually frame buffer) */
+    int dst_x_size;       /*!< Destination bitmap width */
+    int dst_y_size;       /*!< Destination bitmap height */
+    int dst_x_start;      /*!< Destination start x coordinate */
+    int dst_y_start;      /*!< Destination start y coordinate */
+    int dst_x_end;        /*!< Destination end x coordinate (exclusive) */
+    int dst_y_end;        /*!< Destination end y coordinate (exclusive) */
+    const void *src_data; /*!< Source bitmap data */
+    int src_x_size;       /*!< Source bitmap width */
+    int src_y_size;       /*!< Source bitmap height */
+    int src_x_start;      /*!< Source start x coordinate */
+    int src_y_start;      /*!< Source start y coordinate */
+    int src_x_end;        /*!< Source end x coordinate (exclusive) */
+    int src_y_end;        /*!< Source end y coordinate (exclusive) */
+    int bits_per_pixel;   /*!< Bits per pixel */
+    bool (*on_hook_end)(esp_lcd_panel_handle_t panel); /*!< Callback to be invoked when the hook completes its operation */
+} esp_lcd_draw_bitmap_hook_data_t;
+
+/**
+ * @brief draw bitmap hook function type for custom pixel processing operations
+ *
+ * This hook allows users to implement custom operations like scaling, rotation,
+ * color space conversion, etc. using hardware accelerators like PPA or DMA2D.
+ *
+ * @note The hook should ensure the synchronization of draw operations on its own.
+ *
+ * @param[in] panel LCD panel handle
+ * @param[in] hook_data Hook data
+ * @param[in] hook_ctx Hook context
+ * @return
+ *          - ESP_OK on success
+ *          - Other error codes on failure
+ */
+typedef esp_err_t (*esp_lcd_panel_draw_bitmap_hook_t)(esp_lcd_panel_handle_t panel, const esp_lcd_draw_bitmap_hook_data_t *hook_data, void* hook_ctx);
+
+/**
+ * @brief Type of LCD panel hooks
+ */
+typedef struct {
+    esp_lcd_panel_draw_bitmap_hook_t draw_bitmap_hook; /*!< Draw bitmap hook function */
+} esp_lcd_panel_hooks_t;
+
+/**
+ * @brief Register panel hooks to the DPI panel
+ *
+ * @note You can register panel hooks to implement custom operations like scaling, rotation, color space conversion, etc.
+ *       with hardware accelerators like PPA or DMA2D.
+ *       The hook will be overridden when this function is called multiple times.
+ *
+ * @param[in] dpi_panel LCD DPI panel handle, which is returned from esp_lcd_new_panel_dpi()
+ * @param[in] hooks Panel hooks
+ * @param[in] hook_ctx Hook context
+ * @return
+ *      - ESP_OK: Register hooks successfully
+ *      - Other error codes on failure
+ */
+esp_err_t esp_lcd_dpi_panel_register_hooks(esp_lcd_panel_handle_t dpi_panel, const esp_lcd_panel_hooks_t *hooks, void *hook_ctx);
+
+/**
+ * @brief Enable DMA2D for DPI panel
+ *
+ * @note The function will register a built-in DMA2D draw bitmap hook to perform draw bitmap operations using DMA2D.
+ *
+ * @param[in] dpi_panel LCD DPI panel handle, which is returned from esp_lcd_new_panel_dpi()
+ * @return
+ *      - ESP_OK: Enable DMA2D successfully
+ *      - Other error codes on failure
+ */
+esp_err_t esp_lcd_dpi_panel_enable_dma2d(esp_lcd_panel_handle_t dpi_panel);
+
+/**
+ * @brief Disable DMA2D for DPI panel
+ *
+ * @note The function will unregister the built-in DMA2D draw bitmap hook.
+ *
+ * @param[in] dpi_panel LCD DPI panel handle, which is returned from esp_lcd_new_panel_dpi()
+ * @return
+ *      - ESP_OK: Disable DMA2D successfully
+ *      - Other error codes on failure
+ */
+esp_err_t esp_lcd_dpi_panel_disable_dma2d(esp_lcd_panel_handle_t dpi_panel);
+
 #ifdef __cplusplus
 }
 #endif

components/esp_lcd/dsi/include/esp_lcd_mipi_dsi.h

@@ -58,6 +58,31 @@ esp_err_t esp_lcd_panel_del(esp_lcd_panel_handle_t panel);
  */
 esp_err_t esp_lcd_panel_draw_bitmap(esp_lcd_panel_handle_t panel, int x_start, int y_start, int x_end, int y_end, const void *color_data);
 
+/**
+ * @brief Draw partial source bitmap on LCD panel
+ *
+ * This function allows drawing a portion of a source bitmap to a specific area on the LCD panel.
+ *
+ * @param[in] panel LCD panel handle, which is created by other factory API like `esp_lcd_new_panel_st7789()`
+ * @param[in] x_start Start pixel index in the target frame buffer, on x-axis (x_start is included)
+ * @param[in] y_start Start pixel index in the target frame buffer, on y-axis (y_start is included)
+ * @param[in] x_end End pixel index in the target frame buffer, on x-axis (x_end is not included)
+ * @param[in] y_end End pixel index in the target frame buffer, on y-axis (y_end is not included)
+ * @param[in] color_data Source bitmap data
+ * @param[in] src_x_size Size of the source bitmap in the x-axis
+ * @param[in] src_y_size Size of the source bitmap in the y-axis
+ * @param[in] src_x_start Start pixel index in the source bitmap, on x-axis (src_x_start is included)
+ * @param[in] src_y_start Start pixel index in the source bitmap, on y-axis (src_y_start is included)
+ * @param[in] src_x_end End pixel index in the source bitmap, on x-axis (src_x_end is not included)
+ * @param[in] src_y_end End pixel index in the source bitmap, on y-axis (src_y_end is not included)
+ * @return
+ *          - ESP_OK on success
+ *          - ESP_ERR_INVALID_ARG if parameters are invalid
+ *          - ESP_ERR_NOT_SUPPORTED if this function is not supported by the panel
+ */
+esp_err_t esp_lcd_panel_draw_bitmap_2d(esp_lcd_panel_handle_t panel, int x_start, int y_start, int x_end, int y_end, const void *color_data,
+                                       size_t src_x_size, size_t src_y_size, int src_x_start, int src_y_start, int src_x_end, int src_y_end);
+
 /**
  * @brief Mirror the LCD panel on specific axis
  *

components/esp_lcd/include/esp_lcd_panel_ops.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2021-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -59,6 +59,27 @@ struct esp_lcd_panel_t {
      */
     esp_err_t (*draw_bitmap)(esp_lcd_panel_t *panel, int x_start, int y_start, int x_end, int y_end, const void *color_data);
 
+    /**
+     * @brief Draw partial bitmap on LCD panel
+     *
+     * @param[in] panel LCD panel handle, which is created by other factory API like `esp_lcd_new_panel_st7789()`
+     * @param[in] x_start Start pixel index in the target frame buffer, on x-axis (x_start is included)
+     * @param[in] y_start Start pixel index in the target frame buffer, on y-axis (y_start is included)
+     * @param[in] x_end End pixel index in the target frame buffer, on x-axis (x_end is not included)
+     * @param[in] y_end End pixel index in the target frame buffer, on y-axis (y_end is not included)
+     * @param[in] src_data Source bitmap data
+     * @param[in] src_x_size Size of the source bitmap in the x-axis
+     * @param[in] src_y_size Size of the source bitmap in the y-axis
+     * @param[in] src_x_start Start pixel index in the source bitmap, on x-axis (src_x_start is included)
+     * @param[in] src_y_start Start pixel index in the source bitmap, on y-axis (src_y_start is included)
+     * @param[in] src_x_end End pixel index in the source bitmap, on x-axis (src_x_end is not included)
+     * @param[in] src_y_end End pixel index in the source bitmap, on y-axis (src_y_end is not included)
+     * @return
+     *          - ESP_OK on success
+     */
+    esp_err_t (*draw_bitmap_2d)(esp_lcd_panel_t *panel, int x_start, int y_start, int x_end, int y_end,
+                                const void *src_data, size_t src_x_size, size_t src_y_size, int src_x_start, int src_y_start, int src_x_end, int src_y_end);
+
     /**
      * @brief Mirror the LCD panel on specific axis
      *

components/esp_lcd/interface/esp_lcd_panel_interface.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -188,6 +188,13 @@ esp_err_t esp_async_fbcpy(esp_async_fbcpy_handle_t mcp, esp_async_fbcpy_trans_de
     mcp->memcpy_done_cb = memcpy_done_cb;
     mcp->cb_args = cb_args;
 
+    // write back the user's draw buffer, so that the DMA can see the correct data
+    // Note, the user src buffer may not be contiguous, writeback from the head to the tail anyways
+    size_t bits_per_pixel = color_hal_pixel_format_fourcc_get_bit_depth(transaction->pixel_format_fourcc_id);
+    size_t copy_head = (transaction->src_offset_x + transaction->src_offset_y * transaction->src_buffer_size_x) * bits_per_pixel / 8;
+    size_t copy_size = (transaction->copy_size_x + transaction->copy_size_y * transaction->src_buffer_size_x) * bits_per_pixel / 8;
+    ESP_RETURN_ON_ERROR(esp_cache_msync((void *)transaction->src_buffer + copy_head, copy_size, ESP_CACHE_MSYNC_FLAG_DIR_C2M | ESP_CACHE_MSYNC_FLAG_UNALIGNED), TAG, "writeback draw buffer failed");
+
     // mount the data to the DMA descriptor
     async_memcpy_setup_dma2d_descriptor(mcp, transaction);
 

components/esp_lcd/src/esp_async_fbcpy.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2021-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -37,6 +37,16 @@ esp_err_t esp_lcd_panel_draw_bitmap(esp_lcd_panel_handle_t panel, int x_start, i
     return panel->draw_bitmap(panel, x_start, y_start, x_end, y_end, color_data);
 }
 
+esp_err_t esp_lcd_panel_draw_bitmap_2d(esp_lcd_panel_handle_t panel, int x_start, int y_start, int x_end, int y_end,
+                                       const void *color_data, size_t src_x_size, size_t src_y_size, int src_x_start, int src_y_start, int src_x_end, int src_y_end)
+{
+    ESP_RETURN_ON_FALSE(panel, ESP_ERR_INVALID_ARG, TAG, "invalid panel handle");
+    ESP_RETURN_ON_FALSE(panel->draw_bitmap_2d, ESP_ERR_NOT_SUPPORTED, TAG, "draw_bitmap_2d is not supported by this panel");
+    ESP_RETURN_ON_FALSE((x_start < x_end) && (y_start < y_end), ESP_ERR_INVALID_ARG, TAG, "start position must be smaller than end position");
+    ESP_RETURN_ON_FALSE((src_x_start < src_x_end) && (src_y_start < src_y_end), ESP_ERR_INVALID_ARG, TAG, "source start position must be smaller than end position");
+    return panel->draw_bitmap_2d(panel, x_start, y_start, x_end, y_end, color_data, src_x_size, src_y_size, src_x_start, src_y_start, src_x_end, src_y_end);
+}
+
 esp_err_t esp_lcd_panel_mirror(esp_lcd_panel_handle_t panel, bool mirror_x, bool mirror_y)
 {
     ESP_RETURN_ON_FALSE(panel, ESP_ERR_INVALID_ARG, TAG, "invalid panel handle");

components/esp_lcd/src/esp_lcd_panel_ops.c

@@ -9,5 +9,5 @@ endif()
 # In order for the cases defined by `TEST_CASE` to be linked into the final elf,
 # the component can be registered as WHOLE_ARCHIVE
 idf_component_register(SRCS ${srcs}
-                       PRIV_REQUIRES esp_lcd unity
+                       PRIV_REQUIRES esp_lcd unity esp_driver_ppa
                        WHOLE_ARCHIVE)

components/esp_lcd/test_apps/mipi_dsi_lcd/main/CMakeLists.txt

@@ -18,7 +18,7 @@
 #include "test_mipi_dsi_board.h"
 #include "esp_lcd_ek79007.h"
 
-IRAM_ATTR static bool test_rgb_panel_count_in_callback(esp_lcd_panel_handle_t panel, esp_lcd_dpi_panel_event_data_t *edata, void *user_ctx)
+IRAM_ATTR static bool test_dpi_panel_count_in_callback(esp_lcd_panel_handle_t panel, esp_lcd_dpi_panel_event_data_t *edata, void *user_ctx)
 {
     uint32_t *count = (uint32_t *)user_ctx;
     *count = *count + 1;
@@ -91,7 +91,7 @@ TEST_CASE("MIPI DSI draw bitmap (EK79007) IRAM Safe", "[mipi_dsi]")
 
     uint32_t callback_calls = 0;
     esp_lcd_dpi_panel_event_callbacks_t cbs = {
-        .on_refresh_done = test_rgb_panel_count_in_callback,
+        .on_refresh_done = test_dpi_panel_count_in_callback,
     };
     TEST_ESP_OK(esp_lcd_dpi_panel_register_event_callbacks(mipi_dpi_panel, &cbs, &callback_calls));