# 图像信号处理器 (ISP)

[English]

## 简介

ESP32-P4 内含图像信号处理器 (ISP)，是由众多图像处理算法组成的流水线。ISP 从 DVP 摄像头、MIPI-CSI 摄像头或系统存储处接收图像数据，并通过 DMA 将处理后的图像数据写入系统存储。ISP 需要与其他摄像头控制器模块协同工作，无法独立工作。

## 术语表

- MIPI-CSI：符合 MIPI 规范的高速串行摄像头接口

- DVP：数字视频并行接口，通常由 vsync、hsync、de 和 data 信号组成

- RAW：直接从图像传感器输出的未处理数据，通常分为 R、Gr、Gb 和 B 四个通道，按位宽分为 RAW8、RAW10、RAW12 等不同格式

- RGB：由红、绿、蓝三种颜色组成的彩色图像格式，按每种颜色的位宽分为 RGB888、RGB565 等格式

- YUV：由亮度和色度组成的彩色图像格式，按数据排列方式分为 YUV444、YUV422、YUV420 等格式

- AF：自动对焦

- AWB：自动白平衡

- AE：自动曝光

- HIST：直方图

- BF：拜耳域降噪

- BLC：黑电平校正

- LSC：镜头阴影校正

- CCM：色彩校正矩阵

## ISP 流水线

ISP 流水线

## 功能概述

ISP 驱动程序提供以下服务：

- 资源分配 - 涵盖如何通过正确的配置来分配 ISP 资源，以及完成工作后如何回收资源。

- 启用和禁用 ISP - 涵盖如何启用和禁用 ISP 处理器。

- 单次与连续 AF 数据统计 - 涵盖如何单次或连续获取 AF 统计信息。

- 单次与连续 AWB 数据统计 - 涵盖如何单次或连续获取 AWB 白块统计信息。

- 单次与连续 AE 数据统计 - 涵盖如何单次或连续获取 AE 统计信息。

- 单次与连续直方图数据统计 - 涵盖如何单次或连续获取直方图统计信息。

- ISP BF 控制器 - 涵盖如何启用和配置 BF 功能。

- ISP BLC 控制器 - 涵盖如何启用和配置 BLC 功能。

- ISP LSC 控制器 - 涵盖如何启用和配置 LSC 功能。

- 配置 CCM - 涵盖如何配置 CCM。

- ISP 去马赛克控制器 - 涵盖如何配置去马赛克功能。

- 启用 gamma 校正 - 涵盖如何启用和配置 gamma 校正。

- ISP 锐化控制器 - 涵盖如何配置锐化功能。

- ISP 图像裁剪控制器 - 涵盖如何启用和配置图像裁剪功能。

- 注册事件回调函数 - 涵盖如何将用户特定代码挂接到 ISP 驱动事件回调。

- 线程安全 - 列出了驱动程序中线程安全的 API。

- Kconfig 选项 - 列出了支持的 Kconfig 选项，这些选项可以对驱动程序产生不同影响。

- IRAM 安全 - 描述了当 cache 被禁用时，如何使 ISP 中断和控制功能正常工作。

### 资源分配

#### 安装 ISP 驱动程序

ISP 驱动程序需要由 `esp_isp_processor_cfg_t` 指定配置。

指定 `esp_isp_processor_cfg_t` 中的配置后，可以调用 `esp_isp_new_processor()` 来分配和初始化 ISP 处理器。如果函数运行正常，将返回一个 ISP 处理器句柄。请参考以下代码：

    esp_isp_processor_cfg_t isp_config = {
        .clk_src = ISP_CLK_SRC_DEFAULT,
        ...
    };

    isp_proc_handle_t isp_proc = NULL;
    ESP_ERROR_CHECK(esp_isp_new_processor(&isp_config, &isp_proc));

使用上述句柄，可以启用/禁用 ISP 驱动程序，也可以安装其他 ISP 模块。

备注

如果将 MIPI CSI 或 ISP_DVP 用作摄像头控制器，则必须使用 ISP 外设。因此即便无需使用 ISP 功能，也要调用 `esp_isp_new_processor()` 函数安装 ISP 驱动程序。

如果无需使用 ISP 功能，也可以设置 `esp_isp_processor_cfg_t::bypass_isp`，使 ISP 驱动程序绕过 ISP 流水线，仅启用必要的功能。

#### 安装 ISP 自动对焦 (AF) 驱动程序

ISP 自动对焦 (AF) 驱动程序需要由 `esp_isp_af_config_t` 指定配置。

指定 `esp_isp_af_config_t` 中的配置后，可以调用 `esp_isp_new_af_controller()` 来分配和初始化 ISP AF 控制器。如果函数运行正常，将返回一个 ISP AF 控制器句柄。请参考以下代码：

    esp_isp_af_config_t af_config = {
        .edge_thresh = 128,
    };
    isp_af_ctlr_t af_ctrlr = NULL;
    ESP_ERROR_CHECK(esp_isp_new_af_controller(isp_proc, &af_config, &af_ctrlr));

使用上述句柄，可以启用/禁用 ISP AF 驱动程序，也可以安装 ISP AF 环境检测模块。

#### 安装 ISP 自动白平衡 (AWB) 驱动程序

ISP 自动白平衡 (AWB) 驱动程序需要由 `esp_isp_awb_config_t` 指定配置。

指定 `esp_isp_awb_config_t` 中的配置后，可以调用 `esp_isp_new_awb_controller()` 来分配和初始化 ISP AWB 控制器。如果函数运行正常，将返回一个 ISP AWB 控制器句柄。请参考以下代码：

    isp_awb_ctlr_t awb_ctlr = NULL;
    uint32_t image_width = 800;
    uint32_t image_height = 600;
    /* AWB 配置，请参考 API 注释来调整参数 */
    esp_isp_awb_config_t awb_config = {
        .sample_point = ISP_AWB_SAMPLE_POINT_AFTER_CCM,
        ...
    };
    ESP_ERROR_CHECK(esp_isp_new_awb_controller(isp_proc, &awb_config, &awb_ctlr));

其他 AWB API 和 AWB 方案也需要此步骤中创建的 AWB 句柄。

#### 安装 ISP 自动曝光 (AE) 驱动程序

ISP 自动曝光 (AE) 驱动程序需要由 `esp_isp_ae_config_t` 指定配置。

指定 `esp_isp_ae_config_t` 中的配置后，可以调用 `esp_isp_new_ae_controller()` 来分配和初始化 ISP AE 控制器。如果函数运行正常，将返回一个 ISP AE 控制器句柄。请参考以下代码：

    esp_isp_ae_config_t ae_config = {
        .sample_point = ISP_AE_SAMPLE_POINT_AFTER_DEMOSAIC,
        ...
    };
    isp_ae_ctlr_t ae_ctlr = NULL;
    ESP_ERROR_CHECK(esp_isp_new_ae_controller(isp_proc, &ae_config, &ae_ctlr));

使用上述句柄，可以启用/禁用 ISP AE 驱动程序，也可以设置 ISP AE 环境检测器。

#### 安装 ISP 直方图 (HIST) 驱动程序

ISP 直方图 (HIST) 驱动程序需要由 `esp_isp_hist_config_t` 指定配置。

指定 `esp_isp_hist_config_t` 中的配置后，可以调用 `esp_isp_new_hist_controller()` 来分配和初始化 ISP 直方图控制器。如果此函数运行正常，将返回一个 ISP HIST 控制器句柄。请参考以下代码。

- 所有子窗口权重的十进制值之和应为 256，否则统计数据将较小，并且整数值应为 0。

- 所有 RGB 系数的十进制值之和应为 256，否则统计数据将较小，并且整数值应为 0。

- segment_threshold 必须在 0~255 之间且按顺序排列。

    esp_isp_hist_config_t hist_cfg = {
        .segment_threshold = {16, 32, 48, 64, 80, 96, 112, 128, 144, 160, 176, 192, 208, 224, 240},
        .hist_mode = ISP_HIST_SAMPLING_RGB,
        .rgb_coefficient.coeff_r = {
            .integer = 0,
            .decimal = 86,
        },
        .rgb_coefficient.coeff_g = {
            .integer = 0,
            .decimal = 85,
        },
        .rgb_coefficient.coeff_b = {
            .integer = 0,
            .decimal = 85,
        },
        .window_weight = {
            {{16, 0}}, {{10, 0}}, {{10, 0}}, {{10, 0}}, {{10, 0}},
            {{10, 0}}, {{10, 0}}, {{10, 0}}, {{10, 0}}, {{10, 0}},
            {{10, 0}}, {{10, 0}}, {{10, 0}}, {{10, 0}}, {{10, 0}},
            {{10, 0}}, {{10, 0}}, {{10, 0}}, {{10, 0}}, {{10, 0}},
            {{10, 0}}, {{10, 0}}, {{10, 0}}, {{10, 0}}, {{10, 0}},
        },
    };
    isp_hist_ctlr_t hist_ctlr_ctlr = NULL;
    ESP_ERROR_CHECK(esp_isp_new_hist_controller(isp_proc, &hist_config, &hist_ctlr));

使用上述句柄，可以启用/禁用 ISP HIST 驱动程序的设置。

#### 卸载 ISP 驱动程序

如果不再需要先前安装的 ISP 驱动程序，建议通过调用 API 来回收资源，并释放底层硬件：

- `esp_isp_del_processor()`，用于 ISP 核心处理器。

- `esp_isp_del_af_controller()`，用于 ISP AF 控制器。

- `esp_isp_del_awb_controller()`，用于 ISP AWB 控制器。

- `esp_isp_del_ae_controller()`，用于 ISP AE 控制器。

- `esp_isp_del_hist_controller()`，用于 ISP 直方图控制器。

### 启用和禁用 ISP

#### ISP

在进行 ISP 流水线操作之前，需要先调用 `esp_isp_enable()` 函数来启用 ISP 处理器。此函数：

- 将驱动程序状态从 init 切换到 enable。

调用 `esp_isp_disable()` 函数会执行相反的操作，即将驱动程序恢复到 init 状态。

#### ISP AF 控制器

在进行 ISP AF 操作之前，需要先调用 `esp_isp_af_controller_enable()` 函数来启用 ISP AF 控制器。此函数：

- 将驱动程序状态从 init 切换到 enable。

调用 `esp_isp_af_controller_disable()` 函数会执行相反的操作，即将驱动程序恢复到 init 状态。

### 单次与连续 AF 数据统计

调用 `esp_isp_af_controller_get_oneshot_statistics()` 可获取单次 AF 统计结果，请参考以下代码。

除此之外，ISP AF 驱动程序还可以连续获取 AF 统计信息。调用 `esp_isp_af_controller_start_continuous_statistics()` 可启动连续统计，调用 `esp_isp_af_controller_stop_continuous_statistics()` 可停止统计。

若想启用连续统计，需要先注册回调函数 `esp_isp_af_env_detector_evt_cbs_t::on_env_statistics_done` 或 `esp_isp_af_env_detector_evt_cbs_t::on_env_change` 以获取统计数据。有关如何注册回调函数，请参见 注册事件回调函数。

备注

使用连续统计时，AF 环境检测器将失效。

    esp_isp_af_config_t af_config = {
        .edge_thresh = 128,
    };
    isp_af_ctlr_t af_ctrlr = NULL;
    ESP_ERROR_CHECK(esp_isp_new_af_controller(isp_proc, &af_config, &af_ctrlr));
    ESP_ERROR_CHECK(esp_isp_af_controller_enable(af_ctrlr));
    isp_af_result_t result = {};
    /* 触发单次 AF 统计并获取结果，超时时长为 2000 ms */
    ESP_ERROR_CHECK(esp_isp_af_controller_get_oneshot_statistics(af_ctrlr, 2000, &result));

    /* 启动连续 AF 数据统计 */
    ESP_ERROR_CHECK(esp_isp_af_controller_start_continuous_statistics(af_ctrlr));
    // 可在此进行其他操作，统计结果可从回调函数中获取
    // ......
    // vTaskDelay(pdMS_TO_TICKS(1000));
    /* 停止连续 AF 数据统计  */
    ESP_ERROR_CHECK(esp_isp_af_controller_stop_continuous_statistics(af_ctrlr));

    /* 禁用 AF 控制器 */
    ESP_ERROR_CHECK(esp_isp_af_controller_disable(af_ctrlr));
    /* 删除 AF 控制器并释放资源 */
    ESP_ERROR_CHECK(esp_isp_del_af_controller(af_ctrlr));

### 设置 AF 环境检测器

调用 `esp_isp_af_controller_set_env_detector()` 来设置 ISP AF 环境检测器，请参考以下代码：

    esp_isp_af_env_config_t env_config = {
        .interval = 10,
    };
    isp_af_ctlr_t af_ctrlr = NULL;
    ESP_ERROR_CHECK(esp_isp_new_af_controller(isp_proc, &af_config, &af_ctrlr));
    ESP_ERROR_CHECK(esp_isp_af_controller_set_env_detector(af_ctrlr, &env_config));

### 设置 AF 环境检测器阈值

调用 `esp_isp_af_controller_set_env_detector_threshold()` 来设置 ISP AF 环境检测器的阈值。

    int definition_thresh = 0;
    int luminance_thresh = 0;
    ESP_ERROR_CHECK(esp_isp_af_env_detector_set_threshold(env_detector, definition_thresh, luminance_thresh));

#### ISP AWB 控制器

在进行 ISP AWB 操作之前，需要先调用 `esp_isp_awb_controller_enable()` 以启用 ISP AWB 控制器。此函数：

- 将驱动程序状态从 init 切换到 enable。

调用 `esp_isp_awb_controller_disable()` 函数会执行相反的操作，即将驱动程序恢复到 init 状态。

### 单次与连续 AWB 数据统计

调用 `esp_isp_awb_controller_get_oneshot_statistics()` 可获取单次 AWB 白块统计结果，请参考以下代码。

除此之外，ISP AWB 驱动程序还可以连续获取 AWB 统计信息。调用 `esp_isp_awb_controller_start_continuous_statistics()` 可启动连续统计，调用 `esp_isp_awb_controller_stop_continuous_statistics()` 可停止统计。

若想启用连续统计，需要先注册回调函数 `esp_isp_awb_cbs_t::on_statistics_done` 以获取统计结果。有关如何注册回调函数，请参见 注册事件回调函数。

    bool example_isp_awb_on_statistics_done_cb(isp_awb_ctlr_t awb_ctlr, const esp_isp_awb_evt_data_t *edata, void *user_data);
    // ...
    isp_awb_ctlr_t awb_ctlr = NULL;
    uint32_t image_width = 800;
    uint32_t image_height = 600;
    /* AWB 配置，请参考 API 注释来调整参数 */
    esp_isp_awb_config_t awb_config = {
        .sample_point = ISP_AWB_SAMPLE_POINT_AFTER_CCM,
        ...
    };
    isp_awb_stat_result_t stat_res = {};
    /* 创建 AWB 控制器 */
    ESP_ERROR_CHECK(esp_isp_new_awb_controller(isp_proc, &awb_config, &awb_ctlr));
    /* 注册 AWB 回调函数 */
    esp_isp_awb_cbs_t awb_cb = {
        .on_statistics_done = example_isp_awb_on_statistics_done_cb,
    };
    ESP_ERROR_CHECK(esp_isp_awb_register_event_callbacks(awb_ctlr, &awb_cb, NULL));
    /* 启用 AWB 控制器 */
    ESP_ERROR_CHECK(esp_isp_awb_controller_enable(awb_ctlr));

    /* 获取单次 AWB 统计结果 */
    ESP_ERROR_CHECK(esp_isp_awb_controller_get_oneshot_statistics(awb_ctlr, -1, &stat_res));

    /* 启动连续 AWB 数据统计，注意在此之前需要先注册 `on_statistics_done` 回调函数 */
    ESP_ERROR_CHECK(esp_isp_awb_controller_start_continuous_statistics(awb_ctlr));
    // 可在此进行其他操作，统计结果可从回调函数中获取
    // ......
    // vTaskDelay(pdMS_TO_TICKS(1000));
    /* 停止连续 AWB 数据统计 */
    ESP_ERROR_CHECK(esp_isp_awb_controller_stop_continuous_statistics(awb_ctlr));

    /* 禁用 AWB 控制器 */
    ESP_ERROR_CHECK(esp_isp_awb_controller_disable(awb_ctlr));
    /* 删除 AWB 控制器并释放资源 */
    ESP_ERROR_CHECK(esp_isp_del_awb_controller(awb_ctlr));

#### ISP AE 控制器

在进行 ISP AE 操作之前，需要先调用 `esp_isp_ae_controller_enable()` 来启用 ISP AE 控制器。此函数：

- 将驱动程序状态从 init 切换到 enable。

调用 `esp_isp_ae_controller_disable()` 函数会执行相反的操作，即将驱动程序恢复到 init 状态。

### 单次与连续 AE 数据统计

调用 `esp_isp_ae_controller_get_oneshot_statistics()` 可获取单次 AE 统计结果，请参考以下代码。

使用单次 AE 数据统计时，需要禁用连续 AE 模式，否则结果可能会被环境检测器覆盖。完成单次操作后，请重新启动连续模式。

除了上述单次统计 API 外，ISP AE 驱动程序还可以连续获取 AE 统计信息。调用 `esp_isp_ae_controller_start_continuous_statistics()` 可启动连续统计，调用 `esp_isp_ae_controller_stop_continuous_statistics()` 可停止统计。

若想启用连续统计，需要先注册回调函数 `esp_isp_ae_env_detector_evt_cbs_t::on_env_statistics_done` 或 `esp_isp_ae_env_detector_evt_cbs_t::on_env_change` 以获取统计数据。有关如何注册回调函数，请参见 注册事件回调函数。

备注

使用单次统计时，AE 环境检测器将暂时失效，并在完成单次操作后自动恢复。

    esp_isp_ae_config_t ae_config = {
        .sample_point = ISP_AE_SAMPLE_POINT_AFTER_DEMOSAIC,
    };
    isp_ae_ctlr_t ae_ctlr = NULL;
    ESP_ERROR_CHECK(esp_isp_new_ae_controller(isp_proc, &ae_config, &ae_ctlr));
    ESP_ERROR_CHECK(esp_isp_ae_controller_enable(ae_ctlr));
    isp_ae_result_t result = {};
    /* 触发单次 AE 统计并获取结果，超时时长为 2000 ms */
    ESP_ERROR_CHECK(esp_isp_ae_controller_get_oneshot_statistics(ae_ctlr, 2000, &result));

    /* 启动连续 AE 数据统计 */
    ESP_ERROR_CHECK(esp_isp_ae_controller_start_continuous_statistics(ae_ctlr));
    // 可在此进行其他操作，统计结果可从回调函数中获取
    // ......
    // vTaskDelay(pdMS_TO_TICKS(1000));
    /* 停止连续 AE 数据统计 */
    ESP_ERROR_CHECK(esp_isp_ae_controller_stop_continuous_statistics(ae_ctlr));

    /* 禁用 AE 控制器 */
    ESP_ERROR_CHECK(esp_isp_ae_controller_disable(ae_ctlr));
    /* 删除 AE 控制器并释放资源 */
    ESP_ERROR_CHECK(esp_isp_del_ae_controller(ae_ctlr));

### 设置 AE 环境检测器

调用 `esp_isp_ae_controller_set_env_detector()` 来设置 ISP AE 环境检测器，请参考以下代码：

    esp_isp_ae_env_config_t env_config = {
        .interval = 10,
    };
    ESP_ERROR_CHECK(esp_isp_ae_controller_set_env_detector(ae_ctlr, &env_config));

### 设置 AE 环境检测器阈值

调用 `esp_isp_ae_controller_set_env_detector_threshold()` 来设置 ISP AE 环境检测器的阈值 (1-255)。

    esp_isp_ae_env_thresh_t env_thresh = {
        .low_thresh = 110,
        .high_thresh = 130,
    };
    ESP_ERROR_CHECK(esp_isp_ae_controller_set_env_detector_threshold(ae_ctlr, env_thresh));

#### ISP 直方图控制器

在进行 ISP 直方图统计之前，需要先调用 `esp_isp_hist_controller_enable()` 以启用 ISP 直方图控制器。此函数：

- 将驱动程序状态从 init 切换到 enable。

调用 `esp_isp_hist_controller_disable()` 函数会执行相反的操作，即将驱动程序恢复到 init 状态。

### 单次与连续直方图数据统计

调用 `esp_isp_hist_controller_get_oneshot_statistics()` 可获取单次直方图统计结果，请参考以下代码。

除此之外，ISP 直方图驱动程序还可以连续获取直方图统计信息。调用 `esp_isp_hist_controller_start_continuous_statistics()` 可启动连续统计，调用 `esp_isp_hist_controller_stop_continuous_statistics()` 可停止连续统计。

若想启用连续统计，需要先注册回调函数 `esp_isp_hist_cbs_t::on_statistics_done` 以获取统计结果。有关如何注册回调函数，请参见 注册事件回调函数。

    static bool s_hist_scheme_on_statistics_done_callback(isp_hist_ctlr_t awb_ctrlr, const esp_isp_hist_evt_data_t *edata, void *user_data)
    {
        for(int i = 0; i < 16; i++) {
            esp_rom_printf(DRAM_STR("val %d is %x\n"), i, edata->hist_result.hist_value[i]); // 获取直方图统计值
        }
        return true;
    }

    esp_isp_hist_cbs_t hist_cbs = {
        .on_statistics_done = s_hist_scheme_on_statistics_done_callback,
    };

    esp_isp_hist_register_event_callbacks(hist_ctlr, &hist_cbs, hist_ctlr);
    esp_isp_hist_controller_enable(hist_ctlr);

#### ISP BF 控制器

此流水线用于在拜耳模式下进行图像输入降噪。

可调用 `esp_isp_bf_configure()` 函数配置 BF 功能，请参考以下代码：

    esp_isp_bf_config_t bf_config = {
        .denoising_level = 5,
        .bf_template = {
            {1, 2, 1},
            {2, 4, 2},
            {1, 2, 1},
        },
        ...
    };
    ESP_ERROR_CHECK(esp_isp_bf_configure(isp_proc, &bf_config));
    ESP_ERROR_CHECK(esp_isp_bf_enable(isp_proc));

`esp_isp_bf_config_t::bf_template` 用于拜耳域降噪。可以通过高斯滤波器模板或均值滤波器模板来设置 `esp_isp_bf_config_t::bf_template`。

调用 `esp_isp_bf_configure()` 后，需要通过调用 `esp_isp_bf_enable()` 来启用 ISP BF 控制器。此函数：

- 将驱动程序状态从 init 切换到 enable。

调用 `esp_isp_bf_disable()` 函数会执行相反的操作，即将驱动程序恢复到 init 状态。

#### ISP BLC 控制器

黑电平校正 (BLC) 旨在解决因相机传感器中光线折射不均而引起的问题。

可调用 `esp_isp_blc_configure()` 函数配置 BLC 模块以进行校正。

    esp_isp_blc_config_t blc_config = {
        .window = {
            .top_left = {
                .x = 0,
                .y = 0,
            },
            .btm_right = {
                .x = CONFIG_EXAMPLE_MIPI_CSI_DISP_HRES,
                .y = CONFIG_EXAMPLE_MIPI_CSI_DISP_VRES,
            },
        },
        .filter_enable = true,
        .filter_threshold = {
            .top_left_chan_thresh = 128,
            .top_right_chan_thresh = 128,
            .bottom_left_chan_thresh = 128,
            .bottom_right_chan_thresh = 128,
        },
        .stretch = {
            .top_left_chan_stretch_en = true,
            .top_right_chan_stretch_en = true,
            .bottom_left_chan_stretch_en = true,
            .bottom_right_chan_stretch_en = true,
        },
    };
    ESP_ERROR_CHECK(esp_isp_blc_configure(isp_proc, &blc_config));
    ESP_ERROR_CHECK(esp_isp_blc_enable(isp_proc));

调用 `esp_isp_blc_configure()` 后，需要通过调用 `esp_isp_blc_enable()` 来启用 ISP BLC 控制器。此函数：

- 将驱动程序状态从 init 切换到 enable。

调用 `esp_isp_blc_disable()` 函数会执行相反的操作，即将驱动程序恢复到 init 状态。

调用 `esp_isp_blc_set_correction_offset()` 函数来设置 BLC 校正偏移量。

    esp_isp_blc_offset_t blc_offset = {
        .top_left_chan_offset = 20,
        .top_right_chan_offset = 20,
        .bottom_left_chan_offset = 20,
        .bottom_right_chan_offset = 20,
    };
    ESP_ERROR_CHECK(esp_isp_blc_set_correction_offset(isp_proc, &blc_offset));

#### ISP LSC 控制器

镜头阴影校正 (LSC) 旨在解决因相机镜头中光线折射不均而引起的问题。

可调用 `esp_isp_lsc_configure()` 函数配置 LSC 模块以进行校正。硬件进行校正相关计算时需要用到 `esp_isp_lsc_gain_array_t` 类型的数据结构。`esp_isp_lsc_allocate_gain_array()` 是一个辅助函数，为增益值分配大小合适的系统存储。

    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));

调用 `esp_isp_lsc_configure()` 后，需要通过调用 `esp_isp_lsc_enable()` 来启用 ISP LSC 控制器。可以通过调用 `esp_isp_lsc_disable()` 来禁用 LSC。此外，即使未启用 LSC 控制器，也可以调用 `esp_isp_lsc_configure()`，但 LSC 功能仅在启用后才会生效。

#### ISP 色彩控制器

该流水线用于调整图像的对比度、饱和度、色调和亮度。

可调用 `esp_isp_color_configure()` 函数配置色彩功能，请参考以下代码。

- 对比度应为 0 ~ 1.0，默认值为 1.0

- 饱和度应为 0 ~ 1.0，默认值为 1.0

- 色调应为 0 ~ 360，默认值为 0

- 亮度应为 -127 ~ 128，默认值为 0

    esp_isp_color_config_t color_config = {
        .color_contrast = {
            .integer = 1,
            .decimal = 0,
        },
        .color_saturation = {
            .integer = 1,
            .decimal = 0,
        },
        .color_hue = 0,
        .color_brightness = 0,
    };
    ESP_ERROR_CHECK(esp_isp_color_configure(isp_proc, &color_config));
    ESP_ERROR_CHECK(esp_isp_color_enable(isp_proc));

调用 `esp_isp_color_configure()` 后，需要通过调用 `esp_isp_color_enable()` 来启用 ISP 色彩控制器。此函数：

- 将驱动程序状态从 init 切换为 enable。

调用 `esp_isp_color_disable()` 函数会执行相反的操作，即将驱动程序恢复到 init 状态。

备注

当 ISP DVP 外设在使用且输出颜色格式设置为 RGB 色彩空间时，摄像头驱动程序会自动启用 ISP 色彩控制器 以确保数据输出正确。在这种情况下，禁止调用 `esp_isp_color_disable()` 函数，否则可能导致摄像头数据混乱。

### 配置 CCM

色彩校正矩阵可以调整 RGB888 像素格式的颜色比例，可用于通过算法调整图像颜色（例如，使用 AWB 计算结果进行白平衡），或者通过滤波算法用作过滤器。

调整色彩校正矩阵的公式如下：

    [ R' ]     [ RR  RG  RB  ]   [ R ]
    [ G' ] =   [ GR  GG  GB  ] * [ G ]
    [ B' ]     [ BR  BG  BB  ]   [ B ]

可以参考以下代码进行配置：

    // ...
    // 配置 CCM
    esp_isp_ccm_config_t ccm_cfg = {
        .matrix = {
            1.0, 0.0, 0.0,
            0.0, 1.0, 0.0,
            0.0, 0.0, 1.0
        },
        .saturation = false,
        ...
    };
    ESP_ERROR_CHECK(esp_isp_ccm_configure(isp_proc, &ccm_cfg));
    // 启用 CCM 模块后，配置好的 CCM 将应用到图像上
    ESP_ERROR_CHECK(esp_isp_ccm_enable(isp_proc));
    // CCM 也可以在启用后进行配置
    ccm_cfg.matrix[0][0] = 2.0;
    ESP_ERROR_CHECK(esp_isp_ccm_configure(isp_proc, &ccm_cfg));
    // 如果不再需要 CCM，则禁用它
    ESP_ERROR_CHECK(esp_isp_ccm_disable(isp_proc));

#### ISP 去马赛克控制器

此流水线用于执行图像去马赛克算法，将 RAW 图像转换为 RGB 模式。

可调用 `esp_isp_demosaic_configure()` 来配置去马赛克功能，请参考以下代码：

    esp_isp_demosaic_config_t demosaic_config = {
        .grad_ratio = {
            .integer = 2,
            .decimal = 5,
        },
        ...
    };

    ESP_ERROR_CHECK(esp_isp_demosaic_configure(isp_proc, &demosaic_config));
    ESP_ERROR_CHECK(esp_isp_demosaic_enable(isp_proc));

调用 `esp_isp_demosaic_configure()` 后，需要通过调用 `esp_isp_demosaic_enable()` 来启用 ISP 去马赛克控制器。此函数：

- 将驱动程序状态从 init 切换到 enable。

调用 `esp_isp_demosaic_disable()` 会执行相反的操作，即将驱动程序恢复到 init 状态。

即使驱动程序处于 init 状态，也可以调用 `esp_isp_demosaic_configure()`，但去马赛克配置只有在 enable 状态下才会生效。

### 启用 gamma 校正

人眼的视觉系统对物理亮度的感知是非线性的。将 gamma 校正添加到 ISP 流水线中，可以将 RGB 坐标转换为坐标与主观亮度成正比的空间。

驱动程序提供了帮助函数 `esp_isp_gamma_fill_curve_points()`，用于填充 `isp_gamma_curve_points_t`，这是描述 gamma 校正曲线的点集合。也可以通过手动声明点来获得期望的 gamma 校正曲线。每个 R/G/B 分量有自己的 gamma 校正曲线，可以通过调用 `esp_isp_gamma_configure()` 来配置。

以下是一个典型的代码示例：

    #include <math.h>

    // 设置相机 gamma 为 0.7，gamma 校正曲线为 y = 256 * (x / 256) ^ 0.7
    static uint32_t s_gamma_curve(uint32_t x)
    {
        return pow((double)x / 256, 0.7) * 256;
    }

    isp_gamma_curve_points_t pts = {};
    ESP_ERROR_CHECK(esp_isp_gamma_fill_curve_points(s_gamma_curve, &pts));
    ESP_ERROR_CHECK(esp_isp_gamma_configure(isp_proc, COLOR_COMPONENT_R, &pts));
    ESP_ERROR_CHECK(esp_isp_gamma_configure(isp_proc, COLOR_COMPONENT_G, &pts));
    ESP_ERROR_CHECK(esp_isp_gamma_configure(isp_proc, COLOR_COMPONENT_B, &pts));

    // 配置完曲线参数后启用 gamma 模块
    ESP_ERROR_CHECK(esp_isp_gamma_enable(isp_proc));

    // 如果不再需要，则禁用 gamma
    ESP_ERROR_CHECK(esp_isp_gamma_disable(isp_proc));

#### ISP 锐化控制器

此流水线用于在 YUV 模式下锐化输入图像。

调用 `esp_isp_sharpen_configure()` 来配置锐化功能，请参考以下代码。

    esp_isp_sharpen_config_t sharpen_config = {
        .h_thresh = 255,
        .sharpen_template = {
            {1, 2, 1},
            {2, 4, 2},
            {1, 2, 1},
        },
        ...
    };
    ESP_ERROR_CHECK(esp_isp_sharpen_configure(isp_proc, &sharpen_config));
    ESP_ERROR_CHECK(esp_isp_sharpen_enable(isp_proc));

调用 `esp_isp_sharpen_config_t::sharpen_template` 进行锐化。可以通过高斯滤波器模板或均值滤波器模板来设置 `esp_isp_sharpen_config_t::sharpen_template`。

调用 `esp_isp_sharpen_configure()` 后，需要通过调用 `esp_isp_sharpen_enable()` 以启用 ISP 锐化控制器。此函数：

- 将驱动程序状态从 init 切换到 enable。

调用 `esp_isp_sharpen_disable()` 函数会执行相反的操作，即将驱动程序恢复到 init 状态。

即使驱动程序处于 init 状态，也可以调用 `esp_isp_sharpen_configure()`，但锐化配置只有在 enable 状态下才会生效。

#### ISP 图像裁剪控制器

ISP 图像裁剪功能可以从原始图像中提取指定区域，减少后续处理的数据量，提高处理效率。裁剪功能在 ISP 流水线的末端执行，可以输出比输入图像更小的区域。

备注

ISP 图像裁剪功能仅在 ESP32-P4 revision 3.0 及以上版本中可用。

可调用 `esp_isp_crop_configure()` 函数配置图像裁剪功能，请参考以下代码：

    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));

调用 `esp_isp_crop_configure()` 后，需要通过调用 `esp_isp_crop_enable()` 来启用 ISP 图像裁剪控制器。此函数：

- 将驱动程序状态从 init 切换到 enable。

调用 `esp_isp_crop_disable()` 函数会执行相反的操作，即将驱动程序恢复到 init 状态。

即使驱动程序处于 init 状态，也可以调用 `esp_isp_crop_configure()`，但裁剪配置只有在 enable 状态下才会生效。

备注

- 裁剪区域的左上角坐标 (top_left) 必须小于右下角坐标 (btm_right)

- 裁剪区域的左上角坐标必须为偶数，右下角坐标必须为奇数

- 裁剪区域不能超出原始图像的边界

- 需根据裁剪后分辨率调整显示介质（如LCD）的尺寸，确保显示完整，避免出现黑边或拉伸现象。

### 注册事件回调函数

ISP 模块启动后，会动态生成特定事件。

你也可以通过参数 `user_data` 将自己的上下文保存到回调函数中，用户数据将直接传递给回调函数。

备注

下文中提到的回调函数在 ISR 上下文中被调用，必须确保这些函数不会尝试阻塞（例如，确保只从函数中调用带有 `ISR` 后缀的 FreeRTOS API）。

#### 注册 ISP 处理器事件回调函数

启用 ISP 处理器后，会动态生成多个 ISP 子模块的事件。可以通过调用 `esp_isp_register_event_callbacks()` 将函数挂接到中断服务例程。所有支持的事件回调函数可参见 `esp_isp_evt_cbs_t`：

- `esp_isp_evt_cbs_t::on_sharpen_frame_done` 在完成锐化帧后设置回调函数。ISP 锐化子模块完成一帧的操作后会调用此函数。函数原型在 `esp_isp_sharpen_callback_t` 中声明。

#### 注册 ISP AF 环境检测器事件回调函数

ISP AF 环境检测器启动后，将动态生成特定事件。若想在事件发生时调用某些函数，请通过调用 `esp_isp_af_env_detector_register_event_callbacks()` 将目标函数挂接到中断服务程序中。所有支持的事件回调函数可参见 `esp_isp_af_env_detector_evt_cbs_t`：

- `esp_isp_af_env_detector_evt_cbs_t::on_env_statistics_done` 为环境统计完成事件设置回调函数。该函数原型在 `esp_isp_af_env_detector_callback_t` 中声明。

- `esp_isp_af_env_detector_evt_cbs_t::on_env_change` 为环境变化事件设置回调函数。该函数原型在 `esp_isp_af_env_detector_callback_t` 中声明。

#### 注册 ISP AWB 统计完成事件回调函数

ISP AWB 控制器完成白块数据统计后，将动态生成特定事件。若想在统计完成时收到通知，请通过调用 `esp_isp_awb_register_event_callbacks()` 将目标函数挂接到中断服务程序中。所有支持的事件回调函数可参见 `esp_isp_awb_cbs_t`：

- `esp_isp_awb_cbs_t::on_statistics_done` 在白块数据统计完成后设置回调函数。该函数原型在 `esp_isp_awb_callback_t` 中声明。

#### 注册 ISP AE 环境检测器事件回调函数

ISP AE 环境检测器启动后，将动态生成特定事件。若想在事件发生时调用某些函数，请通过调用 `esp_isp_ae_env_detector_register_event_callbacks()` 将目标函数挂接到中断服务程序中。所有支持的事件回调函数可参见 `esp_isp_ae_env_detector_evt_cbs_t`：

- `esp_isp_ae_env_detector_evt_cbs_t::on_env_statistics_done` 为环境统计完成事件设置回调函数。该函数原型在 `esp_isp_ae_env_detector_callback_t` 中声明。

- `esp_isp_ae_env_detector_evt_cbs_t::on_env_change` 为环境变化事件设置回调函数。该函数原型在 `esp_isp_ae_env_detector_callback_t` 中声明。

#### 注册 ISP HIST 统计完成事件回调函数

ISP HIST 控制器完成亮度统计后，将动态生成特定事件。若想在统计完成时收到通知，请通过调用 `esp_isp_hist_register_event_callbacks()` 将目标函数挂接到中断服务程序。所有支持的事件回调函数可参见 `esp_isp_hist_cbs_t`：

- `esp_isp_hist_cbs_t::on_statistics_done` 在完成亮度统计时设置回调函数。该函数原型在 `esp_isp_hist_callback_t` 中声明。

### 线程安全

驱动程序会确保以下工厂函数的线程安全：

- `esp_isp_new_processor()`

- `esp_isp_del_processor()`

- `esp_isp_new_af_controller()`

- `esp_isp_del_af_controller()`

- `esp_isp_new_awb_controller()`

- `esp_isp_del_awb_controller()`

- `esp_isp_new_ae_controller()`

- `esp_isp_del_ae_controller()`

- `esp_isp_new_hist_controller()`

- `esp_isp_del_hist_controller()`

使用时，可以直接从不同的 RTOS 任务中调用此类函数，无需额外锁保护。其他 API 无法确保线程安全。

### Kconfig 选项

- CONFIG_ISP_ISR_IRAM_SAFE 控制默认的 ISR 句柄在 cache 被禁用时是否可以正常工作。

### IRAM 安全

默认情况下，当 cache 因写入或擦除 flash 等原因而被禁用时，ISP 的中断将会延迟。

Kconfig 选项 CONFIG_ISP_ISR_IRAM_SAFE 支持：

- 即使 cache 被禁用也能启用中断

- 将 ISR 使用的所有函数放入 IRAM

- 将驱动程序对象放入 DRAM（以防意外映射到 PSRAM）

启用上述 Kconfig 选项，保证 cache 被禁用时中断可以正常运行，但这会增加 IRAM 使用量。启用此选项后，当 cache 被禁用时，ISR 回调函数将继续运行。因此，必须确保回调函数及其上下文也是 IRAM 安全的。

Kconfig 选项 CONFIG_ISP_CTRL_FUNC_IN_IRAM 支持：

- 将一些 ISP 控制函数放入 IRAM，函数列表请参见：

  > - `esp_isp_sharpen_configure()`

  > - `esp_isp_demosaic_configure()`

## 应用示例

- peripherals/isp/multi_pipelines 演示了如何使用 ISP 流水线处理来自摄像头传感器的图像信号，并通过 DSI 外设在 LCD 屏幕上显示视频。

## API 参考

### Header File

- components/esp_driver_isp/include/driver/isp.h

- This header file can be included with:

  >     #include "driver/isp.h"

- This header file is a part of the API provided by the `esp_driver_isp` component. To declare that your component depends on `esp_driver_isp`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_driver_isp

  > or

  >     PRIV_REQUIRES esp_driver_isp

### Header File

- components/esp_driver_isp/include/driver/isp_af.h

- This header file can be included with:

  >     #include "driver/isp_af.h"

- This header file is a part of the API provided by the `esp_driver_isp` component. To declare that your component depends on `esp_driver_isp`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_driver_isp

  > or

  >     PRIV_REQUIRES esp_driver_isp

### Functions

esp_err_t esp_isp_new_af_controller(isp_proc_handle_t isp_proc, const esp_isp_af_config_t *af_config, isp_af_ctlr_t *ret_hdl)

  New an ISP AF controller.

  参数:

    - isp_proc -- [in] ISP Processor handle

    - af_config -- [in] Pointer to AF config. Refer to `esp_isp_af_config_t`.

    - ret_hdl -- [out] AF controller handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid

    - ESP_ERR_INVALID_STATE Invalid state

    - ESP_ERR_NOT_FOUND No free interrupt found with the specified flags

    - ESP_ERR_NO_MEM If out of memory

esp_err_t esp_isp_del_af_controller(isp_af_ctlr_t af_ctrlr)

  Delete an ISP AF controller.

  参数:

    af_ctrlr -- [in] AF controller handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_af_controller_enable(isp_af_ctlr_t af_ctrlr)

  Enable an ISP AF controller.

  参数:

    af_ctrlr -- [in] AF controller handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_af_controller_disable(isp_af_ctlr_t af_ctrlr)

  Disable an ISP AF controller.

  参数:

    af_ctrlr -- [in] AF controller handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_af_controller_get_oneshot_statistics(isp_af_ctlr_t af_ctrlr, int timeout_ms, isp_af_result_t *out_res)

  Trigger AF luminance and definition statistics for one time and get the result.

  参数:

    - af_ctrlr -- [in] AF controller handle

    - timeout_ms -- [in] Timeout in millisecond

      - timeout_ms < 0: Won't return until finished

      - timeout_ms = 0: No timeout, trigger one time statistics and return immediately, in this case, the result won't be assigned in this function, but you can get the result in the callback `esp_isp_af_env_detector_evt_cbs_t::on_env_statistics_done`

      - timeout_ms > 0: Wait for specified milliseconds, if not finished, then return timeout error

    - out_res -- [out] AF luminance and definition statistics result, can be NULL if `timeout_ms = 0`

  返回:

    - ESP_OK On success

    - ESP_ERR_TIMEOUT If the waiting time exceeds the specified timeout.

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_af_controller_start_continuous_statistics(isp_af_ctlr_t af_ctrlr)

  Start AF continuous statistics of the luminance and definition in the windows.

  备注

  This function is an asynchronous and non-block function, it will start the continuous statistics and return immediately. You have to register the AF callback and get the result from the callback event data.

  备注

  When continuous mode start, AF environment detector will be invalid

  参数:

    af_ctrlr -- [in] AF controller handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG Null pointer

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_af_controller_stop_continuous_statistics(isp_af_ctlr_t af_ctrlr)

  Stop AF continuous statistics of the luminance and definition in the windows.

  参数:

    af_ctrlr -- [in] AF controller handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG Null pointer

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_af_controller_set_env_detector(isp_af_ctlr_t af_ctrlr, const esp_isp_af_env_config_t *env_config)

  Set ISP AF environment detector.

  备注

  When continuous mode start, AF environment detector will be invalid

  参数:

    - af_ctrlr -- [in] AF controller handle

    - env_config -- [in] AF Env detector configuration

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_af_controller_set_env_detector_threshold(isp_af_ctlr_t af_ctrlr, int definition_thresh, int luminance_thresh)

  Set ISP AF environment detector detecting threshold.

  参数:

    - af_ctrlr -- [in] AF controller handle

    - definition_thresh -- [in] Threshold for definition

    - luminance_thresh -- [in] Threshold for luminance

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_af_env_detector_register_event_callbacks(isp_af_ctlr_t af_ctrlr, const esp_isp_af_env_detector_evt_cbs_t *cbs, void *user_data)

  Register AF environment detector event callbacks.

  备注

  User can deregister a previously registered callback by calling this function and setting the to-be-deregistered callback member in the `cbs` structure to NULL.

  备注

  When CONFIG_ISP_ISR_IRAM_SAFE is enabled, the callback itself and functions called by it should be placed in IRAM. Involved variables (including `user_data`) should be in internal RAM as well.

  参数:

    - af_ctrlr -- [in] AF controller handle

    - cbs -- [in] Group of callback functions

    - user_data -- [in] User data, which will be delivered to the callback functions directly

  返回:

    - ESP_OK: On success

    - ESP_ERR_INVALID_ARG: Invalid arguments

    - ESP_ERR_INVALID_STATE: Driver state is invalid, you shouldn't call this API at this moment

### Structures

struct esp_isp_af_config_t

  AF controller config.

  Public Members

  isp_window_t window[ISP_AF_WINDOW_NUM]

    The sampling windows of AF.

  int edge_thresh

    Edge threshold, definition higher than this value will be counted as a valid pixel for calculating AF result.

  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)

struct esp_isp_af_env_config_t

  AF environment detector config.

  Public Members

  int interval

    Interval between environment detection, in frames. i.e., AF controller will trigger the statistic periodically to detect the environment change.

struct esp_isp_af_env_detector_evt_data_t

  Event data structure.

  Public Members

  isp_af_result_t af_result

    The AF statistics result

struct esp_isp_af_env_detector_evt_cbs_t

  Group of ISP AF Env detector callbacks.

  备注

  These callbacks are all running in an ISR environment.

  备注

  When CONFIG_ISP_ISR_IRAM_SAFE is enabled, the callback itself and functions called by it should be placed in IRAM. Involved variables should be in internal RAM as well.

  Public Members

  esp_isp_af_env_detector_callback_t on_env_statistics_done

    Event callback, invoked when environment sample done.

  esp_isp_af_env_detector_callback_t on_env_change

    Event callback, invoked when environment change happens.

### Type Definitions

typedef bool (*esp_isp_af_env_detector_callback_t)(isp_af_ctlr_t af_ctrlr, const esp_isp_af_env_detector_evt_data_t *edata, void *user_data)

  Prototype of ISP AF Env detector event callback.

  Param af_ctrlr:

    [in] ISP AF controller handle

  Param edata:

    [in] ISP AF Env detector event data

  Param user_data:

    [in] User registered context, registered when in `esp_isp_af_env_detector_register_event_callbacks()`

  Return:

    Whether a high priority task is woken up by this function

### Header File

- components/esp_driver_isp/include/driver/isp_ae.h

- This header file can be included with:

  >     #include "driver/isp_ae.h"

- This header file is a part of the API provided by the `esp_driver_isp` component. To declare that your component depends on `esp_driver_isp`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_driver_isp

  > or

  >     PRIV_REQUIRES esp_driver_isp

### Functions

esp_err_t esp_isp_new_ae_controller(isp_proc_handle_t isp_proc, const esp_isp_ae_config_t *ae_config, isp_ae_ctlr_t *ret_hdl)

  New an ISP AE controller.

  参数:

    - isp_proc -- [in] ISP Processor handle

    - ae_config -- [in] Pointer to AE config. Refer to `esp_isp_ae_config_t`.

    - ret_hdl -- [out] AE controller handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid

    - ESP_ERR_INVALID_STATE Invalid state

    - ESP_ERR_NOT_FOUND No free interrupt found with the specified flags

    - ESP_ERR_NO_MEM If out of memory

esp_err_t esp_isp_del_ae_controller(isp_ae_ctlr_t ae_ctlr)

  Delete an ISP AE controller.

  参数:

    ae_ctlr -- [in] AE controller handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_ae_controller_enable(isp_ae_ctlr_t ae_ctlr)

  Enable an ISP AE controller.

  参数:

    ae_ctlr -- [in] AE controller handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_ae_controller_disable(isp_ae_ctlr_t ae_ctlr)

  Disable an ISP AE controller.

  参数:

    ae_ctlr -- [in] AE controller handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_ae_controller_get_oneshot_statistics(isp_ae_ctlr_t ae_ctlr, int timeout_ms, isp_ae_result_t *out_res)

  Trigger AE luminance statistics for one time and get the result.

  参数:

    - ae_ctlr -- [in] AE controller handle

    - timeout_ms -- [in] Timeout in millisecond

      - timeout_ms < 0: Won't return until finished

      - timeout_ms = 0: No timeout, trigger one time statistics and return immediately, in this case, the result won't be assigned in this function, but you can get the result in the callback `esp_isp_ae_env_detector_evt_cbs_t::on_env_statistics_done`

      - timeout_ms > 0: Wait for specified milliseconds, if not finished, then return timeout error

    - out_res -- [out] AE luminance statistics result, can be NULL if `timeout_ms = 0`

  返回:

    - ESP_OK On success

    - ESP_ERR_TIMEOUT If the waiting time exceeds the specified timeout.

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_ae_controller_start_continuous_statistics(isp_ae_ctlr_t ae_ctlr)

  Start AE continuous statistics of the luminance in the windows.

  备注

  This function is an asynchronous and non-block function, it will start the continuous statistics and return immediately. You have to register the AE callback and get the result from the callback event data.

  备注

  When using oneshot statistics, the AE Environment Detector will be temporarily disabled and will automatically recover once the oneshot is complete.

  参数:

    ae_ctlr -- [in] AE controller handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG Null pointer

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_ae_controller_stop_continuous_statistics(isp_ae_ctlr_t ae_ctlr)

  Stop AE continuous statistics of the luminance in the windows.

  参数:

    ae_ctlr -- [in] AE controller handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG Null pointer

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_ae_controller_set_env_detector(isp_ae_ctlr_t ae_ctlr, const esp_isp_ae_env_config_t *env_config)

  Set ISP AE environment detector.

  参数:

    - ae_ctlr -- [in] AE controller handle

    - env_config -- [in] AE Env detector configuration

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_ae_controller_set_env_detector_threshold(isp_ae_ctlr_t ae_ctlr, const esp_isp_ae_env_thresh_t *env_thresh)

  Set ISP AE environment detector detecting threshold.

  参数:

    - ae_ctlr -- [in] AE controller handle

    - env_thresh -- [in] Luminance thresholds for AE env detector

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_ae_env_detector_register_event_callbacks(isp_ae_ctlr_t ae_ctlr, const esp_isp_ae_env_detector_evt_cbs_t *cbs, void *user_data)

  Register AE Env detector event callbacks.

  备注

  User can deregister a previously registered callback by calling this function and setting the to-be-deregistered callback member in the `cbs` structure to NULL.

  备注

  When CONFIG_ISP_ISR_IRAM_SAEE is enabled, the callback itself and functions called by it should be placed in IRAM. Involved variables (including `user_data`) should be in internal RAM as well.

  参数:

    - ae_ctlr -- [in] AE controller handle

    - cbs -- [in] Group of callback functions

    - user_data -- [in] User data, which will be delivered to the callback functions directly

  返回:

    - ESP_OK: On success

    - ESP_ERR_INVALID_ARG: Invalid arguments

    - ESP_ERR_INVALID_STATE: Driver state is invalid, you shouldn't call this API at this moment

### Structures

struct esp_isp_ae_config_t

  AE controller config.

  Public Members

  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_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)

struct esp_isp_ae_env_config_t

  AE environment detector config.

  Public Members

  int interval

    Interval between environment detection, in frames. i.e., AE controller will trigger the statistic periodically to detect the environment change.

struct esp_isp_ae_env_thresh_t

  AE environment detector config.

  Public Members

  int low_thresh

    Low threshold for AE environment detector luminance

  int high_thresh

    High threshold for AE environment detector luminance

struct esp_isp_ae_env_detector_evt_data_t

  Event data structure.

  Public Members

  isp_ae_result_t ae_result

    The AE statistics result

struct esp_isp_ae_env_detector_evt_cbs_t

  Group of ISP AE env_detector.

  备注

  These callbacks are all running in an ISR environment.

  备注

  When CONFIG_ISP_ISR_IRAM_SAEE is enabled, the callback itself and functions called by it should be placed in IRAM. Involved variables should be in internal RAM as well.

  Public Members

  esp_isp_ae_env_detector_callback_t on_env_statistics_done

    Event callback, invoked when environment sample done.

  esp_isp_ae_env_detector_callback_t on_env_change

    Event callback, invoked when environment change happens.

### Type Definitions

typedef bool (*esp_isp_ae_env_detector_callback_t)(isp_ae_ctlr_t ae_ctlr, const esp_isp_ae_env_detector_evt_data_t *edata, void *user_data)

  Prototype of ISP AE Env detector event callback.

  Param ae_ctlr:

    [in] ISP AE controller handle

  Param edata:

    [in] ISP AE Env detector event data

  Param user_data:

    [in] User registered context, registered when in `esp_isp_ae_env_detector_register_event_callbacks()`

  Return:

    Whether a high priority task is woken up by this function

### Header File

- components/esp_driver_isp/include/driver/isp_awb.h

- This header file can be included with:

  >     #include "driver/isp_awb.h"

- This header file is a part of the API provided by the `esp_driver_isp` component. To declare that your component depends on `esp_driver_isp`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_driver_isp

  > or

  >     PRIV_REQUIRES esp_driver_isp

### Functions

esp_err_t esp_isp_new_awb_controller(isp_proc_handle_t isp_proc, const esp_isp_awb_config_t *awb_cfg, isp_awb_ctlr_t *ret_hdl)

  New an ISP AWB controller.

  参数:

    - isp_proc -- [in] ISP Processor handle

    - awb_cfg -- [in] Pointer to AWB config. Refer to `esp_isp_awb_config_t`.

    - ret_hdl -- [out] AWB controller handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid

    - ESP_ERR_INVALID_STATE Invalid state

    - ESP_ERR_NOT_FOUND No free interrupt found with the specified flags

    - ESP_ERR_NO_MEM If out of memory

esp_err_t esp_isp_del_awb_controller(isp_awb_ctlr_t awb_ctlr)

  Delete an ISP AWB controller.

  参数:

    awb_ctlr -- [in] AWB controller handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_awb_controller_reconfig(isp_awb_ctlr_t awb_ctlr, const esp_isp_awb_config_t *awb_cfg)

  Reconfigure the ISP AWB controller.

  备注

  This function is allowed to be called no matter the awb controller is enabled or not.

  参数:

    - awb_ctlr -- [in] AWB controller handle

    - awb_cfg -- [in] Pointer to AWB config. Refer to `esp_isp_awb_config_t`

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid

esp_err_t esp_isp_awb_controller_enable(isp_awb_ctlr_t awb_ctlr)

  Enable an ISP AWB controller.

  参数:

    awb_ctlr -- [in] AWB controller handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_awb_controller_disable(isp_awb_ctlr_t awb_ctlr)

  Disable an ISP AWB controller.

  参数:

    awb_ctlr -- [in] AWB controller handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_awb_controller_get_oneshot_statistics(isp_awb_ctlr_t awb_ctlr, int timeout_ms, isp_awb_stat_result_t *out_res)

  Trigger AWB white patch statistics for one time and get the result.

  参数:

    - awb_ctlr -- [in] AWB controller handle

    - timeout_ms -- [in] Timeout in millisecond

      - timeout_ms < 0: Won't return until finished

      - timeout_ms = 0: No timeout, trigger one time statistics and return immediately, in this case, the result won't be assigned in this function, but you can get the result in the callback `esp_isp_awb_cbs_t::on_statistics_done`

      - timeout_ms > 0: Wait for specified milliseconds, if not finished, then return timeout error

    - out_res -- [out] AWB white patch statistics result

  返回:

    - ESP_OK On success

    - ESP_ERR_TIMEOUT Wait for the result timeout

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_awb_controller_start_continuous_statistics(isp_awb_ctlr_t awb_ctlr)

  Start AWB continuous statistics of the white patch in the window.

  备注

  This function is an asynchronous and non-block function, it will start the continuous statistics and return immediately. You have to register the AWB callback and get the result from the callback event data.

  参数:

    awb_ctlr -- [in] AWB controller handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG Null pointer

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_awb_controller_stop_continuous_statistics(isp_awb_ctlr_t awb_ctlr)

  Stop AWB continuous statistics of the white patch in the window.

  参数:

    awb_ctlr -- [in] AWB controller handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG Null pointer

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_awb_register_event_callbacks(isp_awb_ctlr_t awb_ctlr, const esp_isp_awb_cbs_t *cbs, void *user_data)

  Register AWB event callbacks.

  备注

  User can deregister a previously registered callback by calling this function and setting the to-be-deregistered callback member in the `cbs` structure to NULL.

  备注

  When CONFIG_ISP_ISR_IRAM_SAFE is enabled, the callback itself and functions called by it should be placed in IRAM. Involved variables (including `user_data`) should be in internal RAM as well.

  参数:

    - awb_ctlr -- [in] AWB controller handle

    - cbs -- [in] Group of callback functions

    - user_data -- [in] User data, which will be delivered to the callback functions directly

  返回:

    - ESP_OK: On success

    - ESP_ERR_INVALID_ARG: Invalid arguments

    - ESP_ERR_INVALID_STATE: Driver state is invalid, you shouldn't call this API at this moment

### Structures

struct esp_isp_awb_config_t

  AWB controller config.

  Public Members

  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_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. It will be more reliable because the edges of image are easily to be overexposure, the overexposure pixels are almost at maximum luminance, which are not good references to calculate the gain for white balance.

  isp_window_t subwindow

    Statistic subwindow of AWB. Need to be set no greater than the main window. It will be evenly divided into a grid of ISP_AWB_WINDOW_X_NUM * ISP_AWB_WINDOW_Y_NUM blocks. The blocks share the same restrictions in R/G, B/G and luminance range as the main window. The statistics result of each block will be returned in the `isp_awb_stat_result_t::subwin_result` field.

  isp_u32_range_t luminance

    Luminance range of the white patch. Range [0, 255 * 3] Not suggest to set the max value to 255 * 3, because these pixels are too bright, very possible to be overexposure. So the pixels that too bright should not be the reference of the white balance. And the minimum value better to be 0 to allow the white balance work under low luminance environment.

  isp_float_range_t red_green_ratio

    Red to green ratio of the white patch. Range [0, 4.0). The ratio could be as wider as possible, so that all the distorted pixels will be counted for the reference of white balance.

  isp_float_range_t blue_green_ratio

    Blue to green ratio of the white patch. Range [0, 4.0) The ratio could be as wider as possible, so that all the distorted pixels will be counted for the reference of white balance.

  struct esp_isp_awb_config_t white_patch

    white patch configuration

  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)

struct esp_isp_awb_evt_data_t

  Event data of callbacks.

  Public Members

  isp_awb_stat_result_t awb_result

    The AWB white patch statistics result

struct esp_isp_awb_cbs_t

  Group of ISP AWB callbacks.

  备注

  These callbacks are all running in an ISR environment.

  备注

  When CONFIG_ISP_ISR_IRAM_SAFE is enabled, the callback itself and functions called by it should be placed in IRAM. Involved variables should be in internal RAM as well.

  Public Members

  esp_isp_awb_callback_t on_statistics_done

    Event callback, invoked when white patches statistic done.

### Type Definitions

typedef bool (*esp_isp_awb_callback_t)(isp_awb_ctlr_t awb_ctlr, const esp_isp_awb_evt_data_t *edata, void *user_data)

  Prototype of ISP AWB event callback.

  Param awb_ctlr:

    [in] ISP AWB controller handle

  Param edata:

    [in] ISP AWB event data

  Param user_data:

    [in] User registered context, registered when in `esp_isp_awb_env_detector_register_event_callbacks()`

  Return:

    Whether a high priority task is woken up by this function

### Header File

- components/esp_driver_isp/include/driver/isp_bf.h

- This header file can be included with:

  >     #include "driver/isp_bf.h"

- This header file is a part of the API provided by the `esp_driver_isp` component. To declare that your component depends on `esp_driver_isp`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_driver_isp

  > or

  >     PRIV_REQUIRES esp_driver_isp

### Functions

esp_err_t esp_isp_bf_configure(isp_proc_handle_t proc, const esp_isp_bf_config_t *config)

  ISP BF configuration.

  备注

  After calling this API, BF doesn't take into effect until `esp_isp_bf_enable` is called

  参数:

    - proc -- [in] Processor handle

    - config -- [in] BF configurations, set NULL to de-configure the ISP BF

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_STATE Not allowed to be called under current state

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid

esp_err_t esp_isp_bf_enable(isp_proc_handle_t proc)

  Enable ISP BF function.

  参数:

    proc -- [in] Processor handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_bf_disable(isp_proc_handle_t proc)

  Disable ISP BF function.

  参数:

    proc -- [in] Processor handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

### Structures

struct esp_isp_bf_config_t

  ISP BF configurations.

  Public Members

  isp_bf_edge_padding_mode_t padding_mode

    BF edge padding mode.

  uint8_t padding_data

    BF edge padding pixel data.

  uint8_t bf_template[ISP_BF_TEMPLATE_X_NUMS][ISP_BF_TEMPLATE_Y_NUMS]

    BF template data.

  uint8_t denoising_level

    BF denoising level, from 2 to 20, the bigger the better denoising performance, but the worse detailed.

  uint8_t padding_line_tail_valid_start_pixel

    BF edge padding line tail valid start pixel, padding data will only be valid between the valid start pixel and the valid end pixel. Set both the start and end pixel to 0 to make all padding pixel valid.

  uint8_t padding_line_tail_valid_end_pixel

    BF edge padding line tail valid end pixel, padding data will only be valid between the valid start pixel and the valid end pixel. Set both the start and end pixel to 0 to make all padding pixel valid.

  uint32_t update_once_configured

    If set, apply configuration to hardware immediately; otherwise defer to frame boundary.

  struct esp_isp_bf_config_t flags

    Driver behaviour flags.

### Header File

- components/esp_driver_isp/include/driver/isp_blc.h

- This header file can be included with:

  >     #include "driver/isp_blc.h"

- This header file is a part of the API provided by the `esp_driver_isp` component. To declare that your component depends on `esp_driver_isp`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_driver_isp

  > or

  >     PRIV_REQUIRES esp_driver_isp

### Functions

esp_err_t esp_isp_blc_configure(isp_proc_handle_t isp_proc, const esp_isp_blc_config_t *config)

  ISP BLC configuration.

  备注

  After calling this API, BLC doesn't take into effect until `esp_isp_blc_enable` is called

  参数:

    - isp_proc -- [in] Processor handle

    - config -- [in] BLC configurations

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_STATE Not allowed to be called under current state

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid

    - ESP_ERR_NOT_SUPPORTED Not supported

esp_err_t esp_isp_blc_enable(isp_proc_handle_t isp_proc)

  Enable ISP BLC function.

  参数:

    isp_proc -- [in] Processor handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_blc_set_correction_offset(isp_proc_handle_t isp_proc, esp_isp_blc_offset_t *offset)

  Set the correction offset of ISP BLC function.

  参数:

    - isp_proc -- [in] Processor handle

    - offset -- [in] Correction offset

esp_err_t esp_isp_blc_disable(isp_proc_handle_t isp_proc)

  Disable ISP BLC function.

  参数:

    isp_proc -- [in] Processor handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

### Structures

struct esp_isp_blc_thresh_t

  ISP BLC threshold configurations.

  Public Members

  uint8_t top_left_chan_thresh

    Black level threshold for top left channel of the raw Bayer image.

  uint8_t top_right_chan_thresh

    Black level threshold for top right channel of the raw Bayer image.

  uint8_t bottom_left_chan_thresh

    Black level threshold for bottom left channel of the raw Bayer image.

  uint8_t bottom_right_chan_thresh

    Black level threshold for bottom right channel of the raw Bayer image.

struct esp_isp_blc_stretch_t

  ISP BLC stretch configurations.

  Enable this can stretch the pixel value to 0~255 after black level correction

  Public Members

  bool top_left_chan_stretch_en

    Enable stretch for top left channel of the raw Bayer image.

  bool top_right_chan_stretch_en

    Enable stretch for top right channel of the raw Bayer image.

  bool bottom_left_chan_stretch_en

    Enable stretch for bottom left channel of the raw Bayer image.

  bool bottom_right_chan_stretch_en

    Enable stretch for bottom right channel of the raw Bayer image.

struct esp_isp_blc_config_t

  ISP BLC configurations.

  Public Members

  isp_window_t window

    The sampling windows of BLC, only pixels within the window will be sampled.

  esp_isp_blc_thresh_t filter_threshold

    Black level threshold for each channel of the raw Bayer image.

  bool filter_enable

    Enable filter for BLC, if enabled, only pixels within the threshold will be sampled.

  esp_isp_blc_stretch_t stretch

    Stretch configurations for each channel of the raw Bayer image.

  uint32_t update_once_configured

    If set, apply configuration to hardware immediately; otherwise defer to frame boundary.

  struct esp_isp_blc_config_t flags

    Driver behaviour flags.

struct esp_isp_blc_offset_t

  ISP BLC correction offset.

  Public Members

  uint32_t top_left_chan_offset

    Correction offset for top left channel of the raw Bayer image.

  uint32_t top_right_chan_offset

    Correction offset for top right channel of the raw Bayer image.

  uint32_t bottom_left_chan_offset

    Correction offset for bottom left channel of the raw Bayer image.

  uint32_t bottom_right_chan_offset

    Correction offset for bottom right channel of the raw Bayer image.

### Header File

- components/esp_driver_isp/include/driver/isp_lsc.h

- This header file can be included with:

  >     #include "driver/isp_lsc.h"

- This header file is a part of the API provided by the `esp_driver_isp` component. To declare that your component depends on `esp_driver_isp`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_driver_isp

  > or

  >     PRIV_REQUIRES esp_driver_isp

### Functions

esp_err_t esp_isp_lsc_allocate_gain_array(isp_proc_handle_t isp_proc, esp_isp_lsc_gain_array_t *gain_array, size_t *out_array_size_per_channel)

  Helper function to allocate gain array for LSC.

  参数:

    - isp_proc -- [in] Processor handle

    - gain_array -- [in] Gain array to be allocated

    - out_array_size_per_channel -- [out] Array size

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_STATE Not allowed to be called under current state

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid

    - ESP_ERR_NO_MEM Out of memory

esp_err_t esp_isp_lsc_configure(isp_proc_handle_t isp_proc, const esp_isp_lsc_config_t *config)

  ISP LSC configuration.

  备注

  After calling this API, LSC doesn't take into effect until `esp_isp_lsc_enable` is called

  参数:

    - isp_proc -- [in] Processor handle

    - config -- [in] LSC configurations

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_STATE Not allowed to be called under current state

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid

    - ESP_ERR_NOT_SUPPORTED Not supported

esp_err_t esp_isp_lsc_enable(isp_proc_handle_t isp_proc)

  Enable ISP LSC function.

  参数:

    isp_proc -- [in] Processor handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_lsc_disable(isp_proc_handle_t isp_proc)

  Disable ISP LSC function.

  参数:

    isp_proc -- [in] Processor handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

### Structures

struct esp_isp_lsc_gain_array_t

  LSC Gain array.

  Public Members

  isp_lsc_gain_t *gain_r

    Gain for R channel.

  isp_lsc_gain_t *gain_gr

    Gain for GR channel.

  isp_lsc_gain_t *gain_gb

    Gain for GB channel.

  isp_lsc_gain_t *gain_b

    Gain for B channel.

struct esp_isp_lsc_config_t

  ISP LSC configurations.

  Public Members

  esp_isp_lsc_gain_array_t *gain_array

    Gain array.

### Header File

- components/esp_driver_isp/include/driver/isp_ccm.h

- This header file can be included with:

  >     #include "driver/isp_ccm.h"

- This header file is a part of the API provided by the `esp_driver_isp` component. To declare that your component depends on `esp_driver_isp`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_driver_isp

  > or

  >     PRIV_REQUIRES esp_driver_isp

### Functions

esp_err_t esp_isp_ccm_configure(isp_proc_handle_t proc, const esp_isp_ccm_config_t *ccm_cfg)

  ISP Color Correction Matrix (CCM) configuration.

  备注

  This function is allowed to be called before or after `esp_isp_ccm_enable`, but it only takes effect until `esp_isp_ccm_enable` is called

  参数:

    - proc -- [in] Processor handle

    - ccm_cfg -- [in] CCM configurations

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid

esp_err_t esp_isp_ccm_enable(isp_proc_handle_t proc)

  Enable ISP CCM function.

  参数:

    proc -- [in] Processor handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

esp_err_t esp_isp_ccm_disable(isp_proc_handle_t proc)

  Disable ISP CCM function.

  参数:

    proc -- [in] Processor handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

### Structures

struct esp_isp_ccm_config_t

  Color Correction Matrix configurations.

  Public Members

  float matrix[ISP_CCM_DIMENSION][ISP_CCM_DIMENSION]

    The color correction matrix in float

  bool saturation

    Whether to use saturation when the float data in the matrix is out of the range, For example, if one of the matrix data is 5.0, When saturation is true, and final value will be limited to 4.0, and won't rise error When saturation is false, `esp_isp_ccm_configure` will rise ESP_ERR_INVALID_ARG error

  uint32_t update_once_configured

    If set, apply configuration to hardware immediately; otherwise defer to frame boundary.

  struct esp_isp_ccm_config_t flags

    Driver behaviour flags.

### Header File

- components/esp_driver_isp/include/driver/isp_demosaic.h

- This header file can be included with:

  >     #include "driver/isp_demosaic.h"

- This header file is a part of the API provided by the `esp_driver_isp` component. To declare that your component depends on `esp_driver_isp`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_driver_isp

  > or

  >     PRIV_REQUIRES esp_driver_isp

### Functions

esp_err_t esp_isp_demosaic_configure(isp_proc_handle_t proc, const esp_isp_demosaic_config_t *config)

  ISP Demosaic configuration.

  备注

  After calling this API, Demosaic doesn't take into effect until `esp_isp_demosaic_enable` is called

  参数:

    - proc -- [in] Processor handle

    - config -- [in] Demosaic configurations, set NULL to de-configure the ISP Demosaic

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid

esp_err_t esp_isp_demosaic_enable(isp_proc_handle_t proc)

  Enable ISP Demosaic function.

  参数:

    proc -- [in] Processor handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_demosaic_disable(isp_proc_handle_t proc)

  Disable ISP Demosaic function.

  参数:

    proc -- [in] Processor handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

### Structures

struct esp_isp_demosaic_config_t

  ISP Demosaic configurations.

  Public Members

  isp_demosaic_grad_ratio_t grad_ratio

    Demosaic gradient ratio,

    - gradient_x * grad_ratio < gradient_y, use interpolation results in X direction

    - gradient_y * grad_ratio < gradient_x, use interpolation results in Y direction

    - else use the average results between X and Y

  isp_demosaic_edge_padding_mode_t padding_mode

    Demosaic edge padding mode.

  uint8_t padding_data

    Demosaic edge padding pixel data.

  uint8_t padding_line_tail_valid_start_pixel

    Demosaic edge padding line tail valid start pixel, padding data will only be valid between the valid start pixel and the valid end pixel. Set both the start and end pixel to 0 to make all padding pixel valid.

  uint8_t padding_line_tail_valid_end_pixel

    Demosaic edge padding line tail valid end pixel, padding data will only be valid between the valid start pixel and the valid end pixel. Set both the start and end pixel to 0 to make all padding pixel valid.

### Header File

- components/esp_driver_isp/include/driver/isp_sharpen.h

- This header file can be included with:

  >     #include "driver/isp_sharpen.h"

- This header file is a part of the API provided by the `esp_driver_isp` component. To declare that your component depends on `esp_driver_isp`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_driver_isp

  > or

  >     PRIV_REQUIRES esp_driver_isp

### Functions

esp_err_t esp_isp_sharpen_configure(isp_proc_handle_t proc, const esp_isp_sharpen_config_t *config)

  ISP Sharpen configuration.

  备注

  After calling this API, sharpen doesn't take into effect until `esp_isp_sharpen_enable` is called

  参数:

    - proc -- [in] Processor handle

    - config -- [in] Sharpen configurations, set NULL to de-configure the ISP Sharpen

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid

esp_err_t esp_isp_sharpen_enable(isp_proc_handle_t proc)

  Enable ISP Sharpen function.

  参数:

    proc -- [in] Processor handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_sharpen_disable(isp_proc_handle_t proc)

  Disable ISP Sharpen function.

  参数:

    proc -- [in] Processor handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

### Structures

struct esp_isp_sharpen_config_t

  ISP Sharpen configurations.

  Public Members

  isp_sharpen_h_freq_coeff_t h_freq_coeff

    High freq pixel sharpeness coeff.

  isp_sharpen_m_freq_coeff m_freq_coeff

    Medium freq pixel sharpeness coeff.

  uint8_t h_thresh

    High threshold, pixel value higher than this threshold will be multiplied by `h_freq_coeff`

  uint8_t l_thresh

    Low threshold, pixel value higher than this threshold but lower than `h_thresh` will be multiplied by `m_freq_coeff`. Pixel value lower than this threshold will be set to 0.

  isp_sharpen_edge_padding_mode_t padding_mode

    Sharpen edge padding mode.

  uint8_t padding_data

    Sharpen edge padding pixel data.

  uint8_t sharpen_template[ISP_SHARPEN_TEMPLATE_X_NUMS][ISP_SHARPEN_TEMPLATE_Y_NUMS]

    Sharpen template data.

  uint8_t padding_line_tail_valid_start_pixel

    Sharpen edge padding line tail valid start pixel, padding data will only be valid between the valid start pixel and the valid end pixel. Set both the start and end pixel to 0 to make all padding pixel valid.

  uint8_t padding_line_tail_valid_end_pixel

    Sharpen edge padding line tail valid end pixel, padding data will only be valid between the valid start pixel and the valid end pixel. Set both the start and end pixel to 0 to make all padding pixel valid.

  uint32_t update_once_configured

    If set, apply configuration to hardware immediately; otherwise defer to frame boundary.

  struct esp_isp_sharpen_config_t flags

    Driver behaviour flags.

### Header File

- components/esp_driver_isp/include/driver/isp_gamma.h

- This header file can be included with:

  >     #include "driver/isp_gamma.h"

- This header file is a part of the API provided by the `esp_driver_isp` component. To declare that your component depends on `esp_driver_isp`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_driver_isp

  > or

  >     PRIV_REQUIRES esp_driver_isp

### Functions

esp_err_t esp_isp_gamma_configure(isp_proc_handle_t proc, color_component_t component, const isp_gamma_curve_points_t *pts)

  ISP gamma Correction configuration.

  备注

  This function is allowed to be called before or after esp_isp_gamma_enable(), but it only takes effect until esp_isp_gamma_enable() is called

  参数:

    - proc -- [in] Processor handle

    - component -- [in] One of the R/G/B components, color_component_t

    - pts -- [in]

      Group of points that describe the desired gamma correction curve;

      Passing in NULL to reset to default parameters (no correction)

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid

esp_err_t esp_isp_gamma_enable(isp_proc_handle_t proc)

  Enable ISP gamma function.

  参数:

    proc -- [in] Processor handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

esp_err_t esp_isp_gamma_disable(isp_proc_handle_t proc)

  Disable ISP gamma function.

  参数:

    proc -- [in] Processor handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

esp_err_t esp_isp_gamma_fill_curve_points(uint32_t (*gamma_correction_operator)(uint32_t), isp_gamma_curve_points_t *pts)

  Helper function to fill the isp_gamma_curve_points_t structure, giving the mathematical function of the desired gamma correction curve.

  备注

  The raw values are sampled with equal spacing

  参数:

    - gamma_correction_operator -- [in]

      The desired gamma correction curve y = f(x).

      x is the raw value, in [0, 256]; y is the gamma-corrected value, in [0, 256];

      y can be equal to 256 only if x = 256. For any other x value, y should be always less than 256.

    - pts -- [out] Pointer to the to-be-filled isp_gamma_curve_points_t structure

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

### Header File

- components/esp_driver_isp/include/driver/isp_hist.h

- This header file can be included with:

  >     #include "driver/isp_hist.h"

- This header file is a part of the API provided by the `esp_driver_isp` component. To declare that your component depends on `esp_driver_isp`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_driver_isp

  > or

  >     PRIV_REQUIRES esp_driver_isp

### Functions

esp_err_t esp_isp_new_hist_controller(isp_proc_handle_t isp_proc, const esp_isp_hist_config_t *hist_cfg, isp_hist_ctlr_t *ret_hdl)

  New an ISP hist controller.

  参数:

    - isp_proc -- [in] ISP Processor handle

    - hist_cfg -- [in] Pointer to hist config. Refer to `esp_isp_hist_config_t`.

    - ret_hdl -- [out] hist controller handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid

    - ESP_ERR_INVALID_STATE Invalid state

    - ESP_ERR_NOT_FOUND No free interrupt found with the specified flags

    - ESP_ERR_NO_MEM If out of memory

esp_err_t esp_isp_del_hist_controller(isp_hist_ctlr_t hist_ctlr)

  Delete an ISP hist controller.

  参数:

    hist_ctlr -- [in] hist controller handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_hist_controller_enable(isp_hist_ctlr_t hist_ctlr)

  Enable an ISP hist controller.

  参数:

    hist_ctlr -- [in] hist controller handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_hist_controller_disable(isp_hist_ctlr_t hist_ctlr)

  Disable an ISP hist controller.

  参数:

    hist_ctlr -- [in] hist controller handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_hist_controller_get_oneshot_statistics(isp_hist_ctlr_t hist_ctlr, int timeout_ms, isp_hist_result_t *out_res)

  Trigger hist reference statistics for one time and get the result.

  参数:

    - hist_ctlr -- [in] hist controller handle

    - timeout_ms -- [in] Timeout in millisecond

      - timeout_ms < 0: Won't return until finished

      - timeout_ms = 0: No timeout, trigger one time statistics and return immediately, in this case, the result won't be assigned in this function, but you can get the result in the callback `esp_isp_hist_cbs_t::on_statistics_done`

      - timeout_ms > 0: Wait for specified milliseconds, if not finished, then return timeout error

    - out_res -- [out] hist reference statistics result

  返回:

    - ESP_OK On success

    - ESP_ERR_TIMEOUT Wait for the result timeout

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_hist_controller_start_continuous_statistics(isp_hist_ctlr_t hist_ctlr)

  Start hist continuous statistics of the reference in the window.

  备注

  This function is an asynchronous and non-block function, it will start the continuous statistics and return immediately. You have to register the hist callback and get the result from the callback event data.

  参数:

    hist_ctlr -- [in] hist controller handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG Null pointer

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_hist_controller_stop_continuous_statistics(isp_hist_ctlr_t hist_ctlr)

  Stop hist continuous statistics of the reference in the window.

  参数:

    hist_ctlr -- [in] hist controller handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG Null pointer

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_hist_register_event_callbacks(isp_hist_ctlr_t hist_ctlr, const esp_isp_hist_cbs_t *cbs, void *user_data)

  Register hist event callbacks.

  备注

  User can deregister a previously registered callback by calling this function and setting the to-be-deregistered callback member in the `cbs` structure to NULL.

  备注

  When CONFIG_ISP_ISR_IRAM_SAFE is enabled, the callback itself and functions called by it should be placed in IRAM. Involved variables (including `user_data`) should be in internal RAM as well.

  参数:

    - hist_ctlr -- [in] hist controller handle

    - cbs -- [in] Group of callback functions

    - user_data -- [in] User data, which will be delivered to the callback functions directly

  返回:

    - ESP_OK: On success

    - ESP_ERR_INVALID_ARG: Invalid arguments

    - ESP_ERR_INVALID_STATE: Driver state is invalid, you shouldn't call this API at this moment

### Structures

struct esp_isp_hist_config_t

  Hist controller config.

  Public Members

  isp_window_t window

    The sampling window of histogram, see `isp_window_t`

  isp_hist_sampling_mode_t hist_mode

    ISP histogram sampling mode

  isp_hist_rgb_coefficient_t rgb_coefficient

    RGB coefficients, adjust the sensitivity to red, geen, and blue colors in the image, only effect when hist_mode is ISP_HIST_SAMPLING_RGB, the sum of all coefficients decimal should be 256

  isp_hist_weight_t window_weight[ISP_HIST_BLOCK_X_NUM * ISP_HIST_BLOCK_Y_NUM]

    Weights of histogram's each subwindows, the sum of all subwindows's weight decimal should be 256

  uint32_t segment_threshold[ISP_HIST_INTERVAL_NUMS]

    Threshold to segment the histogram into intervals, range 0~255

struct esp_isp_hist_evt_data_t

  Event data of callbacks.

  Public Members

  isp_hist_result_t hist_result

    The histogram reference statistics result

struct esp_isp_hist_cbs_t

  Group of ISP hist callbacks.

  备注

  These callbacks are all running in an ISR environment.

  备注

  When CONFIG_ISP_ISR_IRAM_SAFE is enabled, the callback itself and functions called by it should be placed in IRAM. Involved variables should be in internal RAM as well.

  Public Members

  esp_isp_hist_callback_t on_statistics_done

    Event callback, invoked when histogram statistic done.

### Type Definitions

typedef bool (*esp_isp_hist_callback_t)(isp_hist_ctlr_t hist_ctlr, const esp_isp_hist_evt_data_t *edata, void *user_data)

  Prototype of ISP hist event callback.

  Param hist_ctlr:

    [in] ISP hist controller handle

  Param edata:

    [in] ISP hist event data

  Param user_data:

    [in] User registered context, registered when in `esp_isp_hist_register_event_callbacks()`

  Return:

    Whether a high priority task is woken up by this function

### Header File

- components/esp_driver_isp/include/driver/isp_color.h

- This header file can be included with:

  >     #include "driver/isp_color.h"

- This header file is a part of the API provided by the `esp_driver_isp` component. To declare that your component depends on `esp_driver_isp`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_driver_isp

  > or

  >     PRIV_REQUIRES esp_driver_isp

### Functions

esp_err_t esp_isp_color_configure(isp_proc_handle_t proc, const esp_isp_color_config_t *config)

  ISP Color configuration.

  备注

  After calling this API, Color doesn't take into effect until `esp_isp_color_enable` is called

  备注

  API is ISR available

  参数:

    - proc -- [in] Processor handle

    - config -- [in] Color configurations, set NULL to de-configure the ISP Color

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid

esp_err_t esp_isp_color_enable(isp_proc_handle_t proc)

  Enable ISP color function.

  参数:

    proc -- [in] Processor handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_color_disable(isp_proc_handle_t proc)

  Disable ISP color function.

  参数:

    proc -- [in] Processor handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

### Structures

struct esp_isp_color_config_t

  ISP color configurations.

  Public Members

  isp_color_contrast_t color_contrast

    The color contrast value, defines the contrast level of the image, which controls the difference in luminance between the lightest and darkest parts of the image Range 0 ~ 1, decimal value should be 0~127, default 1

  isp_color_saturation_t color_saturation

    The color saturation value, controls the intensity of colors in the image, affecting how vivid or muted the colors appear. Range 0 ~ 1, decimal value should be 0~127, default 1

  uint32_t color_hue

    The color hue value, based on the color wheel. 0 degrees represents red, 120 degrees represents green, and 240 degrees represents blue. 360 degrees overlaps with 0 degrees Range 0 ~ 360, default 0.

  int color_brightness

    The color brightness value. Range -128 ~ 127, default 0. Negative range (-128 to -1): Decreases brightness, the smaller the value, the darker the image. Zero (0): Maintains the original brightness, without adjusting the image's brightness. Positive range (1 to 127): Increases brightness, the larger the value, the brighter the image.

  uint32_t update_once_configured

    If set, apply configuration to hardware immediately; otherwise defer to frame boundary.

  struct esp_isp_color_config_t flags

    Driver behaviour flags.

### Header File

- components/esp_driver_isp/include/driver/isp_crop.h

- This header file can be included with:

  >     #include "driver/isp_crop.h"

- This header file is a part of the API provided by the `esp_driver_isp` component. To declare that your component depends on `esp_driver_isp`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_driver_isp

  > or

  >     PRIV_REQUIRES esp_driver_isp

### Functions

esp_err_t esp_isp_crop_configure(isp_proc_handle_t isp_proc, const esp_isp_crop_config_t *config)

  ISP Crop configuration.

  备注

  After calling this API, crop doesn't take into effect until `esp_isp_crop_enable` is called

  参数:

    - isp_proc -- [in] Processor handle

    - config -- [in] Crop configurations, set NULL to de-configure the ISP Crop

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid

esp_err_t esp_isp_crop_enable(isp_proc_handle_t isp_proc)

  Enable ISP crop function.

  参数:

    isp_proc -- [in] Processor handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_crop_disable(isp_proc_handle_t isp_proc)

  Disable ISP crop function.

  参数:

    isp_proc -- [in] Processor handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

### Structures

struct esp_isp_crop_config_t

  ISP crop configurations.

  Public Members

  isp_window_t window

    Crop window coordinates

### Header File

- components/esp_driver_isp/include/driver/isp_core.h

- This header file can be included with:

  >     #include "driver/isp_core.h"

- This header file is a part of the API provided by the `esp_driver_isp` component. To declare that your component depends on `esp_driver_isp`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_driver_isp

  > or

  >     PRIV_REQUIRES esp_driver_isp

### Functions

esp_err_t esp_isp_new_processor(const esp_isp_processor_cfg_t *proc_config, isp_proc_handle_t *ret_proc)

  New an ISP processor.

  参数:

    - proc_config -- [in] Pointer to ISP config. Refer to `esp_isp_processor_cfg_t`.

    - ret_proc -- [out] Processor handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_NOT_FOUND No free interrupt found with the specified flags

    - ESP_ERR_NOT_SUPPORTED Not supported mode

    - ESP_ERR_NO_MEM If out of memory

esp_err_t esp_isp_del_processor(isp_proc_handle_t proc)

  Delete an ISP processor.

  参数:

    proc -- [in] Processor handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_enable(isp_proc_handle_t proc)

  Enable an ISP processor.

  参数:

    proc -- [in] Processor handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_disable(isp_proc_handle_t proc)

  Disable an ISP processor.

  参数:

    proc -- [in] Processor handle

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

    - ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_register_event_callbacks(isp_proc_handle_t proc, const esp_isp_evt_cbs_t *cbs, void *user_data)

  Register ISP event callbacks.

  备注

  User can deregister a previously registered callback by calling this function and setting the to-be-deregistered callback member in the `cbs` structure to NULL.

  备注

  When CONFIG_ISP_ISR_IRAM_SAFE is enabled, the callback itself and functions called by it should be placed in IRAM. Involved variables (including `user_data`) should be in internal RAM as well.

  参数:

    - proc -- [in] Processor handle

    - cbs -- [in] Group of callback functions

    - user_data -- [in] User data, which will be delivered to the callback functions directly

  返回:

    - ESP_OK: On success

    - ESP_ERR_INVALID_ARG: Invalid arguments

    - ESP_ERR_INVALID_STATE: Driver state is invalid, you shouldn't call this API at this moment

### Structures

struct esp_isp_processor_cfg_t

  ISP configurations.

  Public Members

  isp_clk_src_t clk_src

    Clock source.

  uint32_t clk_hz

    Clock frequency in Hz, suggest twice higher than cam sensor speed.

  isp_input_data_source_t input_data_source

    Input data source.

  isp_color_t input_data_color_type

    Input color type.

  isp_color_t output_data_color_type

    Output color type.

  isp_color_range_t yuv_range

    When the `output_data_color_type` is any YUV color space, this field is to describe its color range.

  isp_yuv_conv_std_t yuv_std

    This field is to describe YUV<->RGB conversion standard.

  bool has_line_start_packet

    Enable line start packet.

  bool has_line_end_packet

    Enable line end packet.

  uint32_t h_res

    Input horizontal resolution, i.e. the number of pixels in a line.

  uint32_t v_res

    Input vertical resolution, i.e. the number of lines in a frame.

  color_raw_element_order_t bayer_order

    Bayer order.

  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)

  uint32_t bypass_isp

    Bypass ISP pipelines.

  uint32_t byte_swap_en

    Enable byte swap.

  struct esp_isp_processor_cfg_t flags

    Flags.

### Header File

- components/esp_driver_isp/include/driver/isp_types.h

- This header file can be included with:

  >     #include "driver/isp_types.h"

- This header file is a part of the API provided by the `esp_driver_isp` component. To declare that your component depends on `esp_driver_isp`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_driver_isp

  > or

  >     PRIV_REQUIRES esp_driver_isp

### Structures

struct isp_u32_range_t

  ISP unsigned integer range type.

  备注

  Whether the edge value are included depends on the variable itself

  Public Members

  uint32_t min

    Minimum unsigned int value.

  uint32_t max

    Maximum unsigned int value.

struct isp_float_range_t

  ISP float range type.

  备注

  Whether the edge value are included depends on the variable itself

  Public Members

  float min

    Minimum float value.

  float max

    Maximum float value.

struct isp_af_result_t

  ISP AF result.

  Public Members

  int definition[ISP_AF_WINDOW_NUM]

    Definition, it refers how clear and sharp an image is.

  int luminance[ISP_AF_WINDOW_NUM]

    Luminance, it refers how luminant an image is.

struct isp_awb_subwin_stat_result_t

  ISP AWB subwindow result.

  Public Members

  uint32_t white_patch_num[ISP_AWB_WINDOW_X_NUM][ISP_AWB_WINDOW_Y_NUM]

    white patch number that counted by AWB in the subwindow

  uint32_t sum_r[ISP_AWB_WINDOW_X_NUM][ISP_AWB_WINDOW_Y_NUM]

    The sum of R channel of these white patches.

  uint32_t sum_g[ISP_AWB_WINDOW_X_NUM][ISP_AWB_WINDOW_Y_NUM]

    The sum of G channel of these white patches.

  uint32_t sum_b[ISP_AWB_WINDOW_X_NUM][ISP_AWB_WINDOW_Y_NUM]

    The sum of B channel of these white patches.

struct isp_awb_stat_result_t

  ISP AWB result.

  Public Members

  uint32_t white_patch_num

    white patch number that counted by AWB in the window

  uint32_t sum_r

    The sum of R channel of these white patches.

  uint32_t sum_g

    The sum of G channel of these white patches.

  uint32_t sum_b

    The sum of B channel of these white patches.

  isp_awb_subwin_stat_result_t subwin_result

    The AWB subwindow statistics result.

struct isp_ae_result_t

  ISP AE result.

  Public Members

  int luminance[ISP_AE_BLOCK_X_NUM][ISP_AE_BLOCK_Y_NUM]

    Luminance, it refers how luminant an image is.

struct esp_isp_sharpen_evt_data_t

  Event data structure.

  Public Members

  uint8_t high_freq_pixel_max

    high freq pixel max value

struct esp_isp_evt_cbs_t

  Group of ISP event callbacks.

  备注

  These callbacks are all running in an ISR environment.

  备注

  When CONFIG_ISP_ISR_IRAM_SAFE is enabled, the callback itself and functions called by it should be placed in IRAM. Involved variables should be in internal RAM as well.

  Public Members

  esp_isp_sharpen_callback_t on_sharpen_frame_done

    Event callback, invoked when sharpen frame done.

### Type Definitions

typedef struct isp_processor_t *isp_proc_handle_t

  Type of ISP processor handle.

typedef struct isp_af_controller_t *isp_af_ctlr_t

  Type of ISP AF controller handle.

typedef struct isp_awb_controller_t *isp_awb_ctlr_t

  Type of ISP AWB controller handle.

typedef struct isp_ae_controller_t *isp_ae_ctlr_t

  Type of ISP AE controller handle.

typedef struct isp_hist_controller_t *isp_hist_ctlr_t

  Type of ISP HIST controller handle.

typedef bool (*esp_isp_sharpen_callback_t)(isp_proc_handle_t proc, const esp_isp_sharpen_evt_data_t *edata, void *user_data)

  Prototype of ISP sharpen event callback.

  Param proc:

    [in] Processor handle

  Param edata:

    [in] ISP sharpen event data

  Param user_data:

    [in] User registered context, registered when in `esp_isp_register_event_callbacks()`

  Return:

    Whether a high priority task is woken up by this function

### Header File

- components/hal/include/hal/isp_types.h

- This header file can be included with:

  >     #include "hal/isp_types.h"

### Unions

union isp_demosaic_grad_ratio_t
  #include <isp_types.h>

  Gradient ratio.

  Public Members

  uint32_t decimal

    Integer part.

  uint32_t integer

    Decimal part.

  uint32_t reserved

    Reserved.

  struct isp_demosaic_grad_ratio_t
  uint32_t val

    32-bit gradient ratio value

union isp_sharpen_h_freq_coeff_t
  #include <isp_types.h>

  High freq pixel sharpeness coeff.

  Public Members

  uint32_t decimal

    Decimal part.

  uint32_t integer

    Integer part.

  uint32_t reserved

    Reserved.

  struct isp_sharpen_h_freq_coeff_t
  uint32_t val

    32-bit high freq pixel sharpeness coeff register value

union isp_sharpen_m_freq_coeff
  #include <isp_types.h>

  Medium freq pixel sharpeness coeff.

  Public Members

  uint32_t decimal

    Decimal part.

  uint32_t integer

    Integer part.

  uint32_t reserved

    Reserved.

  struct isp_sharpen_m_freq_coeff
  uint32_t val

    32-bit medium freq pixel sharpeness coeff register value

union isp_hist_weight_t
  #include <isp_types.h>

  ISP histogram weight value.

  Public Members

  uint32_t decimal

    Decimal part.

  uint32_t integer

    Integer part.

  uint32_t reserved

    Reserved.

  struct isp_hist_weight_t
  uint32_t val

    32-bit histogram weight value

union isp_hist_coeff_t
  #include <isp_types.h>

  ISP histogram coefficient value.

  Public Members

  uint32_t decimal

    Decimal part.

  uint32_t integer

    Integer part.

  uint32_t reserved

    Reserved.

  struct isp_hist_coeff_t
  uint32_t val

    32-bit histogram coefficient value

union isp_color_contrast_t
  #include <isp_types.h>

  Color contrast value.

  Public Members

  uint32_t decimal

    Decimal part.

  uint32_t integer

    Integer part.

  uint32_t reserved

    Reserved.

  struct isp_color_contrast_t
  uint32_t val

    32-bit color contrast value

union isp_color_saturation_t
  #include <isp_types.h>

  Color saturation value.

  Public Members

  uint32_t decimal

    Decimal part.

  uint32_t integer

    Integer part.

  uint32_t reserved

    Reserved.

  struct isp_color_saturation_t
  uint32_t val

    32-bit color saturation value

union isp_lsc_gain_t
  #include <isp_types.h>

  LSC gain.

  Public Members

  uint32_t decimal

    Integer part.

  uint32_t integer

    Decimal part.

  uint32_t reserved

    Reserved.

  struct isp_lsc_gain_t
  uint32_t val

    32-bit gradient ratio value

### Structures

struct isp_coordinate_t

  ISP coordinate type.

  Public Members

  uint32_t x

    X coordinate of the point.

  uint32_t y

    Y coordinate of the point.

struct isp_window_t

  The top left and bottom right coordinates of ISP full window.

  Public Members

  isp_coordinate_t top_left

    The top left point coordinate.

  isp_coordinate_t btm_right

    The bottom right point coordinate.

struct isp_awb_gain_t

  ISP AWB gain.

  Public Members

  uint32_t gain_r

    White balance gain for R channel.

  uint32_t gain_g

    White balance gain for G channel.

  uint32_t gain_b

    White balance gain for B channel.

struct isp_gamma_curve_points_t

  Structure that declares the points on an ISP gamma curve.

  Constraint on pt[n].x: When n = 0, pt[n].x = 2 ^ a[n] When 0 < n < ISP_GAMMA_CURVE_POINTS_NUM-1, pt[n].x - pt[n-1].x = 2 ^ a[n] When n = ISP_GAMMA_CURVE_POINTS_NUM-1, pt[n].x = 255, (pt[n].x + 1) - pt[n-1].x = 2 ^ a[n] a[n] within [0, 7]

  Public Members

  uint8_t x

    Raw value (0, 255].

  uint8_t y

    gamma-corrected value (0, 255]

  struct isp_gamma_curve_points_t pt[ISP_GAMMA_CURVE_POINTS_NUM]

    Point (x, y)

struct isp_hist_rgb_coefficient_t

  ISP histogram r,g,b coefficient.

  Public Members

  isp_hist_coeff_t coeff_r

    R coefficient.

  isp_hist_coeff_t coeff_g

    G coefficient.

  isp_hist_coeff_t coeff_b

    B coefficient.

struct isp_hist_result_t

  ISP histogram result.

  Public Members

  uint32_t hist_value[ISP_HIST_SEGMENT_NUMS]

    Histogram value, represents the number of pixels that the histogram window's brightness results fall into the segment X.

struct isp_wbg_gain_t

  ISP White Balance Gain.

  Public Members

  uint32_t gain_r

    White balance gain for R channel.

  uint32_t gain_g

    White balance gain for G channel.

  uint32_t gain_b

    White balance gain for B channel.

### Macros

ISP_AE_BLOCK_X_NUM

ISP_AE_BLOCK_Y_NUM

ISP_AF_WINDOW_NUM

ISP_AWB_WINDOW_X_NUM

ISP_AWB_WINDOW_Y_NUM

ISP_BF_TEMPLATE_X_NUMS

  BF template x field nums.

ISP_BF_TEMPLATE_Y_NUMS

  BF template y field nums.

ISP_CCM_DIMENSION

  ISP Color Correction Matrix dimension.

ISP_DEMOSAIC_GRAD_RATIO_INT_BITS

ISP_DEMOSAIC_GRAD_RATIO_DEC_BITS

ISP_DEMOSAIC_GRAD_RATIO_RES_BITS

ISP_DVP_DATA_SIG_NUM

ISP_SHARPEN_TEMPLATE_X_NUMS

ISP_SHARPEN_TEMPLATE_Y_NUMS

ISP_SHARPEN_H_FREQ_COEF_INT_BITS

ISP_SHARPEN_H_FREQ_COEF_DEC_BITS

ISP_SHARPEN_H_FREQ_COEF_RES_BITS

ISP_SHARPEN_M_FREQ_COEF_INT_BITS

ISP_SHARPEN_M_FREQ_COEF_DEC_BITS

ISP_SHARPEN_M_FREQ_COEF_RES_BITS

ISP_GAMMA_CURVE_POINTS_NUM

  Number of points to define a gamma correction curve.

ISP_HIST_BLOCK_X_NUM

ISP_HIST_BLOCK_Y_NUM

ISP_HIST_SEGMENT_NUMS

ISP_HIST_INTERVAL_NUMS

ISP_HIST_WEIGHT_INT_BITS

ISP_HIST_WEIGHT_DEC_BITS

ISP_HIST_WEIGHT_RES_BITS

ISP_HIST_COEFF_INT_BITS

ISP_HIST_COEFF_DEC_BITS

ISP_HIST_COEFF_RES_BITS

ISP_COLOR_CONTRAST_INT_BITS

ISP_COLOR_CONTRAST_DEC_BITS

ISP_COLOR_CONTRAST_RES_BITS

ISP_COLOR_SATURATION_INT_BITS

ISP_COLOR_SATURATION_DEC_BITS

ISP_COLOR_SATURATION_RES_BITS

ISP_LSC_GRAD_RATIO_INT_BITS

ISP_LSC_GRAD_RATIO_DEC_BITS

ISP_LSC_GRAD_RATIO_RES_BITS

### Type Definitions

typedef soc_periph_isp_clk_src_t isp_clk_src_t

  Clock source type of ISP.

### Enumerations

enum isp_input_data_source_t

  ISP Input Source.

  Values:

  enumerator ISP_INPUT_DATA_SOURCE_CSI

    Input data from CSI.

  enumerator ISP_INPUT_DATA_SOURCE_DVP

    Input data from DVP.

  enumerator ISP_INPUT_DATA_SOURCE_DWGDMA

    Input data from DW-GDMA.

enum isp_color_t

  ISP Color Type.

  Values:

  enumerator ISP_COLOR_RAW8

    RAW8.

  enumerator ISP_COLOR_RAW10

    RAW10.

  enumerator ISP_COLOR_RAW12

    RAW12.

  enumerator ISP_COLOR_RGB888

    RGB888.

  enumerator ISP_COLOR_RGB565

    RGB565.

  enumerator ISP_COLOR_YUV422

    YUV422.

  enumerator ISP_COLOR_YUV420

    YUV420.

enum isp_color_range_t

  ISP color range.

  Values:

  enumerator ISP_COLOR_RANGE_LIMIT

    Limited color range

  enumerator ISP_COLOR_RANGE_FULL

    Full color range

enum isp_yuv_conv_std_t

  The standard used for conversion between RGB and YUV.

  Values:

  enumerator ISP_YUV_CONV_STD_BT601

    YUV<->RGB conversion standard: BT.601

  enumerator ISP_YUV_CONV_STD_BT709

    YUV<->RGB conversion standard: BT.709

enum isp_ae_sample_point_t

  ISP AE input data source.

  Values:

  enumerator ISP_AE_SAMPLE_POINT_AFTER_DEMOSAIC

    AE input data after demosaic.

  enumerator ISP_AE_SAMPLE_POINT_AFTER_GAMMA

    AE input data after gamma.

enum isp_awb_sample_point_t

  ISP AWB sample point in the ISP pipeline.

  Values:

  enumerator ISP_AWB_SAMPLE_POINT_BEFORE_CCM

    Sample AWB data before CCM (Color Correction Matrix)

  enumerator ISP_AWB_SAMPLE_POINT_AFTER_CCM

    Sample AWB data after CCM (Color Correction Matrix)

enum isp_bf_edge_padding_mode_t

  ISP BF edge padding mode.

  Values:

  enumerator ISP_BF_EDGE_PADDING_MODE_SRND_DATA

    Fill BF edge padding data with surrounding pixel data.

  enumerator ISP_BF_EDGE_PADDING_MODE_CUSTOM_DATA

    Fill BF edge padding data with custom pixel data.

enum isp_demosaic_edge_padding_mode_t

  ISP Demosaic edge padding mode.

  Values:

  enumerator ISP_DEMOSAIC_EDGE_PADDING_MODE_SRND_DATA

    Fill Demosaic edge padding data with surrounding pixel data.

  enumerator ISP_DEMOSAIC_EDGE_PADDING_MODE_CUSTOM_DATA

    Fill Demosaic edge padding data with custom pixel data.

enum isp_sharpen_edge_padding_mode_t

  ISP Sharpen edge padding mode.

  Values:

  enumerator ISP_SHARPEN_EDGE_PADDING_MODE_SRND_DATA

    Fill Sharpen edge padding data with surrounding pixel data.

  enumerator ISP_SHARPEN_EDGE_PADDING_MODE_CUSTOM_DATA

    Fill Sharpen edge padding data with custom pixel data.

enum isp_hist_sampling_mode_t

  ISP histogram mode.

  Values:

  enumerator ISP_HIST_SAMPLING_RAW_B

    histogram mode for B component of raw image

  enumerator ISP_HIST_SAMPLING_RAW_GB

    histogram mode for GB component of raw image

  enumerator ISP_HIST_SAMPLING_RAW_GR

    histogram mode for GR component of raw image

  enumerator ISP_HIST_SAMPLING_RAW_R

    histogram mode for R component of raw image

  enumerator ISP_HIST_SAMPLING_RGB

    histogram mode for RGB

  enumerator ISP_HIST_SAMPLING_YUV_Y

    histogram mode for Y component for YUV

  enumerator ISP_HIST_SAMPLING_YUV_U

    histogram mode for U component for YUV

  enumerator ISP_HIST_SAMPLING_YUV_V

    histogram mode for V component for YUV

此文档对您有帮助吗？

- 反馈已收到，谢谢！
- 如果您有其他意见，欢迎填写乐鑫文档反馈表。

- 我们重视您的反馈。
- 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。