diff --git a/components/esp_driver_isp/include/driver/isp_ae.h b/components/esp_driver_isp/include/driver/isp_ae.h index dd4ff00c64..be8c471bdf 100644 --- a/components/esp_driver_isp/include/driver/isp_ae.h +++ b/components/esp_driver_isp/include/driver/isp_ae.h @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ @@ -19,7 +19,12 @@ extern "C" { * @brief AE controller config */ typedef struct { - isp_ae_sample_point_t sample_point; ///< The input data source, ISP_AE_SAMPLE_POINT_AFTER_DEMOSAIC: AE input data after demosaic, ISP_AE_SAMPLE_POINT_AFTER_GAMMA: AE input data after gamma + isp_ae_sample_point_t sample_point; /*!< AE sample point in the ISP pipeline. See TRM for more details. + * ISP_AE_SAMPLE_POINT_x: see TRM for more details + * + * Different sample points collect different color statistics, which can be used + * to match different hardware pipelines and AE tuning strategies. + */ isp_window_t window; ///< The sampling windows of AE int intr_priority; ///< The interrupt priority, range 0~3, if set to 0, the driver will try to allocate an interrupt with a relative low priority (1,2,3) } esp_isp_ae_config_t; diff --git a/components/esp_driver_isp/include/driver/isp_awb.h b/components/esp_driver_isp/include/driver/isp_awb.h index 070c3390e5..9e343b5f86 100644 --- a/components/esp_driver_isp/include/driver/isp_awb.h +++ b/components/esp_driver_isp/include/driver/isp_awb.h @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ @@ -20,12 +20,10 @@ extern "C" { */ typedef struct { isp_awb_sample_point_t sample_point; /*!< AWB sample point of the ISP pipeline. - * ISP_AWB_SAMPLE_POINT_BEFORE_CCM: sample before Color Correction Matrix(CCM). - * ISP_AWB_SAMPLE_POINT_AFTER_CCM: sample after Color Correction Matrix(CCM). - * If your camera support to set the manual gain to the RGB channels, - * then you can choose to sample before CCM, and set the gain to the camera registers. - * If your camera doesn't support the manual gain or don't want to change the camera configuration, - * then you can choose to sample after CCM, and set the calculated gain to the CCM + * ISP_AWB_SAMPLE_POINT_x: see TRM for more details + * + * Different sample points collect different color statistics, which can be used + * to match different hardware pipelines and AWB tuning strategies. */ isp_window_t window; /*!< Statistic main window of AWB. * Suggest to set it at the middle of the image and a little smaller than the whole image. diff --git a/components/esp_driver_isp/test_apps/isp/main/test_isp_driver.c b/components/esp_driver_isp/test_apps/isp/main/test_isp_driver.c index b456259466..39d0b121f3 100644 --- a/components/esp_driver_isp/test_apps/isp/main/test_isp_driver.c +++ b/components/esp_driver_isp/test_apps/isp/main/test_isp_driver.c @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ @@ -161,7 +161,7 @@ TEST_CASE("ISP AWB driver oneshot vs continuous test", "[isp]") uint32_t image_height = 600; /* Default parameters from helper macro */ esp_isp_awb_config_t awb_config = { - .sample_point = ISP_AWB_SAMPLE_POINT_AFTER_CCM, + .sample_point = ISP_AWB_SAMPLE_POINT_1, .window = { .top_left = {.x = image_width * 0.2, .y = image_height * 0.2}, .btm_right = {.x = image_width * 0.8, .y = image_height * 0.8}, @@ -274,7 +274,7 @@ TEST_CASE("ISP AE driver oneshot vs continuous test", "[isp]") isp_ae_ctlr_t ae_ctlr = NULL; /* Default parameters from helper macro */ esp_isp_ae_config_t ae_config = { - .sample_point = ISP_AE_SAMPLE_POINT_AFTER_DEMOSAIC, + .sample_point = ISP_AE_SAMPLE_POINT_0, }; isp_ae_result_t ae_res = {}; /* Create the ae controller */ @@ -319,7 +319,7 @@ TEST_CASE("ISP AE controller exhausted allocation", "[isp]") TEST_ESP_OK(esp_isp_new_processor(&isp_config, &isp_proc)); esp_isp_ae_config_t ae_config = { - .sample_point = ISP_AE_SAMPLE_POINT_AFTER_DEMOSAIC, + .sample_point = ISP_AE_SAMPLE_POINT_0, }; isp_ae_ctlr_t ae_ctrlr[ISP_LL_AE_CTLR_NUMS + 1] = {}; for (int i = 0; i < ISP_LL_AE_CTLR_NUMS; i++) { diff --git a/components/esp_hal_cam/include/hal/isp_types.h b/components/esp_hal_cam/include/hal/isp_types.h index 7825976e15..b1c084b541 100644 --- a/components/esp_hal_cam/include/hal/isp_types.h +++ b/components/esp_hal_cam/include/hal/isp_types.h @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2023-2026 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ @@ -108,8 +108,10 @@ typedef enum { * */ typedef enum { - ISP_AE_SAMPLE_POINT_AFTER_DEMOSAIC, ///< AE input data after demosaic - ISP_AE_SAMPLE_POINT_AFTER_GAMMA, ///< AE input data after gamma + ISP_AE_SAMPLE_POINT_0, ///< AE sample point 0, see TRM for more details + ISP_AE_SAMPLE_POINT_1, ///< AE sample point 1, see TRM for more details + ISP_AE_SAMPLE_POINT_AFTER_DEMOSAIC __attribute__((deprecated("Use ISP_AE_SAMPLE_POINT_0 instead"))) = ISP_AE_SAMPLE_POINT_0, ///< Deprecated alias of `ISP_AE_SAMPLE_POINT_0` + ISP_AE_SAMPLE_POINT_AFTER_GAMMA __attribute__((deprecated("Use ISP_AE_SAMPLE_POINT_1 instead"))) = ISP_AE_SAMPLE_POINT_1, ///< Deprecated alias of `ISP_AE_SAMPLE_POINT_1` } isp_ae_sample_point_t; /*--------------------------------------------------------------- @@ -137,8 +139,10 @@ typedef enum { * @brief ISP AWB sample point in the ISP pipeline */ typedef enum { - ISP_AWB_SAMPLE_POINT_BEFORE_CCM, ///< Sample AWB data before CCM (Color Correction Matrix) - ISP_AWB_SAMPLE_POINT_AFTER_CCM, ///< Sample AWB data after CCM (Color Correction Matrix) + ISP_AWB_SAMPLE_POINT_0, ///< AWB sample point 0, see TRM for more details + ISP_AWB_SAMPLE_POINT_1, ///< AWB sample point 1, see TRM for more details + ISP_AWB_SAMPLE_POINT_BEFORE_CCM __attribute__((deprecated("Use ISP_AWB_SAMPLE_POINT_0 instead"))) = ISP_AWB_SAMPLE_POINT_0, ///< Deprecated alias of `ISP_AWB_SAMPLE_POINT_0` + ISP_AWB_SAMPLE_POINT_AFTER_CCM __attribute__((deprecated("Use ISP_AWB_SAMPLE_POINT_1 instead"))) = ISP_AWB_SAMPLE_POINT_1, ///< Deprecated alias of `ISP_AWB_SAMPLE_POINT_1` } isp_awb_sample_point_t; /** diff --git a/docs/en/api-reference/peripherals/isp.rst b/docs/en/api-reference/peripherals/isp.rst index 575207bdfd..c35c4b33a0 100644 --- a/docs/en/api-reference/peripherals/isp.rst +++ b/docs/en/api-reference/peripherals/isp.rst @@ -47,13 +47,14 @@ ISP Pipeline isp_chs [label = "Contrast &\n Hue & Saturation", width = 150, height = 70]; isp_yuv [label = "YUV Limit\n YUB2RGB", width = 120, height = 70]; - isp_header -> BLC -> BF -> LSC -> Demosaic -> CCM -> Gamma -> RGB2YUV -> SHARP -> isp_chs -> isp_yuv -> CROP -> isp_tail; + isp_header -> BLC -> BF -> LSC -> Demosaic -> WBG -> CCM -> Gamma -> RGB2YUV -> SHARP -> isp_chs -> isp_yuv -> CROP -> isp_tail; LSC -> HIST + Demosaic -> WBG Demosaic -> AWB Demosaic -> AE Demosaic -> HIST - CCM -> AWB + WBG -> AWB Gamma -> AE RGB2YUV -> HIST RGB2YUV -> AF @@ -144,7 +145,7 @@ If an :cpp:type:`esp_isp_awb_config_t` configuration is specified, you can call uint32_t image_height = 600; /* The AWB configuration, please refer to the API comment for how to tune these parameters */ esp_isp_awb_config_t awb_config = { - .sample_point = ISP_AWB_SAMPLE_POINT_AFTER_CCM, + .sample_point = ISP_AWB_SAMPLE_POINT_1, ... }; ESP_ERROR_CHECK(esp_isp_new_awb_controller(isp_proc, &awb_config, &awb_ctlr)); @@ -161,7 +162,7 @@ If the configurations in :cpp:type:`esp_isp_ae_config_t` is specified, call :cpp .. code-block:: c esp_isp_ae_config_t ae_config = { - .sample_point = ISP_AE_SAMPLE_POINT_AFTER_DEMOSAIC, + .sample_point = ISP_AE_SAMPLE_POINT_0, ... }; isp_ae_ctlr_t ae_ctlr = NULL; @@ -342,7 +343,7 @@ Note that if you want to use the continuous statistics, you need to register the uint32_t image_height = 600; /* The AWB configuration, please refer to the API comment for how to tune these parameters */ esp_isp_awb_config_t awb_config = { - .sample_point = ISP_AWB_SAMPLE_POINT_AFTER_CCM, + .sample_point = ISP_AWB_SAMPLE_POINT_1, ... }; isp_awb_stat_result_t stat_res = {}; @@ -401,7 +402,7 @@ Note that if you want to use the continuous statistics, you need to register the .. code-block:: c esp_isp_ae_config_t ae_config = { - .sample_point = ISP_AE_SAMPLE_POINT_AFTER_DEMOSAIC, + .sample_point = ISP_AE_SAMPLE_POINT_0, }; isp_ae_ctlr_t ae_ctlr = NULL; ESP_ERROR_CHECK(esp_isp_new_ae_controller(isp_proc, &ae_config, &ae_ctlr)); diff --git a/docs/zh_CN/api-reference/peripherals/isp.rst b/docs/zh_CN/api-reference/peripherals/isp.rst index 25563d26a0..1790af45b8 100644 --- a/docs/zh_CN/api-reference/peripherals/isp.rst +++ b/docs/zh_CN/api-reference/peripherals/isp.rst @@ -47,13 +47,14 @@ ISP 流水线 isp_chs [label = "对比度 &\n 色调 & 饱和度", width = 150, height = 70]; isp_yuv [label = "YUV 限制\n YUB2RGB", width = 120, height = 70]; - isp_header -> BLC -> BF -> LSC -> 去马赛克 -> CCM -> gamma 校正 -> RGB 转 YUV -> 锐化 -> isp_chs -> isp_yuv -> 裁剪 -> isp_tail; + isp_header -> BLC -> BF -> LSC -> 去马赛克 -> WBG -> CCM -> gamma 校正 -> RGB 转 YUV -> 锐化 -> isp_chs -> isp_yuv -> 裁剪 -> isp_tail; LSC -> HIST + 去马赛克 -> WBG 去马赛克 -> AWB 去马赛克 -> AE 去马赛克 -> HIST - CCM -> AWB + WBG -> AWB gamma 校正 -> AE RGB 转 YUV -> HIST RGB 转 YUV -> AF @@ -144,7 +145,7 @@ ISP 自动白平衡 (AWB) 驱动程序需要由 :cpp:type:`esp_isp_awb_config_t` uint32_t image_height = 600; /* AWB 配置，请参考 API 注释来调整参数 */ esp_isp_awb_config_t awb_config = { - .sample_point = ISP_AWB_SAMPLE_POINT_AFTER_CCM, + .sample_point = ISP_AWB_SAMPLE_POINT_1, ... }; ESP_ERROR_CHECK(esp_isp_new_awb_controller(isp_proc, &awb_config, &awb_ctlr)); @@ -161,7 +162,7 @@ ISP 自动曝光 (AE) 驱动程序需要由 :cpp:type:`esp_isp_ae_config_t` 指 .. code-block:: c esp_isp_ae_config_t ae_config = { - .sample_point = ISP_AE_SAMPLE_POINT_AFTER_DEMOSAIC, + .sample_point = ISP_AE_SAMPLE_POINT_0, ... }; isp_ae_ctlr_t ae_ctlr = NULL; @@ -342,7 +343,7 @@ ISP AWB 控制器 uint32_t image_height = 600; /* AWB 配置，请参考 API 注释来调整参数 */ esp_isp_awb_config_t awb_config = { - .sample_point = ISP_AWB_SAMPLE_POINT_AFTER_CCM, + .sample_point = ISP_AWB_SAMPLE_POINT_1, ... }; isp_awb_stat_result_t stat_res = {}; @@ -401,7 +402,7 @@ ISP AE 控制器 .. code-block:: c esp_isp_ae_config_t ae_config = { - .sample_point = ISP_AE_SAMPLE_POINT_AFTER_DEMOSAIC, + .sample_point = ISP_AE_SAMPLE_POINT_0, }; isp_ae_ctlr_t ae_ctlr = NULL; ESP_ERROR_CHECK(esp_isp_new_ae_controller(isp_proc, &ae_config, &ae_ctlr)); diff --git a/examples/peripherals/isp/multi_pipelines/main/example_awb.c b/examples/peripherals/isp/multi_pipelines/main/example_awb.c index df09cabbc6..9b8b4f135a 100644 --- a/examples/peripherals/isp/multi_pipelines/main/example_awb.c +++ b/examples/peripherals/isp/multi_pipelines/main/example_awb.c @@ -39,7 +39,7 @@ static TaskHandle_t s_awb_task_handle = NULL; static void s_get_default_awb_config(esp_isp_awb_config_t *config, uint32_t h_res, uint32_t v_res) { // Set sample point: after CCM by default - config->sample_point = ISP_AWB_SAMPLE_POINT_AFTER_CCM; + config->sample_point = ISP_AWB_SAMPLE_POINT_1; // Configure window: middle 80% of image to avoid edge overexposure config->window.top_left.x = h_res * 0.2f;