图像信号处理器 (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：拜耳域降噪

• CCM：色彩校正矩阵

ISP 流水线

ISP 流水线

功能概述

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

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

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

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

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

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

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

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

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

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

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

• 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 模块。

安装 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_env_detector_evt_cbs_t::on_env_statistics_done 可启动连续统计，调用 esp_isp_ae_env_detector_evt_cbs_t::on_env_change 可停止统计。

若想启用连续统计，需要先注册回调函数 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 色彩控制器

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

可调用 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 状态。

配置 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, &sharpen_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 模块启动后，会动态生成特定事件。

你也可以通过参数 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 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_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::[anonymous] 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.

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, range (-4.0, 4.0)

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

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.

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.

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)

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

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::[anonymous] [anonymous]

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::[anonymous] [anonymous]

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::[anonymous] [anonymous]

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::[anonymous] [anonymous]

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::[anonymous] [anonymous]

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::[anonymous] [anonymous]

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::[anonymous] [anonymous]

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::[anonymous] [anonymous]

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_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::[anonymous] 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.

Macros

ISP_AE_BLOCK_X_NUM

ISP_AE_BLOCK_Y_NUM

ISP_AF_WINDOW_NUM

ISP_BF_TEMPLATE_X_NUMS

ISP_BF_TEMPLATE_Y_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

---

此文档对您有帮助吗？

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

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