refactor(dsi): deprecate pixel_format configuration in favor of in_color_format

components/esp_lcd/dsi/esp_lcd_panel_dpi.c

@@ -177,7 +177,17 @@ esp_err_t esp_lcd_new_panel_dpi(esp_lcd_dsi_bus_handle_t bus, const esp_lcd_dpi_
     }
     ESP_RETURN_ON_FALSE(num_fbs <= DPI_PANEL_MAX_FB_NUM, ESP_ERR_INVALID_ARG, TAG, "num_fbs not within [1,%d]", DPI_PANEL_MAX_FB_NUM);
 
-    size_t bits_per_pixel = 0;
+    // by default, use RGB888 as the input color format
+    lcd_color_format_t in_color_format = LCD_COLOR_FMT_RGB888;
+    size_t bits_per_pixel = 24;
+    // the deprecated way to set the pixel format
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
+    bool has_pixel_fmt = panel_config->pixel_format != 0;
+    bool has_in_fmt = panel_config->in_color_format != 0;
+    ESP_RETURN_ON_FALSE(has_pixel_fmt ^ has_in_fmt, ESP_ERR_INVALID_ARG, TAG,
+                        "must set exactly one of pixel_format or in_color_format");
+    if (panel_config->pixel_format) {
         switch (panel_config->pixel_format) {
         case LCD_COLOR_PIXEL_FORMAT_RGB565:
             bits_per_pixel = 16;
@@ -190,15 +200,19 @@ esp_err_t esp_lcd_new_panel_dpi(esp_lcd_dsi_bus_handle_t bus, const esp_lcd_dpi_
             bits_per_pixel = 24;
             break;
         }
-    lcd_color_format_t in_color_format = COLOR_TYPE_ID(COLOR_SPACE_RGB, panel_config->pixel_format);
-    // if user sets the in_color_format, it can override the pixel format setting
+        in_color_format = COLOR_TYPE_ID(COLOR_SPACE_RGB, panel_config->pixel_format);
+    }
+#pragma GCC diagnostic pop
+    // the recommended way to set the input color format
     if (panel_config->in_color_format) {
+        in_color_format = panel_config->in_color_format;
+        // if user sets the in_color_format, it can override the pixel format setting
         color_space_pixel_format_t in_color_id = {
-            .color_type_id = panel_config->in_color_format,
+            .color_type_id = in_color_format,
         };
         bits_per_pixel = color_hal_pixel_format_get_bit_depth(in_color_id);
-        in_color_format = panel_config->in_color_format;
     }
+    // by default, out_color_format is the same as in_color_format (i.e. no color format conversion)
     lcd_color_format_t out_color_format = in_color_format;
     if (panel_config->out_color_format) {
         out_color_format = panel_config->out_color_format;

components/esp_lcd/dsi/include/esp_lcd_mipi_dsi.h

@@ -84,7 +84,6 @@ typedef struct {
     uint8_t virtual_channel;                   /*!< Virtual channel ID, index from 0 */
     mipi_dsi_dpi_clock_source_t dpi_clk_src;   /*!< MIPI DSI DPI clock source */
     uint32_t dpi_clock_freq_mhz;               /*!< DPI clock frequency in MHz */
-    lcd_color_rgb_pixel_format_t pixel_format; /*!< Pixel format that used by the MIPI LCD device */
     lcd_color_format_t in_color_format;        /*!< Format of the input data (color space and pixel format),
                                                     which is the format stored in the frame buffer */
     lcd_color_format_t out_color_format;       /*!< Format of the output data (color space and pixel format),
@@ -92,6 +91,8 @@ typedef struct {
     uint8_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 created */
     esp_lcd_video_timing_t video_timing;       /*!< Video timing */
+    /** @deprecated Duplicate of in_color_format; use in_color_format instead. */
+    lcd_color_rgb_pixel_format_t pixel_format __attribute__((deprecated("pixel_format is deprecated, use in_color_format instead"))); /*!< Pixel format that used by the MIPI LCD device */
     /// 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 */

components/hal/color_hal.c

@@ -29,6 +29,8 @@ uint32_t color_hal_pixel_format_get_bit_depth(color_space_pixel_format_t format)
     case COLOR_TYPE_ID(COLOR_SPACE_RGB, COLOR_PIXEL_RGB565):
     case COLOR_TYPE_ID(COLOR_SPACE_YUV, COLOR_PIXEL_YUV422):
         return 16;
+    case COLOR_TYPE_ID(COLOR_SPACE_RGB, COLOR_PIXEL_RGB666):
+        return 18;
     case COLOR_TYPE_ID(COLOR_SPACE_RGB, COLOR_PIXEL_RGB888):
     case COLOR_TYPE_ID(COLOR_SPACE_YUV, COLOR_PIXEL_YUV444):
         return 24;

components/hal/include/hal/lcd_types.h

@@ -32,7 +32,7 @@ typedef enum {
 } lcd_rgb_data_endian_t;
 
 /**
- * @brief LCD color space
+ * @brief The color space of the LCD input color data
  */
 typedef enum {
     LCD_COLOR_SPACE_RGB = COLOR_SPACE_RGB, /*!< Color space: RGB */

docs/en/migration-guides/release-6.x/6.0/peripherals.rst

@@ -173,7 +173,8 @@ LCD
 - The ``color_space`` and ``rgb_endian`` configuration options in the :cpp:type:`esp_lcd_panel_dev_config_t` structure have been replaced by the :cpp:member:`esp_lcd_panel_dev_config_t::rgb_ele_order` member, which sets the RGB element order. The corresponding types ``lcd_color_rgb_endian_t`` and ``esp_lcd_color_space_t`` have also been removed; use :cpp:type:`lcd_rgb_element_order_t` instead.
 - The ``esp_lcd_panel_disp_off`` function has been removed. Please use the :func:`esp_lcd_panel_disp_on_off` function to control display on/off.
 - The ``on_bounce_frame_finish`` member in :cpp:type:`esp_lcd_rgb_panel_event_callbacks_t` has been replaced by :cpp:member:`esp_lcd_rgb_panel_event_callbacks_t::on_frame_buf_complete`, which indicates that a complete frame buffer has been sent to the LCD controller.
-- The legacy I2C driver ``driver/i2c.h`` is deprecated since version 5.2. Starting from version 6.0, LCD driver based on legacy I2C is removed and LCD driver would only based on new I2C driver ``driver/i2c_master.h``.
+- The LCD IO layer driver for the I2C interface previously had two implementations, based on the new and legacy I2C master bus drivers. As the legacy I2C driver is being deprecated, support for it in the LCD IO layer has been removed. Only the APIs provided in ``driver/i2c_master.h`` are now used.
+- :cpp:member:`esp_lcd_dpi_panel_config_t::pixel_format` member is deprecated. It is recommended to only use :cpp:member:`esp_lcd_dpi_panel_config_t::in_color_format` to set the MIPI DSI driver's input pixel data format.
 
 SPI
 ---

docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst

@@ -173,7 +173,8 @@ LCD
 - :cpp:type:`esp_lcd_panel_dev_config_t` 结构体中的 ``color_space`` 和 ``rgb_endian`` 配置均已被 :cpp:member:`esp_lcd_panel_dev_config_t::rgb_ele_order` 成员取代，用来设置 RGB 元素的排列顺序。对应的类型 ``lcd_color_rgb_endian_t`` 和 ``esp_lcd_color_space_t`` 也已被移除，请使用 :cpp:type:`lcd_rgb_element_order_t` 替代。
 - ``esp_lcd_panel_disp_off`` 函数已被移除。请使用 :func:`esp_lcd_panel_disp_on_off` 函数来控制显示内容的开关。
 - :cpp:type:`esp_lcd_rgb_panel_event_callbacks_t` 中的 ``on_bounce_frame_finish`` 成员已被 :cpp:member:`esp_lcd_rgb_panel_event_callbacks_t::on_frame_buf_complete` 成员取代，用于指示一个完整的帧缓冲区已被发送给 LCD 控制器。
-- 基于旧版 I2C 的 LCD 驱动 ``driver/lcd.h`` 在 5.2 的版本中就已经被弃用。从 6.0 版本开始，基于旧版 I2C 的 LCD 驱动被完全移除并只使用基于 ``driver/i2c_master.h`` 的新驱动。
+- I2C 接口的 LCD IO 层驱动有两套实现，分别基于新、旧 I2C Master 总线驱动。由于旧版的 I2C Master 驱动逐渐被弃用，遂 LCD 的 IO 层也移除对旧版的支持，只使用 ``driver/i2c_master.h`` 中提供的 API。
+- :cpp:member:`esp_lcd_dpi_panel_config_t::pixel_format` 成员已经被废弃。建议仅使用 :cpp:member:`esp_lcd_dpi_panel_config_t::in_color_format` 来设定 MIPI DSI 驱动输入的像素数据格式。
 
 SPI
 ---