From b873befcd8606823954d1a5e47ea32853472a91e Mon Sep 17 00:00:00 2001 From: Armando Date: Mon, 11 Nov 2024 15:57:01 +0800 Subject: [PATCH] doc(isp): isp lsc programming guide --- .../esp_driver_isp/include/driver/isp_lsc.h | 10 ++--- docs/doxygen/Doxyfile_esp32p4 | 1 + docs/en/api-reference/peripherals/isp.rst | 40 ++++++++++++++++++- 3 files changed, 44 insertions(+), 7 deletions(-) diff --git a/components/esp_driver_isp/include/driver/isp_lsc.h b/components/esp_driver_isp/include/driver/isp_lsc.h index db32c74ff1..68ef165955 100644 --- a/components/esp_driver_isp/include/driver/isp_lsc.h +++ b/components/esp_driver_isp/include/driver/isp_lsc.h @@ -34,7 +34,7 @@ typedef struct { /** * @brief Helper function to allocate gain array for LSC * - * @param[in] proc Processor handle + * @param[in] isp_proc Processor handle * @param[in] gain_array Gain array to be allocated * @param[out] out_array_size_per_channel Array size * @@ -51,8 +51,8 @@ esp_err_t esp_isp_lsc_allocate_gain_array(isp_proc_handle_t isp_proc, esp_isp_ls * * @note After calling this API, LSC doesn't take into effect until `esp_isp_lsc_enable` is called * - * @param[in] proc Processor handle - * @param[in] config LSC configurations + * @param[in] isp_proc Processor handle + * @param[in] config LSC configurations * * @return * - ESP_OK On success @@ -65,7 +65,7 @@ esp_err_t esp_isp_lsc_configure(isp_proc_handle_t isp_proc, const esp_isp_lsc_co /** * @brief Enable ISP LSC function * - * @param[in] proc Processor handle + * @param[in] isp_proc Processor handle * * @return * - ESP_OK On success @@ -77,7 +77,7 @@ esp_err_t esp_isp_lsc_enable(isp_proc_handle_t isp_proc); /** * @brief Disable ISP LSC function * - * @param[in] proc Processor handle + * @param[in] isp_proc Processor handle * * @return * - ESP_OK On success diff --git a/docs/doxygen/Doxyfile_esp32p4 b/docs/doxygen/Doxyfile_esp32p4 index 3bea406c98..ebdf3a5619 100644 --- a/docs/doxygen/Doxyfile_esp32p4 +++ b/docs/doxygen/Doxyfile_esp32p4 @@ -34,6 +34,7 @@ INPUT += \ $(PROJECT_PATH)/components/esp_driver_isp/include/driver/isp_awb.h \ $(PROJECT_PATH)/components/esp_driver_isp/include/driver/isp_ccm.h \ $(PROJECT_PATH)/components/esp_driver_isp/include/driver/isp_bf.h \ + $(PROJECT_PATH)/components/esp_driver_isp/include/driver/isp_lsc.h \ $(PROJECT_PATH)/components/esp_driver_isp/include/driver/isp_demosaic.h \ $(PROJECT_PATH)/components/esp_driver_isp/include/driver/isp_sharpen.h \ $(PROJECT_PATH)/components/esp_driver_isp/include/driver/isp_core.h \ diff --git a/docs/en/api-reference/peripherals/isp.rst b/docs/en/api-reference/peripherals/isp.rst index 13e7ff499a..33d6ea2b7e 100644 --- a/docs/en/api-reference/peripherals/isp.rst +++ b/docs/en/api-reference/peripherals/isp.rst @@ -40,9 +40,9 @@ ISP Pipeline isp_chs [label = "Contrast &\n Hue & Saturation", width = 150, height = 70]; isp_yuv [label = "YUV Limit\nYUB2RGB", width = 120, height = 70]; - isp_header -> BF -> Demosaic -> CCM -> Gamma -> RGB2YUV -> SHARP -> isp_chs -> isp_yuv -> isp_tail; + isp_header -> BF -> LSC -> Demosaic -> CCM -> Gamma -> RGB2YUV -> SHARP -> isp_chs -> isp_yuv -> isp_tail; - BF -> HIST + LSC -> HIST Demosaic -> AWB Demosaic -> AE Demosaic -> HIST @@ -64,6 +64,7 @@ The ISP driver offers following services: - `Get AWB statistics in one shot or continuous way <#isp-awb-statistics>`__ - covers how to get AWB white patches statistics one-shot or continuously. - `Get histogram statistics in one shot or continuous way <#isp-hist-statistics>`__ - covers how to get histogram statistics one-shot or continuously. - `Enable BF function <#isp_bf>`__ - covers how to enable and configure BF function. +- `Enable LSC function <#isp_lsc>`__ - covers how to enable and configure LSC function. - `Configure CCM <#isp-ccm-config>`__ - covers how to configure the Color Correction Matrix. - `Configure Demosaic <#isp-demosaic>`__ - covers how to config the Demosaic function. - `Enable Gamma Correction <#isp-gamma-correction>`__ - covers how to enable and configure gamma correction. @@ -502,6 +503,40 @@ After calling :cpp:func:`esp_isp_bf_configure`, you need to enable the ISP BF pr Calling :cpp:func:`esp_isp_bf_disable` does the opposite, that is, put the driver back to the **init** state. + +.. _isp_lsc: + +ISP LSC Controller +~~~~~~~~~~~~~~~~~~ + +Lens Shading Correction (LSC) aims for the issues caused by the uneven refraction of light through the camera lens. + +Calling :cpp:func:`esp_isp_lsc_configure` to configure the LSC module to do the correction. The :cpp:type:`esp_isp_lsc_gain_array_t` is necessary for the hardware to do the correction related calculation. :cpp:func:`esp_isp_lsc_allocate_gain_array` is a helper function to help allocate proper size of memory for the gains. + +.. code-block:: c + + esp_isp_lsc_gain_array_t gain_array = {}; + size_t gain_size = 0; + ESP_ERROR_CHECK(esp_isp_lsc_allocate_gain_array(isp_proc, &gain_array, &gain_size)); + + esp_isp_lsc_config_t lsc_config = { + .gain_array = &gain_array, + }; + isp_lsc_gain_t gain_val = { + .decimal = 204, + .integer = 0, + }; + for (int i = 0; i < gain_size; i++) { + gain_array.gain_r[i].val = gain_val.val; + gain_array.gain_gr[i].val = gain_val.val; + gain_array.gain_gb[i].val = gain_val.val; + gain_array.gain_b[i].val = gain_val.val; + } + ESP_ERROR_CHECK(esp_isp_lsc_configure(isp_proc, &lsc_config)); + +After calling :cpp:func:`esp_isp_lsc_configure`, you need to enable the ISP LSC controller, by calling :cpp:func:`esp_isp_lsc_enable`. The LSC can be disabled by calling :cpp:func:`esp_isp_lsc_disable`. It's allowed to call :cpp:func:`esp_isp_lsc_configure` when the LSC isn't enabled, but the LSC function will only take effect when it's enabled. + + .. _isp-color: ISP Color Processor @@ -810,6 +845,7 @@ API Reference .. include-build-file:: inc/isp_ae.inc .. include-build-file:: inc/isp_awb.inc .. include-build-file:: inc/isp_bf.inc +.. include-build-file:: inc/isp_lsc.inc .. include-build-file:: inc/isp_ccm.inc .. include-build-file:: inc/isp_demosaic.inc .. include-build-file:: inc/isp_sharpen.inc