rgb_lcd: deprecate esp_lcd_color_space_t

2022-07-18 18:07:32 +08:00 · 2022-07-18 18:07:32 +08:00 · bc372f8f55
commit bc372f8f55
--- a/components/esp_lcd/include/esp_lcd_panel_vendor.h
+++ b/components/esp_lcd/include/esp_lcd_panel_vendor.h
@ -18,7 +18,10 @@ extern "C" {
 */
 typedef struct {
    int reset_gpio_num; /*!< GPIO used to reset the LCD panel, set to -1 if it's not used */
-    esp_lcd_color_space_t color_space; /*!< Set the color space used by the LCD panel */
+    union {
+        lcd_color_rgb_endian_t color_space; /*!< @deprecated Set RGB color space, please use rgb_endian instead */
+        lcd_color_rgb_endian_t rgb_endian;  /*!< Set RGB data endian: RGB or BGR */
+    };
    unsigned int bits_per_pixel;       /*!< Color depth, in bpp */
    struct {
        unsigned int reset_active_high: 1; /*!< Setting this if the panel reset is high level active */
--- a/components/esp_lcd/include/esp_lcd_types.h
+++ b/components/esp_lcd/include/esp_lcd_types.h
@ -1,10 +1,12 @@
 /*
- * SPDX-FileCopyrightText: 2021 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 #pragma once

+#include "hal/lcd_types.h"
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@ -12,14 +14,22 @@ extern "C" {
 typedef struct esp_lcd_panel_io_t *esp_lcd_panel_io_handle_t; /*!< Type of LCD panel IO handle */
 typedef struct esp_lcd_panel_t *esp_lcd_panel_handle_t;       /*!< Type of LCD panel handle */

+/** @cond */
 /**
- * @brief LCD color space type definition
+ * @brief LCD color space type definition (WRONG!)
+ * @deprecated RGB and BGR should belong to the same color space, but this enum take them both as two different color spaces.
+ *             If you want to use a enum to describe a color space, please use lcd_color_space_t instead.
 */
 typedef enum {
    ESP_LCD_COLOR_SPACE_RGB,        /*!< Color space: RGB */
    ESP_LCD_COLOR_SPACE_BGR,        /*!< Color space: BGR */
    ESP_LCD_COLOR_SPACE_MONOCHROME, /*!< Color space: monochrome */
-} esp_lcd_color_space_t;
+} esp_lcd_color_space_t __attribute__((deprecated));
+
+// Ensure binary compatibility with lcd_color_rgb_endian_t
+_Static_assert((lcd_color_rgb_endian_t)ESP_LCD_COLOR_SPACE_RGB == LCD_RGB_ENDIAN_RGB, "ESP_LCD_COLOR_SPACE_RGB is not compatible with LCD_RGB_ENDIAN_RGB");
+_Static_assert((lcd_color_rgb_endian_t)ESP_LCD_COLOR_SPACE_BGR == LCD_RGB_ENDIAN_BGR, "ESP_LCD_COLOR_SPACE_BGR is not compatible with LCD_RGB_ENDIAN_BGR");
+/** @endcond */

 #ifdef __cplusplus
 }
--- a/components/esp_lcd/src/esp_lcd_panel_nt35510.c
+++ b/components/esp_lcd/src/esp_lcd_panel_nt35510.c
@ -66,11 +66,11 @@ esp_err_t esp_lcd_new_panel_nt35510(const esp_lcd_panel_io_handle_t io, const es
        ESP_GOTO_ON_ERROR(gpio_config(&io_conf), err, TAG, "configure GPIO for RST line failed");
    }

-    switch (panel_dev_config->color_space) {
-    case ESP_LCD_COLOR_SPACE_RGB:
+    switch (panel_dev_config->rgb_endian) {
+    case LCD_RGB_ENDIAN_RGB:
        nt35510->madctl_val = 0;
        break;
-    case ESP_LCD_COLOR_SPACE_BGR:
+    case LCD_RGB_ENDIAN_BGR:
        nt35510->madctl_val |= LCD_CMD_BGR_BIT;
        break;
    default:
--- a/components/esp_lcd/src/esp_lcd_panel_ssd1306.c
+++ b/components/esp_lcd/src/esp_lcd_panel_ssd1306.c
@ -66,7 +66,6 @@ esp_err_t esp_lcd_new_panel_ssd1306(const esp_lcd_panel_io_handle_t io, const es
    esp_err_t ret = ESP_OK;
    ssd1306_panel_t *ssd1306 = NULL;
    ESP_GOTO_ON_FALSE(io && panel_dev_config && ret_panel, ESP_ERR_INVALID_ARG, err, TAG, "invalid argument");
-    ESP_GOTO_ON_FALSE(panel_dev_config->color_space == ESP_LCD_COLOR_SPACE_MONOCHROME, ESP_ERR_INVALID_ARG, err, TAG, "support monochrome only");
    ESP_GOTO_ON_FALSE(panel_dev_config->bits_per_pixel == 1, ESP_ERR_INVALID_ARG, err, TAG, "bpp must be 1");
    ssd1306 = calloc(1, sizeof(ssd1306_panel_t));
    ESP_GOTO_ON_FALSE(ssd1306, ESP_ERR_NO_MEM, err, TAG, "no mem for ssd1306 panel");
--- a/components/esp_lcd/src/esp_lcd_panel_st7789.c
+++ b/components/esp_lcd/src/esp_lcd_panel_st7789.c
@ -66,11 +66,11 @@ esp_err_t esp_lcd_new_panel_st7789(const esp_lcd_panel_io_handle_t io, const esp
        ESP_GOTO_ON_ERROR(gpio_config(&io_conf), err, TAG, "configure GPIO for RST line failed");
    }

-    switch (panel_dev_config->color_space) {
-    case ESP_LCD_COLOR_SPACE_RGB:
+    switch (panel_dev_config->rgb_endian) {
+    case LCD_RGB_ENDIAN_RGB:
        st7789->madctl_val = 0;
        break;
-    case ESP_LCD_COLOR_SPACE_BGR:
+    case LCD_RGB_ENDIAN_BGR:
        st7789->madctl_val |= LCD_CMD_BGR_BIT;
        break;
    default:
--- a/components/esp_lcd/test_apps/i2c_lcd/main/test_i2c_lcd_panel.c
+++ b/components/esp_lcd/test_apps/i2c_lcd/main/test_i2c_lcd_panel.c
@ -50,7 +50,6 @@ TEST_CASE("lcd_panel_with_i2c_interface_(ssd1306)", "[lcd]")
    esp_lcd_panel_handle_t panel_handle = NULL;
    esp_lcd_panel_dev_config_t panel_config = {
        .bits_per_pixel = 1,
-        .color_space = ESP_LCD_COLOR_SPACE_MONOCHROME,
        .reset_gpio_num = -1,
    };
    TEST_ESP_OK(esp_lcd_new_panel_ssd1306(io_handle, &panel_config, &panel_handle));
--- a/components/esp_lcd/test_apps/i80_lcd/main/test_i80_lcd_panel.c
+++ b/components/esp_lcd/test_apps/i80_lcd/main/test_i80_lcd_panel.c
@ -299,7 +299,7 @@ TEST_CASE("lcd_panel_i80_io_test", "[lcd]")
    esp_lcd_panel_handle_t panel_handle = NULL;
    esp_lcd_panel_dev_config_t panel_config = {
        .reset_gpio_num = TEST_LCD_RST_GPIO,
-        .color_space = ESP_LCD_COLOR_SPACE_RGB,
+        .rgb_endian = LCD_RGB_ENDIAN_RGB,
        .bits_per_pixel = 16,
    };

@ -419,7 +419,7 @@ TEST_CASE("lcd_panel_with_i80_interface_(st7789, 8bits)", "[lcd]")
    esp_lcd_panel_handle_t panel_handle = NULL;
    esp_lcd_panel_dev_config_t panel_config = {
        .reset_gpio_num = TEST_LCD_RST_GPIO,
-        .color_space = ESP_LCD_COLOR_SPACE_RGB,
+        .rgb_endian = LCD_RGB_ENDIAN_RGB,
        .bits_per_pixel = 16,
    };
    TEST_ESP_OK(esp_lcd_new_panel_st7789(io_handle, &panel_config, &panel_handle));
--- a/components/esp_lcd/test_apps/spi_lcd/main/test_spi_lcd_panel.c
+++ b/components/esp_lcd/test_apps/spi_lcd/main/test_spi_lcd_panel.c
@ -150,7 +150,7 @@ TEST_CASE("lcd_panel_with_8-line_spi_interface_(st7789)", "[lcd]")
    test_spi_lcd_common_initialize(&io_handle, NULL, NULL, 8, 8, true);
    esp_lcd_panel_dev_config_t panel_config = {
        .reset_gpio_num = TEST_LCD_RST_GPIO,
-        .color_space = ESP_LCD_COLOR_SPACE_RGB,
+        .rgb_endian = LCD_RGB_ENDIAN_RGB,
        .bits_per_pixel = 16,
    };
    TEST_ESP_OK(esp_lcd_new_panel_st7789(io_handle, &panel_config, &panel_handle));
@ -164,7 +164,7 @@ TEST_CASE("lcd_panel_with_8-line_spi_interface_(nt35510)", "[lcd]")
    test_spi_lcd_common_initialize(&io_handle, NULL, NULL, 16, 16, true);
    esp_lcd_panel_dev_config_t panel_config = {
        .reset_gpio_num = TEST_LCD_RST_GPIO,
-        .color_space = ESP_LCD_COLOR_SPACE_RGB,
+        .rgb_endian = LCD_RGB_ENDIAN_RGB,
        .bits_per_pixel = 16,
    };
    TEST_ESP_OK(esp_lcd_new_panel_nt35510(io_handle, &panel_config, &panel_handle));
@ -179,7 +179,7 @@ TEST_CASE("lcd_panel_with_1-line_spi_interface_(st7789)", "[lcd]")
    test_spi_lcd_common_initialize(&io_handle, NULL, NULL, 8, 8, false);
    esp_lcd_panel_dev_config_t panel_config = {
        .reset_gpio_num = TEST_LCD_RST_GPIO,
-        .color_space = ESP_LCD_COLOR_SPACE_RGB,
+        .rgb_endian = LCD_RGB_ENDIAN_RGB,
        .bits_per_pixel = 16,
    };
    TEST_ESP_OK(esp_lcd_new_panel_st7789(io_handle, &panel_config, &panel_handle));
--- a/components/hal/include/hal/lcd_types.h
+++ b/components/hal/include/hal/lcd_types.h
@ -20,6 +20,14 @@ extern "C" {
 typedef soc_periph_lcd_clk_src_t lcd_clock_source_t;
 #endif

+/**
+ * @brief RGB color endian
+ */
+typedef enum {
+    LCD_RGB_ENDIAN_RGB, /*!< RGB data endian: RGB */
+    LCD_RGB_ENDIAN_BGR, /*!< RGB data endian: BGR */
+} lcd_color_rgb_endian_t;
+
 #ifdef __cplusplus
 }
 #endif
--- a/docs/en/migration-guides/release-5.x/peripherals.rst
+++ b/docs/en/migration-guides/release-5.x/peripherals.rst
@ -254,6 +254,7 @@ LCD
 - The way to register RGB panel event callbacks has been moved from the :cpp:type:`esp_lcd_rgb_panel_config_t` into a separate API :cpp:func:`esp_lcd_rgb_panel_register_event_callbacks`. However, the event callback signature is not changed.
 - Previous ``relax_on_idle`` flag in :cpp:type:`esp_lcd_rgb_panel_config_t` has been renamed into :cpp:member:`esp_lcd_rgb_panel_config_t::refresh_on_demand`, which expresses the same meaning but with a clear name.
 - If the RGB LCD is created with the ``refresh_on_demand`` flag enabled, the driver won't start a refresh in the :cpp:func:`esp_lcd_panel_draw_bitmap`. Now you have to call :cpp:func:`esp_lcd_rgb_panel_refresh` to refresh the screen by yourself.
+- :cpp:type:`esp_lcd_color_space_t` is deprecated, please use :cpp:type:`lcd_color_space_t` to describe the color space, and use :cpp:type:`lcd_color_rgb_endian_t` to describe the data order of RGB color.

 .. only:: SOC_MCPWM_SUPPORTED

--- a/examples/peripherals/lcd/i2c_oled/main/i2c_oled_example_main.c
+++ b/examples/peripherals/lcd/i2c_oled/main/i2c_oled_example_main.c
@ -117,7 +117,6 @@ void app_main(void)
    esp_lcd_panel_handle_t panel_handle = NULL;
    esp_lcd_panel_dev_config_t panel_config = {
        .bits_per_pixel = 1,
-        .color_space = ESP_LCD_COLOR_SPACE_MONOCHROME,
        .reset_gpio_num = EXAMPLE_PIN_NUM_RST,
    };
    ESP_ERROR_CHECK(esp_lcd_new_panel_ssd1306(io_handle, &panel_config, &panel_handle));
--- a/examples/peripherals/lcd/i80_controller/main/i80_controller_example_main.c
+++ b/examples/peripherals/lcd/i80_controller/main/i80_controller_example_main.c
@ -211,7 +211,7 @@ void app_main(void)
    ESP_LOGI(TAG, "Install LCD driver of st7789");
    esp_lcd_panel_dev_config_t panel_config = {
        .reset_gpio_num = EXAMPLE_PIN_NUM_RST,
-        .color_space = ESP_LCD_COLOR_SPACE_RGB,
+        .rgb_endian = LCD_RGB_ENDIAN_RGB,
        .bits_per_pixel = 16,
    };
    ESP_ERROR_CHECK(esp_lcd_new_panel_st7789(io_handle, &panel_config, &panel_handle));
@ -226,7 +226,7 @@ void app_main(void)
    ESP_LOGI(TAG, "Install LCD driver of nt35510");
    esp_lcd_panel_dev_config_t panel_config = {
        .reset_gpio_num = EXAMPLE_PIN_NUM_RST,
-        .color_space = ESP_LCD_COLOR_SPACE_BGR,
+        .rgb_endian = LCD_RGB_ENDIAN_BGR,
        .bits_per_pixel = 16,
    };
    ESP_ERROR_CHECK(esp_lcd_new_panel_nt35510(io_handle, &panel_config, &panel_handle));
@ -244,7 +244,7 @@ void app_main(void)
    ESP_LOGI(TAG, "Install LCD driver of ili9341 (st7789 compatible)");
    esp_lcd_panel_dev_config_t panel_config = {
        .reset_gpio_num = EXAMPLE_PIN_NUM_RST,
-        .color_space = ESP_LCD_COLOR_SPACE_BGR,
+        .rgb_endian = LCD_RGB_ENDIAN_BGR,
        .bits_per_pixel = 16,
    };
    ESP_ERROR_CHECK(esp_lcd_new_panel_st7789(io_handle, &panel_config, &panel_handle));
--- a/examples/peripherals/lcd/spi_lcd_touch/main/spi_lcd_touch_example_main.c
+++ b/examples/peripherals/lcd/spi_lcd_touch/main/spi_lcd_touch_example_main.c
@ -208,9 +208,9 @@ void app_main(void)
    esp_lcd_panel_dev_config_t panel_config = {
        .reset_gpio_num = EXAMPLE_PIN_NUM_LCD_RST,
 #if CONFIG_EXAMPLE_LCD_CONTROLLER_ILI9341
-        .color_space = ESP_LCD_COLOR_SPACE_RGB,
+        .rgb_endian = LCD_RGB_ENDIAN_RGB,
 #elif CONFIG_EXAMPLE_LCD_CONTROLLER_GC9A01
-        .color_space = ESP_LCD_COLOR_SPACE_BGR,
+        .rgb_endian = LCD_RGB_ENDIAN_BGR,
 #endif
        .bits_per_pixel = 16,
    };
--- a/examples/peripherals/lcd/tjpgd/main/lcd_tjpgd_example_main.c
+++ b/examples/peripherals/lcd/tjpgd/main/lcd_tjpgd_example_main.c
@ -130,7 +130,7 @@ void app_main(void)
    esp_lcd_panel_handle_t panel_handle = NULL;
    esp_lcd_panel_dev_config_t panel_config = {
        .reset_gpio_num = EXAMPLE_PIN_NUM_RST,
-        .color_space = ESP_LCD_COLOR_SPACE_BGR,
+        .rgb_endian = LCD_RGB_ENDIAN_BGR,
        .bits_per_pixel = 16,
    };
    // Initialize the LCD configuration