图像信号处理器 (ISP)
简介
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:拜耳域降噪
LSC:镜头阴影校正
CCM:色彩校正矩阵
ISP 流水线
功能概述
ISP 驱动程序提供以下服务:
资源分配 - 涵盖如何通过正确的配置来分配 ISP 资源,以及完成工作后如何回收资源。
启用和禁用 ISP - 涵盖如何启用和禁用 ISP 处理器。
单次与连续 AF 数据统计 - 涵盖如何单次或连续获取 AF 统计信息。
单次与连续 AWB 数据统计 - 涵盖如何单次或连续获取 AWB 白块统计信息。
单次与连续 AE 数据统计 - 涵盖如何单次或连续获取 AE 统计信息。
单次与连续直方图数据统计 - 涵盖如何单次或连续获取直方图统计信息。
ISP BF 控制器 - 涵盖如何启用和配置 BF 功能。
ISP LSC 控制器 - 涵盖如何启用和配置 LSC 功能。
配置 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 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 状态。
配置 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
中声明。
线程安全
驱动程序会确保以下工厂函数的线程安全:
使用时,可以直接从不同的 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,函数列表请参见:
应用示例
peripherals/isp/multi_pipelines 演示了如何使用 ISP 流水线处理来自摄像头传感器的图像信号,并通过 DSI 外设在 LCD 屏幕上显示视频。
API 参考
Header File
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 onesp_driver_isp
, add the following to your CMakeLists.txt:REQUIRES esp_driver_isp
or
PRIV_REQUIRES esp_driver_isp
Header File
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 onesp_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)
-
isp_window_t window[ISP_AF_WINDOW_NUM]
-
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.
-
int interval
-
struct esp_isp_af_env_detector_evt_data_t
Event data structure.
Public Members
-
isp_af_result_t af_result
The AF statistics result
-
isp_af_result_t af_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.
-
esp_isp_af_env_detector_callback_t on_env_statistics_done
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
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 onesp_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)
-
isp_ae_sample_point_t sample_point
-
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.
-
int interval
-
struct esp_isp_ae_env_thresh_t
AE environment detector config.
-
struct esp_isp_ae_env_detector_evt_data_t
Event data structure.
Public Members
-
isp_ae_result_t ae_result
The AE statistics result
-
isp_ae_result_t ae_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.
-
esp_isp_ae_env_detector_callback_t on_env_statistics_done
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
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 onesp_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)
-
isp_awb_sample_point_t sample_point
-
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
-
isp_awb_stat_result_t awb_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.
-
esp_isp_awb_callback_t on_statistics_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
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 onesp_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.
-
isp_bf_edge_padding_mode_t padding_mode
Header File
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 onesp_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.
-
isp_lsc_gain_t *gain_r
-
struct esp_isp_lsc_config_t
ISP LSC configurations.
Public Members
-
esp_isp_lsc_gain_array_t *gain_array
Gain array.
-
esp_isp_lsc_gain_array_t *gain_array
Header File
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 onesp_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 untilesp_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
-
float matrix[ISP_CCM_DIMENSION][ISP_CCM_DIMENSION]
Header File
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 onesp_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.
-
isp_demosaic_grad_ratio_t grad_ratio
Header File
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 onesp_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 bym_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.
-
isp_sharpen_h_freq_coeff_t h_freq_coeff
Header File
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 onesp_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
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 onesp_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
-
isp_window_t window
-
struct esp_isp_hist_evt_data_t
Event data of callbacks.
Public Members
-
isp_hist_result_t hist_result
The histogram reference statistics result
-
isp_hist_result_t hist_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.
-
esp_isp_hist_callback_t on_statistics_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
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 onesp_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.
-
isp_color_contrast_t color_contrast
Header File
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 onesp_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)
-
isp_clk_src_t clk_src
Header File
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 onesp_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
-
struct isp_float_range_t
ISP float range type.
备注
Whether the edge value are included depends on the variable itself
-
struct isp_af_result_t
ISP AF result.
-
struct isp_awb_stat_result_t
ISP AWB 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.
-
int luminance[ISP_AE_BLOCK_X_NUM][ISP_AE_BLOCK_Y_NUM]
-
struct esp_isp_sharpen_evt_data_t
Event data structure.
Public Members
-
uint8_t high_freq_pixel_max
high freq pixel max value
-
uint8_t high_freq_pixel_max
-
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.
-
esp_isp_sharpen_callback_t on_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
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.
-
union isp_sharpen_h_freq_coeff_t
- #include <isp_types.h>
High freq pixel sharpeness coeff.
-
union isp_sharpen_m_freq_coeff
- #include <isp_types.h>
Medium freq pixel sharpeness coeff.
-
union isp_hist_weight_t
- #include <isp_types.h>
ISP histogram weight value.
-
union isp_hist_coeff_t
- #include <isp_types.h>
ISP histogram coefficient value.
-
union isp_color_contrast_t
- #include <isp_types.h>
Color contrast value.
-
union isp_color_saturation_t
- #include <isp_types.h>
Color saturation value.
-
union isp_lsc_gain_t
- #include <isp_types.h>
LSC gain.
Structures
-
struct isp_coordinate_t
ISP coordinate type.
-
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.
-
isp_coordinate_t top_left
-
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)
-
uint8_t x
-
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.
-
isp_hist_coeff_t coeff_r
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.
-
enumerator ISP_INPUT_DATA_SOURCE_CSI
-
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.
-
enumerator ISP_COLOR_RAW8
-
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
-
enumerator ISP_COLOR_RANGE_LIMIT
-
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
-
enumerator ISP_YUV_CONV_STD_BT601
-
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.
-
enumerator ISP_AE_SAMPLE_POINT_AFTER_DEMOSAIC
-
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)
-
enumerator ISP_AWB_SAMPLE_POINT_BEFORE_CCM
-
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.
-
enumerator ISP_BF_EDGE_PADDING_MODE_SRND_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.
-
enumerator ISP_DEMOSAIC_EDGE_PADDING_MODE_SRND_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.
-
enumerator ISP_SHARPEN_EDGE_PADDING_MODE_SRND_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
-
enumerator ISP_HIST_SAMPLING_RAW_B