Merge branch 'feat/isp_crop_driver_v5.5' into 'release/v5.5'

feat(isp): support Crop driver on p4 rev3 (v5.5)

See merge request espressif/esp-idf!43446

docs/doxygen/Doxyfile_esp32p4

@@ -39,6 +39,7 @@ INPUT += \
     $(PROJECT_PATH)/components/esp_driver_isp/include/driver/isp_bf.h \
     $(PROJECT_PATH)/components/esp_driver_isp/include/driver/isp_blc.h \
     $(PROJECT_PATH)/components/esp_driver_isp/include/driver/isp_lsc.h \
+    $(PROJECT_PATH)/components/esp_driver_isp/include/driver/isp_crop.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 \

docs/en/api-reference/peripherals/isp.rst

@@ -47,7 +47,7 @@ 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 -> isp_tail;
+        isp_header -> BLC -> BF -> LSC -> Demosaic -> CCM -> Gamma -> RGB2YUV -> SHARP -> isp_chs -> isp_yuv -> CROP -> isp_tail;
 
         LSC -> HIST
         Demosaic -> AWB
@@ -77,6 +77,7 @@ The ISP driver offers following services:
 - :ref:`isp-demosaic` - covers how to configure the Demosaic function.
 - :ref:`isp-gamma-correction` - covers how to enable and configure gamma correction.
 - :ref:`isp-sharpen` - covers how to configure the sharpening function.
+- :ref:`isp-crop` - covers how to enable and configure image cropping function.
 - :ref:`isp-callback` - covers how to hook user specific code to ISP driver event callback function.
 - :ref:`isp-thread-safety` - lists which APIs are guaranteed to be thread safe by the driver.
 - :ref:`isp-kconfig-options` - lists the supported Kconfig options that can bring different effects to the driver.
@@ -800,6 +801,51 @@ Calling :cpp:func:`esp_isp_sharpen_disable` does the opposite, that is, put the
 
 :cpp:func:`esp_isp_sharpen_configure` is allowed to be called even if the driver is in **init** state, but the sharpen configurations will only be taken into effect when in **enable** state.
 
+.. _isp-crop:
+
+ISP Image Crop Controller
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ISP image crop function can extract a specified region from the original image, reducing the amount of data for subsequent processing and improving processing efficiency. The crop function is executed at the end of the ISP pipeline and can output a smaller region than the input image.
+
+.. note::
+
+    The ISP image crop function is only available on ESP32-P4 revision 3.0 and above.
+
+Calling :cpp:func:`esp_isp_crop_configure` to configure the image crop function, you can take the following code as reference:
+
+.. code-block:: c
+
+    esp_isp_crop_config_t crop_config = {
+        .window = {
+            .top_left = {
+                .x = 100,  // Top-left X coordinate of crop region
+                .y = 100,  // Top-left Y coordinate of crop region
+            },
+            .btm_right = {
+                .x = 699,  // Bottom-right X coordinate of crop region
+                .y = 499,  // Bottom-right Y coordinate of crop region
+            }
+        }
+    };
+    ESP_ERROR_CHECK(esp_isp_crop_configure(isp_proc, &crop_config));
+    ESP_ERROR_CHECK(esp_isp_crop_enable(isp_proc));
+
+After calling :cpp:func:`esp_isp_crop_configure`, you need to enable the ISP image crop controller by calling :cpp:func:`esp_isp_crop_enable`. This function:
+
+* Switches the driver state from **init** to **enable**.
+
+Calling :cpp:func:`esp_isp_crop_disable` does the opposite, that is, put the driver back to the **init** state.
+
+:cpp:func:`esp_isp_crop_configure` is allowed to be called even if the driver is in **init** state, but the crop configurations will only be taken into effect when in **enable** state.
+
+.. note::
+
+    - The top-left coordinates (top_left) of the crop region must be smaller than the bottom-right coordinates (btm_right)
+    - The top-left coordinates (top_left) of the crop region must be even, and the bottom-right coordinates (btm_right) must be odd
+    - The crop region cannot exceed the boundaries of the original image
+    - Adjust the display medium (such as LCD) size according to the cropped resolution to ensure complete display and avoid black borders or stretching.
+
 
 .. _isp-callback:
 
@@ -927,6 +973,7 @@ API Reference
 .. include-build-file:: inc/isp_gamma.inc
 .. include-build-file:: inc/isp_hist.inc
 .. include-build-file:: inc/isp_color.inc
+.. include-build-file:: inc/isp_crop.inc
 .. include-build-file:: inc/isp_core.inc
 .. include-build-file:: inc/components/esp_driver_isp/include/driver/isp_types.inc
 .. include-build-file:: inc/components/hal/include/hal/isp_types.inc

docs/zh_CN/api-reference/peripherals/isp.rst

@@ -47,7 +47,7 @@ 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 -> 去马赛克 -> CCM -> gamma 校正 -> RGB 转 YUV -> 锐化 -> isp_chs -> isp_yuv -> 裁剪 -> isp_tail;
 
         LSC -> HIST
         去马赛克 -> AWB
@@ -77,6 +77,7 @@ ISP 驱动程序提供以下服务：
 - :ref:`isp-demosaic` - 涵盖如何配置去马赛克功能。
 - :ref:`isp-gamma-correction` - 涵盖如何启用和配置 gamma 校正。
 - :ref:`isp-sharpen` - 涵盖如何配置锐化功能。
+- :ref:`isp-crop` - 涵盖如何启用和配置图像裁剪功能。
 - :ref:`isp-callback` - 涵盖如何将用户特定代码挂接到 ISP 驱动事件回调。
 - :ref:`isp-thread-safety` - 列出了驱动程序中线程安全的 API。
 - :ref:`isp-kconfig-options` - 列出了支持的 Kconfig 选项，这些选项可以对驱动程序产生不同影响。
@@ -262,7 +263,7 @@ ISP AF 控制器
 
     使用连续统计时，AF 环境检测器将失效。
 
-.. code-block:: c
+.. code:: c
 
     esp_isp_af_config_t af_config = {
         .edge_thresh = 128,
@@ -399,7 +400,7 @@ ISP AE 控制器
 
 .. code-block:: c
 
-     esp_isp_ae_config_t ae_config = {
+    esp_isp_ae_config_t ae_config = {
         .sample_point = ISP_AE_SAMPLE_POINT_AFTER_DEMOSAIC,
     };
     isp_ae_ctlr_t ae_ctlr = NULL;
@@ -518,7 +519,6 @@ ISP BF 控制器
 
 调用 :cpp:func:`esp_isp_bf_disable` 函数会执行相反的操作，即将驱动程序恢复到 **init** 状态。
 
-
 .. _isp-blc:
 
 ISP BLC 控制器
@@ -801,6 +801,50 @@ ISP 锐化控制器
 
 即使驱动程序处于 **init** 状态，也可以调用 :cpp:func:`esp_isp_sharpen_configure`，但锐化配置只有在 **enable** 状态下才会生效。
 
+.. _isp-crop:
+
+ISP 图像裁剪控制器
+~~~~~~~~~~~~~~~~~~
+
+ISP 图像裁剪功能可以从原始图像中提取指定区域，减少后续处理的数据量，提高处理效率。裁剪功能在 ISP 流水线的末端执行，可以输出比输入图像更小的区域。
+
+.. note::
+
+    ISP 图像裁剪功能仅在 ESP32-P4 revision 3.0 及以上版本中可用。
+
+可调用 :cpp:func:`esp_isp_crop_configure` 函数配置图像裁剪功能，请参考以下代码：
+
+.. code-block:: c
+
+    esp_isp_crop_config_t crop_config = {
+        .window = {
+            .top_left = {
+                .x = 100,  // 裁剪区域左上角 X 坐标
+                .y = 100,  // 裁剪区域左上角 Y 坐标
+            },
+            .btm_right = {
+                .x = 699,  // 裁剪区域右下角 X 坐标
+                .y = 499,  // 裁剪区域右下角 Y 坐标
+            }
+        }
+    };
+    ESP_ERROR_CHECK(esp_isp_crop_configure(isp_proc, &crop_config));
+    ESP_ERROR_CHECK(esp_isp_crop_enable(isp_proc));
+
+调用 :cpp:func:`esp_isp_crop_configure` 后，需要通过调用 :cpp:func:`esp_isp_crop_enable` 来启用 ISP 图像裁剪控制器。此函数：
+
+* 将驱动程序状态从 **init** 切换到 **enable**。
+
+调用 :cpp:func:`esp_isp_crop_disable` 函数会执行相反的操作，即将驱动程序恢复到 **init** 状态。
+
+即使驱动程序处于 **init** 状态，也可以调用 :cpp:func:`esp_isp_crop_configure`，但裁剪配置只有在 **enable** 状态下才会生效。
+
+.. note::
+
+    - 裁剪区域的左上角坐标 (top_left) 必须小于右下角坐标 (btm_right)
+    - 裁剪区域的左上角坐标必须为偶数，右下角坐标必须为奇数
+    - 裁剪区域不能超出原始图像的边界
+    - 需根据裁剪后分辨率调整显示介质（如LCD）的尺寸，确保显示完整，避免出现黑边或拉伸现象。
 
 .. _isp-callback:
 
@@ -850,7 +894,7 @@ ISP AE 环境检测器启动后，将动态生成特定事件。若想在事件
 注册 ISP HIST 统计完成事件回调函数
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-ISP HIST 控制器完成亮度统计后，将动态生成特定事件。若想在统计完成时收到通知，请通过调用 :cpp:func:`esp_isp_hist_register_event_callbacks` 将目标函数挂挂接到中断服务程序。所有支持的事件回调函数可参见 :cpp:type:`esp_isp_hist_cbs_t`：
+ISP HIST 控制器完成亮度统计后，将动态生成特定事件。若想在统计完成时收到通知，请通过调用 :cpp:func:`esp_isp_hist_register_event_callbacks` 将目标函数挂接到中断服务程序。所有支持的事件回调函数可参见 :cpp:type:`esp_isp_hist_cbs_t`：
 
 - :cpp:member:`esp_isp_hist_cbs_t::on_statistics_done` 在完成亮度统计时设置回调函数。该函数原型在 :cpp:type:`esp_isp_hist_callback_t` 中声明。
 
@@ -928,6 +972,7 @@ API 参考
 .. include-build-file:: inc/isp_gamma.inc
 .. include-build-file:: inc/isp_hist.inc
 .. include-build-file:: inc/isp_color.inc
+.. include-build-file:: inc/isp_crop.inc
 .. include-build-file:: inc/isp_core.inc
 .. include-build-file:: inc/components/esp_driver_isp/include/driver/isp_types.inc
 .. include-build-file:: inc/components/hal/include/hal/isp_types.inc