Image Signal Processor (ISP)

[中文]

Introduction

ESP32-P4 includes an Image Signal Processor (ISP), which is a feature pipeline that consists of many image processing algorithms. ISP receives image data from the DVP camera or MIPI-CSI camera, or system memory, and writes the processed image data to the system memory through DMA. The ISP is designed to work with other camera controller modules and can not operate independently.

Terminology

  • MIPI-CSI: Camera serial interface, a high-speed serial interface for cameras compliant with MIPI specifications

  • DVP: Digital video parallel interface, generally composed of vsync, hsync, de, and data signals

  • RAW: Unprocessed data directly output from an image sensor, typically divided into R, Gr, Gb, and B four channels classified into RAW8, RAW10, RAW12, etc., based on bit width

  • RGB: Colored image format composed of red, green, and blue colors classified into RGB888, RGB565, etc., based on the bit width of each color

  • YUV: Colored image format composed of luminance and chrominance classified into YUV444, YUV422, YUV420, etc., based on the data arrangement

  • AF: Auto focus

  • AWB: Auto white balance

  • AE: Auto exposure

  • HIST: Histogram

  • BF: Bayer noise filter

  • BLC: Black Level Correction

  • LSC: Lens Shading Correction

  • CCM: Color correction matrix

ISP Pipeline

ISP Pipeline

Functional Overview

The ISP driver offers following services:

Resource Allocation

Install ISP Driver

ISP driver requires the configuration that specified by esp_isp_processor_cfg_t.

If the configurations in esp_isp_processor_cfg_t is specified, users can call esp_isp_new_processor() to allocate and initialize an ISP processor. This function will return an ISP processor handle if it runs correctly. You can take following code as reference:

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

You can use the created handle to enable/disable the ISP driver and do other ISP module installation.

Note

ISP peripheral is necessary if MIPI CSI or ISP_DVP is used as camera controller. This means that even if ISP functions are not needed, you still need to install the ISP driver by calling esp_isp_new_processor().

If ISP functions are not needed, ISP driver supports bypassing ISP pipelines and enabling only the necessary functions. This can be achieved by setting esp_isp_processor_cfg_t::bypass_isp.

Install ISP Auto Focus (AF) Driver

ISP auto focus (AF) driver requires the configuration that specified by esp_isp_af_config_t.

If the configurations in esp_isp_af_config_t is specified, users can call esp_isp_new_af_controller() to allocate and initialize an ISP AF controller. This function will return an ISP AF controller handle if it runs correctly. You can take following code as reference:

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

You can use the created handle to enable/disable the ISP AF driver and install ISP AF environment detector module.

Install ISP Auto White Balance (AWB) Driver

ISP auto white balance (AWB) driver requires the configuration specified by esp_isp_awb_config_t.

If an esp_isp_awb_config_t configuration is specified, you can call esp_isp_new_awb_controller() to allocate and initialize an ISP AWB controller. This function will return an ISP AWB controller handle on success. You can take following code as reference:

isp_awb_ctlr_t awb_ctlr = NULL;
uint32_t image_width = 800;
uint32_t image_height = 600;
/* The AWB configuration, please refer to the API comment for how to tune these parameters */
esp_isp_awb_config_t awb_config = {
    .sample_point = ISP_AWB_SAMPLE_POINT_1,
    ...
};
ESP_ERROR_CHECK(esp_isp_new_awb_controller(isp_proc, &awb_config, &awb_ctlr));

The AWB handle created in this step is required by other AWB APIs and AWB scheme.

Install ISP Auto Exposure (AE) Driver

ISP auto exposure (AE) driver requires the configuration that specified by esp_isp_ae_config_t.

If the configurations in esp_isp_ae_config_t is specified, call esp_isp_new_ae_controller() to allocate and initialize an ISP AE controller. This function will return an ISP AE controller handle if it runs correctly. You can take following code as reference.

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

You can use the created handle to enable/disable the ISP AE driver and do ISP AE environment detector setup.

Install ISP Histogram (HIST) Driver

ISP histogram (HIST) driver requires the configuration that specified by esp_isp_hist_config_t.

If the configurations in esp_isp_hist_config_t is specified, users can call esp_isp_new_hist_controller() to allocate and initialize an ISP Histogram controller. This function will return an ISP HIST controller handle if it runs correctly. You can take following code as reference.

  • The sum of all subwindow weights' decimal values should be 256; otherwise, the statistics will be small. The integer value should be 0.

  • The sum of all RGB coefficients' decimal values should be 256; otherwise, the statistics will be small. The integer value should be 0.

  • The segment_threshold must be 0–255 and in order.

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

You can use the created handle to enable/disable the ISP HIST driver setup.

Uninstall ISP Drivers

If previously installed ISP drivers are no longer needed, it's recommended to recycle the resource by following APIs to release the underlying hardware:

Enable and Disable ISP

ISP

Before doing ISP pipeline, you need to enable the ISP processor first, by calling esp_isp_enable(). This function:

  • Switches the driver state from init to enable.

Calling esp_isp_disable() does the opposite, that is, put the driver back to the init state.

ISP DMA Input

Besides image streams from camera controllers, the ISP can also read image frames from system memory through DW-GDMA. To use DMA input, set esp_isp_processor_cfg_t::input_data_source in esp_isp_processor_cfg_t to ISP_INPUT_DATA_SOURCE_DWGDMA, and configure the input format, output format, and resolution according to the image frame.

DMA input is useful for feeding software-generated data, offline RAW images, or other test images in memory into the ISP. It can be used to validate an ISP pipeline without a camera sensor, reproduce issues with a specific input image. Call esp_isp_dma_process_frame() to send one input buffer to the ISP and write the processed image into an output buffer. The input and output buffers must be accessible by DMA. The driver synchronizes cacheable buffers automatically. Input buffers use an unaligned cache write-back; cacheable output buffer addresses and their derived frame sizes must be aligned to the cache line size.

ISP AF Controller

Before doing ISP AF, you need to enable the ISP AF controller first, by calling esp_isp_af_controller_enable(). This function:

  • Switches the driver state from init to enable.

Calling esp_isp_af_controller_disable() does the opposite, that is, put the driver back to the init state.

AF One-shot and Continuous Statistics

Calling esp_isp_af_controller_get_oneshot_statistics() to get one-shot AF statistics result. You can take following code as reference.

Aside from the above one-shot API, the ISP AF driver also provides a way to start AF statistics continuously. Calling esp_isp_af_controller_start_continuous_statistics() to start the continuous statistics and esp_isp_af_controller_stop_continuous_statistics() to stop it.

Note that if you want to use the continuous statistics, you need to register the esp_isp_af_env_detector_evt_cbs_t::on_env_statistics_done or esp_isp_af_env_detector_evt_cbs_t::on_env_change callbacks to get the statistics result. See how to register in Register Event Callbacks.

Note

When you use the continuous statistics, AF Environment Detector will be invalid.

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 = {};
/* Trigger the AF statistics and get its result for one time with timeout value 2000 ms */
ESP_ERROR_CHECK(esp_isp_af_controller_get_oneshot_statistics(af_ctrlr, 2000, &result));

/* Start continuous AF statistics */
ESP_ERROR_CHECK(esp_isp_af_controller_start_continuous_statistics(af_ctrlr));
// You can do other stuffs here, the statistics result can be obtained in the callback
// ......
// vTaskDelay(pdMS_TO_TICKS(1000));
/* Stop continuous AF statistics */
ESP_ERROR_CHECK(esp_isp_af_controller_stop_continuous_statistics(af_ctrlr));

/* Disable the AF controller */
ESP_ERROR_CHECK(esp_isp_af_controller_disable(af_ctrlr));
/* Delete the AF controller and free the resources */
ESP_ERROR_CHECK(esp_isp_del_af_controller(af_ctrlr));

Set AF Environment Detector

Calling esp_isp_af_controller_set_env_detector() to set an ISP AF environment detector. You can take following code as reference:

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

Set AF Environment Detector Threshold

Calling esp_isp_af_controller_set_env_detector_threshold() to set the threshold of an ISP AF environment detector.

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 Controller

Before doing ISP AWB, you need to enable the ISP AWB controller first, by calling esp_isp_awb_controller_enable(). This function:

  • Switches the driver state from init to enable.

Calling esp_isp_awb_controller_disable() does the opposite, that is, put the driver back to the init state.

AWB One-shot and Continuous Statistics

Calling esp_isp_awb_controller_get_oneshot_statistics() to get oneshot AWB statistics result of white patches. You can take following code as reference.

Aside from the above one-shot API, the ISP AWB driver also provides a way to start AWB statistics continuously. Calling esp_isp_awb_controller_start_continuous_statistics() starts the continuous statistics and esp_isp_awb_controller_stop_continuous_statistics() stops it.

Note that if you want to use the continuous statistics, you need to register the esp_isp_awb_cbs_t::on_statistics_done callback to get the statistics result. See how to register it in Register Event Callbacks.

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;
/* The AWB configuration, please refer to the API comment for how to tune these parameters */
esp_isp_awb_config_t awb_config = {
    .sample_point = ISP_AWB_SAMPLE_POINT_1,
    ...
};
isp_awb_stat_result_t stat_res = {};
/* Create the AWB controller */
ESP_ERROR_CHECK(esp_isp_new_awb_controller(isp_proc, &awb_config, &awb_ctlr));
/* Register the AWB callback */
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));
/* Enable the AWB controller */
ESP_ERROR_CHECK(esp_isp_awb_controller_enable(awb_ctlr));

/* Get one-shot AWB statistics result */
ESP_ERROR_CHECK(esp_isp_awb_controller_get_oneshot_statistics(awb_ctlr, -1, &stat_res));

/* Start continuous AWB statistics, note that continuous statistics requires `on_statistics_done` callback */
ESP_ERROR_CHECK(esp_isp_awb_controller_start_continuous_statistics(awb_ctlr));
// You can do other stuffs here, the statistics result can be obtained in the callback
// ......
// vTaskDelay(pdMS_TO_TICKS(1000));
/* Stop continuous AWB statistics */
ESP_ERROR_CHECK(esp_isp_awb_controller_stop_continuous_statistics(awb_ctlr));

/* Disable the AWB controller */
ESP_ERROR_CHECK(esp_isp_awb_controller_disable(awb_ctlr));
/* Delete the AWB controller and free the resources */
ESP_ERROR_CHECK(esp_isp_del_awb_controller(awb_ctlr));

ISP AE Controller

Before doing ISP AE, you need to enable the ISP AE controller first, by calling esp_isp_ae_controller_enable(). This function:

  • Switches the driver state from init to enable.

Calling esp_isp_ae_controller_disable() does the opposite, that is, put the driver back to the init state.

AE One-shot and Continuous Statistics

Calling esp_isp_ae_controller_get_oneshot_statistics() to get oneshot AE statistics result. You can take following code as reference.

When using AE oneshot statistics, the AE continuous mode need to be disabled otherwise the result may be overwritten by the environment detector. After oneshot operation finishes, you need to restart continuous mode again.

Aside from the above oneshot API, the ISP AE driver also provides a way to start AE statistics continuously. Calling esp_isp_ae_controller_start_continuous_statistics() to start the continuous statistics and esp_isp_ae_controller_stop_continuous_statistics() to stop it.

Note that if you want to use the continuous statistics, you need to register the esp_isp_ae_env_detector_evt_cbs_t::on_env_statistics_done or esp_isp_ae_env_detector_evt_cbs_t::on_env_change callback to get the statistics result. See how to register in Register Event Callbacks.

Note

When using oneshot statistics, the AE environment detector will be temporarily disabled and will automatically recover once the oneshot is completed.

esp_isp_ae_config_t ae_config = {
    .sample_point = ISP_AE_SAMPLE_POINT_0,
};
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 = {};
/* Trigger the AE statistics and get its result for one time with timeout value 2000 ms. */
ESP_ERROR_CHECK(esp_isp_ae_controller_get_oneshot_statistics(ae_ctlr, 2000, &result));

/* Start continuous AE statistics */
ESP_ERROR_CHECK(esp_isp_ae_controller_start_continuous_statistics(ae_ctlr));
// You can do other stuffs here, the statistics result can be obtained in the callback
// ......
// vTaskDelay(pdMS_TO_TICKS(1000));
/* Stop continuous AE statistics */
ESP_ERROR_CHECK(esp_isp_ae_controller_stop_continuous_statistics(ae_ctlr));

/* Disable the AE controller */
ESP_ERROR_CHECK(esp_isp_ae_controller_disable(ae_ctlr));
/* Delete the AE controller and free the resources */
ESP_ERROR_CHECK(esp_isp_del_ae_controller(ae_ctlr));

Set AE Environment Detector

Calling esp_isp_ae_controller_set_env_detector() to set an ISP AE environment detector. You can take following code as reference.

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

Set AE Environment Detector Threshold

Calling esp_isp_ae_controller_set_env_detector_threshold() to set the thresholds (1-255) of an ISP AE environment detector.

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 Histogram Controller

Before doing ISP histogram statistics, you need to enable the ISP histogram controller first, by calling esp_isp_hist_controller_enable(). This function:

  • Switches the driver state from init to enable.

Calling esp_isp_hist_controller_disable() does the opposite, that is, put the driver back to the init state.

Histogram One-shot and Continuous Statistics

Calling esp_isp_hist_controller_get_oneshot_statistics() to get oneshot histogram statistics result. You can take following code as reference.

Aside from the above oneshot API, the ISP histogram driver also provides a way to start histogram statistics continuously. Calling esp_isp_hist_controller_start_continuous_statistics() starts the continuous statistics and esp_isp_hist_controller_stop_continuous_statistics() stops it.

Note that if you want to use the continuous statistics, you need to register the esp_isp_hist_cbs_t::on_statistics_done callback to get the statistics result. See how to register it in Register Event Callbacks.

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]); // get the histogram statistic value
    }
    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 Controller

This pipeline is used for doing image input denoising under bayer mode.

Calling esp_isp_bf_configure() to configure BF function, you can take following code as reference.

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 is used for bayer denoise. You can set the esp_isp_bf_config_t::bf_template with a Gaussian filter template or an average filter template.

After calling esp_isp_bf_configure(), you need to enable the ISP BF controller, by calling esp_isp_bf_enable(). This function:

  • Switches the driver state from init to enable.

Calling esp_isp_bf_disable() does the opposite, that is, put the driver back to the init state.

ISP BLC Controller

Black Level Correction (BLC) aims for the issues caused by the uneven black level of the image.

Calling esp_isp_blc_configure() to configure the BLC module to do the correction.

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

After calling esp_isp_blc_configure(), you need to enable the ISP BLC controller by calling esp_isp_blc_enable(). This function:

  • Switches the driver state from init to enable.

Calling esp_isp_blc_disable() does the opposite, that is, put the driver back to the init state.

Calling esp_isp_blc_set_correction_offset() to set the BLC correction offset.

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

ISP DPC Controller

Dead Pixel Correction (DPC) corrects defective pixels in RAW Bayer images before later ISP processing stages. Since adjacent Bayer pixels have different colors, DPC uses the eight same-color neighbors around the center pixel to form a 3×3 same-color neighborhood. When it detects a defective pixel, the hardware replaces the center pixel with the neighborhood median.

DPC supports two complementary correction modes:

  • Static correction is intended for defects at fixed locations. Software uses a uniform white frame to calibrate dark pixels and a uniform black frame to calibrate bright pixels, then merges the results into a coordinate list; a previously calibrated list can also be supplied. During configuration, the driver writes the list to the hardware LUT, and the hardware replaces pixels at matching coordinates with the neighborhood median in every frame.

  • Dynamic correction is intended for transient defects or defects at unknown locations and does not require a coordinate list. Dynamic method 1 uses the same-color neighborhood minimum, maximum, and absolute thresholds to detect bright and dark defects. Dynamic method 2 first screens the center pixel with a neighborhood-maximum ratio range, then applies a second test using a neighborhood estimate and adaptive bright and dark factors.

Both modes can be enabled together. While DPC is disabled, call esp_isp_dpc_static_configure() and esp_isp_dpc_dynamic_configure() for the correction modes to use, call esp_isp_dpc_configure() to apply common DPC settings, then call esp_isp_dpc_enable(). To change the static coordinate list, disable DPC before configuring it again.

Static Correction and Calibration

Static correction accepts 0 to 512 esp_isp_dpc_pixel_coord_t coordinates. Each coordinate contains x and y fields. The array must be in ascending y/x order, contain no duplicates, and all coordinates must be inside the input frame. esp_isp_dpc_static_configure() converts the coordinates to the hardware LUT format during the call, so the caller may release the coordinate array after the call returns.

To calibrate the coordinate list, use a uniform white frame to find dark pixels and a uniform black frame to find bright pixels. Each call to a calibration start API internally enables DPC and accepts one corresponding input frame. Reading the result disables DPC again, which allows the next calibration pass or the final static configuration to start.

The following sequence calibrates and enables static correction. white_frame and black_frame must be uniform RAW input frames. Acquire them as follows:

  • White frame: Fill the sensor field of view with a uniform, texture-free bright target, such as an integrating-sphere source or a defocused matte white reflector. Avoid shadows, vignetting, reflections, and saturated areas.

  • Black frame: Block all light, for example with a lens cap or a dark enclosure. Prevent light leaks, status LEDs, and other stray light from reaching the sensor.

The way to feed each frame to the ISP and wait for it to complete depends on the input source. The following uses DMA input as an example; output_frame is the DMA output buffer.

esp_isp_dpc_calibration_config_t white_calibration_config = {
    .threshold = 0xf0,
    .enable_output = true,
};
esp_isp_dpc_calibration_config_t black_calibration_config = {
    .threshold = 0x0a,
    .enable_output = true,
};
static esp_isp_dpc_calibration_ref_t white_ref;
static esp_isp_dpc_calibration_ref_t black_ref;
static esp_isp_dpc_calibration_ref_t merged_ref;

// Find dark defective pixels from a white frame.
esp_isp_dpc_static_calibration_start_once(isp_proc, ESP_ISP_DPC_CALIBRATION_IMAGE_WHITE, &white_calibration_config);
// Feed white_frame to the ISP and wait until processing completes.
// For example, with DMA input:
esp_isp_dma_process_frame(isp_proc, output_frame, white_frame, 1000);
esp_isp_dpc_calibration_read_result(isp_proc, 1000, &white_ref);

// Find bright defective pixels from a black frame.
esp_isp_dpc_static_calibration_start_once(isp_proc, ESP_ISP_DPC_CALIBRATION_IMAGE_BLACK, &black_calibration_config);
// Feed black_frame to the ISP and wait until processing completes.
// For example, with DMA input:
esp_isp_dma_process_frame(isp_proc, output_frame, black_frame, 1000);
esp_isp_dpc_calibration_read_result(isp_proc, 1000, &black_ref);

// Merge, sort, and remove duplicate coordinates before writing the static LUT.
const esp_isp_dpc_calibration_ref_t *calibration_refs[] = {
    &white_ref,
    &black_ref,
};
esp_isp_dpc_calibration_merge_result(calibration_refs, 2, &merged_ref);
esp_isp_dpc_static_config_t static_dpc_config = {
    .dead_pixel_coords = merged_ref.dead_pixel_coords,
    .dead_pixel_count = merged_ref.dead_pixel_count,
};
esp_isp_dpc_config_t common_dpc_config = {
    .flags.update_once_configured = true,
};
esp_isp_dpc_static_configure(isp_proc, &static_dpc_config);
esp_isp_dpc_configure(isp_proc, &common_dpc_config);
esp_isp_dpc_enable(isp_proc);

esp_isp_dpc_calibration_merge_result() is a software-only utility that accepts any positive number of references. It does not access an ISP processor or hardware. It sorts all coordinates by y/x, removes duplicates, and keeps at most ESP_ISP_DPC_MAX_DEAD_PIXELS coordinates.

To merge N references, pass an array of their addresses and the number of elements to esp_isp_dpc_calibration_merge_result():

const esp_isp_dpc_calibration_ref_t *refs[] = {
    &ref_0,
    &ref_1,
    &ref_2,
};
const size_t ref_count = sizeof(refs) / sizeof(refs[0]);
static esp_isp_dpc_calibration_ref_t merged_ref;

ESP_ERROR_CHECK(esp_isp_dpc_calibration_merge_result(refs, ref_count, &merged_ref));

If a factory calibration or another source already provides a defective-pixel coordinate list, the white- and black-frame calibration flow above can be skipped. Pass the coordinate array directly to esp_isp_dpc_static_configure():

static const esp_isp_dpc_pixel_coord_t factory_bad_pixels[] = {
    {.x = 24, .y = 24},
    {.x = 56, .y = 24},
    {.x = 25, .y = 72},
};
esp_isp_dpc_static_config_t static_dpc_config = {
    .dead_pixel_coords = factory_bad_pixels,
    .dead_pixel_count = sizeof(factory_bad_pixels) / sizeof(factory_bad_pixels[0]),
};
esp_isp_dpc_config_t common_dpc_config = {
    .flags.update_once_configured = true,
};
esp_isp_dpc_static_configure(isp_proc, &static_dpc_config);
esp_isp_dpc_configure(isp_proc, &common_dpc_config);
esp_isp_dpc_enable(isp_proc);

Dynamic Correction

Dynamic Method 1

Dynamic method 1 uses absolute thresholds. A pixel is a bright candidate when it is greater than max8 + high_threshold and a dark candidate when it is less than min8 - low_threshold, where min8 and max8 are calculated from the eight same-color neighbors.

esp_isp_dpc_dynamic_config_t dpc_config = {
    .method = ESP_ISP_DPC_DYNAMIC_METHOD_1,
    .method_1 = {
        .high_threshold = 48,
        .low_threshold = 48,
    },
};
esp_isp_dpc_config_t common_dpc_config = {
    .flags.update_once_configured = true,
};
esp_isp_dpc_dynamic_configure(isp_proc, &dpc_config);
esp_isp_dpc_configure(isp_proc, &common_dpc_config);
esp_isp_dpc_enable(isp_proc);
Dynamic Method 2

Dynamic method 2 detects defective pixels in two stages.

The first stage uses the maximum value max8 of the eight same-color neighbors to screen the center pixel pixel_center. The normal range is max8 * first_stage_lower_ratio < pixel_center < max8 * first_stage_upper_ratio: pixels within this range pass the first stage, while pixels equal to a boundary or outside the range receive a second test. The first-stage ratios use fixed-point values: value = integer + decimal / ISP_DPC_RATIO_MAX. Valid values are 0.0 to 1.0. For fractional values, set integer to 0 and decimal to 0 ... ISP_DPC_RATIO_MAX - 1; for example, 0.5 is integer = 0 and decimal = 8. For 1.0, set integer to 1 and decimal to 0.

  • first_stage_lower_ratio (range 0.0 to 1.0): Lower bound of the first-stage normal range. Raising it sends more dark pixels to the second-stage test; lowering it lets more dark pixels pass the first stage.

  • first_stage_upper_ratio (range 0.0 to 1.0): Upper bound of the first-stage normal range. Raising it lets more bright pixels pass the first stage; lowering it sends more bright pixels to the second-stage test. It must be greater than first_stage_lower_ratio, otherwise the configuration function returns ESP_ERR_INVALID_ARG.

The second stage calculates the mean est of the eight neighbors, the absolute difference dif = abs(est - pixel_center) between est and the center pixel, and their mean avg. A dark-pixel candidate is detected when est >= pixel_center and dif > avg * dark_deviation_factor; a bright-pixel candidate is detected when est < pixel_center and dif > (255 - avg) * bright_deviation_factor. The deviation factors use fixed-point values: value = integer + decimal / ISP_DPC_DEVIATION_FACTOR_MAX. Valid values are 0.0 to 1.0. For fractional values, set integer to 0 and decimal to 0 ... ISP_DPC_DEVIATION_FACTOR_MAX - 1; for example, 0.5 is integer = 0 and decimal = 16. For 1.0, set integer to 1 and decimal to 0.

  • dark_deviation_factor (range 0.0 to 1.0): Second-stage dark-pixel sensitivity. Lowering it reduces the required dark-pixel deviation and corrects dark pixels more aggressively; raising it is more conservative.

  • bright_deviation_factor (range 0.0 to 1.0): Second-stage bright-pixel sensitivity. Lowering it reduces the required bright-pixel deviation and corrects bright pixels more aggressively; raising it is more conservative.

esp_isp_dpc_dynamic_config_t dpc_config = {
    .method = ESP_ISP_DPC_DYNAMIC_METHOD_2,
    .method_2 = {
        .first_stage_lower_ratio = {
            .integer = 0,
            .decimal = 8,
        },
        .first_stage_upper_ratio = {
            .integer = 1,
            .decimal = 0,
        },
        .bright_deviation_factor = {
            .integer = 0,
            .decimal = 16,
        },
        .dark_deviation_factor = {
            .integer = 0,
            .decimal = 16,
        },
    },
};
esp_isp_dpc_config_t common_dpc_config = {
    .flags.update_once_configured = true,
};
esp_isp_dpc_dynamic_configure(isp_proc, &dpc_config);
esp_isp_dpc_configure(isp_proc, &common_dpc_config);
esp_isp_dpc_enable(isp_proc);

ISP LSC Controller

Lens Shading Correction (LSC) aims for the issues caused by the uneven refraction of light through the camera lens.

Calling esp_isp_lsc_configure() to configure the LSC module to do the correction. The esp_isp_lsc_gain_array_t is necessary for the hardware to do the correction related calculation. esp_isp_lsc_allocate_gain_array() is a helper function to help allocate proper size of memory for the gains.

esp_isp_lsc_gain_array_t gain_array = {};
size_t gain_size = 0;
ESP_ERROR_CHECK(esp_isp_lsc_allocate_gain_array(isp_proc, &gain_array, &gain_size));

esp_isp_lsc_config_t lsc_config = {
    .gain_array = &gain_array,
};
isp_lsc_gain_t gain_val = {
    .decimal = 204,
    .integer = 0,
};
for (int i = 0; i < gain_size; i++) {
    gain_array.gain_r[i].val = gain_val.val;
    gain_array.gain_gr[i].val = gain_val.val;
    gain_array.gain_gb[i].val = gain_val.val;
    gain_array.gain_b[i].val = gain_val.val;
}
ESP_ERROR_CHECK(esp_isp_lsc_configure(isp_proc, &lsc_config));

After calling esp_isp_lsc_configure(), you need to enable the ISP LSC controller by calling esp_isp_lsc_enable(). The LSC can be disabled by calling esp_isp_lsc_disable(). It is allowed to call esp_isp_lsc_configure() when the LSC is not enabled, but the LSC function will only take effect when it is enabled.

ISP Color Controller

This pipeline is used to adjust the image contrast, saturation, hue and brightness.

Calling esp_isp_color_configure() to configure color function, you can take following code as reference.

  • Contrast value should be 0 ~ 1.0, default 1.0

  • Saturation value should be 0 ~ 1.0, default 1.0

  • Hue value should be 0 ~ 359, default 0

  • Brightness value should be -127 ~ 128, default 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));

After calling esp_isp_color_configure(), you need to enable the ISP color controller, by calling esp_isp_color_enable(). This function:

  • Switches the driver state from init to enable.

Calling esp_isp_color_disable() does the opposite, that is, put the driver back to the init state.

Note

When the ISP DVP peripheral is used with the output color format set to the RGB color space, ISP Color Controller is automatically enabled in the camera driver to ensure correct data output. The function esp_isp_color_disable() should never be called in this case, otherwise it may result in disarrayed camera data.

Configure CCM

Color correction matrix can scale the color ratio of RGB888 pixels. It can be used for adjusting the image color via some algorithms, for example, used for white balance by inputting the AWB computed result, or used as a filter with some filter algorithms.

To adjust the color correction matrix, here is the formula:

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

, and you can refer to the following code:

// ...
// Configure 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));
// The configured CCM will be applied to the image once the CCM module is enabled
ESP_ERROR_CHECK(esp_isp_ccm_enable(isp_proc));
// CCM can also be configured after it is enabled
ccm_cfg.matrix[0][0] = 2.0;
ESP_ERROR_CHECK(esp_isp_ccm_configure(isp_proc, &ccm_cfg));
// Disable CCM if no longer needed
ESP_ERROR_CHECK(esp_isp_ccm_disable(isp_proc));

ISP Demosaic Controller

This pipeline is used for doing image demosaic algorithm to convert RAW image to RGB mode.

Calling esp_isp_demosaic_configure() to configure Demosaic function, you can take following code as reference.

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

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

After calling esp_isp_demosaic_configure(), you need to enable the ISP Demosaic controller, by calling esp_isp_demosaic_enable(). This function:

  • Switches the driver state from init to enable.

Calling esp_isp_demosaic_disable() does the opposite, that is, put the driver back to the init state.

esp_isp_demosaic_configure() is allowed to be called even if the driver is in init state, but the demosaic configurations will only be taken into effect when in enable state.

Enable Gamma Correction

The human visual system is non-linearly sensitive to the physical luminance. Adding gamma correction to the ISP pipeline to transform RGB coordinates into a space in which coordinates are proportional to subjective brightness.

The driver provides a helper API esp_isp_gamma_fill_curve_points() to fill isp_gamma_curve_points_t, which is a group of points used to describe the gamma correction curve. Or you can manually declare the points as your desired gamma correction curve. Each R/G/B component can have its own gamma correction curve, you can set the configuration by calling esp_isp_gamma_configure().

A typical code example is:

#include <math.h>

// Set the camera gamma to be 0.7, so the gamma correction curve is 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));

// Enable gamma module after curve parameters configured
ESP_ERROR_CHECK(esp_isp_gamma_enable(isp_proc));

// Disable gamma if no longer needed
ESP_ERROR_CHECK(esp_isp_gamma_disable(isp_proc));

ISP Sharpen Controller

This pipeline is used for doing image input sharpening under YUV mode.

Calling esp_isp_sharpen_configure() to configure Sharpen function, you can take following code as reference.

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 is used for sharpening. You can set the esp_isp_sharpen_config_t::sharpen_template with a Gaussian filter template or an average filter template.

After calling esp_isp_sharpen_configure(), you need to enable the ISP Sharpen controller, by calling esp_isp_sharpen_enable(). This function:

  • Switches the driver state from init to enable.

Calling esp_isp_sharpen_disable() does the opposite, that is, put the driver back to the init state.

esp_isp_sharpen_configure() is allowed to be called even if the driver is in init state, but the sharpen configurations will only be taken into effect when in enable state.

ISP Image Crop Controller

The ISP image crop function can extract a specified region from the original image, reducing the amount of data for subsequent processing and improving processing efficiency. The crop function is executed at the end of the ISP pipeline and can output a smaller region than the input image.

Note

The ISP image crop function is only available on ESP32-P4 revision 3.0 and above.

Calling esp_isp_crop_configure() to configure the image crop function, you can take the following code as reference:

esp_isp_crop_config_t crop_config = {
    .window = {
        .top_left = {
            .x = 100,  // Top-left X coordinate of crop region
            .y = 100,  // Top-left Y coordinate of crop region
        },
        .btm_right = {
            .x = 699,  // Bottom-right X coordinate of crop region
            .y = 499,  // Bottom-right Y coordinate of crop region
        }
    }
};
ESP_ERROR_CHECK(esp_isp_crop_configure(isp_proc, &crop_config));
ESP_ERROR_CHECK(esp_isp_crop_enable(isp_proc));

After calling esp_isp_crop_configure(), you need to enable the ISP image crop controller by calling esp_isp_crop_enable(). This function:

  • Switches the driver state from init to enable.

Calling esp_isp_crop_disable() does the opposite, that is, put the driver back to the init state.

esp_isp_crop_configure() is allowed to be called even if the driver is in init state, but the crop configurations will only be taken into effect when in enable state.

Note

  • The top-left coordinates (top_left) of the crop region must be smaller than the bottom-right coordinates (btm_right)

  • The top-left coordinates (top_left) of the crop region must be even, and the bottom-right coordinates (btm_right) must be odd

  • The crop region cannot exceed the boundaries of the original image

  • Adjust the display medium (such as LCD) size according to the cropped resolution to ensure complete display and avoid black borders or stretching.

Register Event Callbacks

After an ISP module starts up, it can generate a specific event dynamically.

You can save your own context to callback function as well, via the parameter user_data. The user data will be directly passed to the callback function.

Note

The below-mentioned callback functions are called within an ISR context. You must ensure that the functions do not attempt to block (e.g., by making sure that only FreeRTOS APIs with ISR suffix are called from within the function).

Register ISP Processor Event Callbacks

After the ISP processor is enabled, it can generate multiple events of multiple ISP submodules dynamically. You can hook your functions to the interrupt service routine by calling esp_isp_register_event_callbacks(). All supported event callbacks are listed in esp_isp_evt_cbs_t:

Register ISP AF Environment Detector Event Callbacks

After the ISP AF environment detector starts up, it can generate a specific event dynamically. If you have some functions that should be called when the event happens, please hook your function to the interrupt service routine by calling esp_isp_af_env_detector_register_event_callbacks(). All supported event callbacks are listed in esp_isp_af_env_detector_evt_cbs_t:

Register ISP AWB Statistics Done Event Callbacks

After the ISP AWB controller finished statistics of white patches, it can generate a specific event dynamically. If you want to be informed when the statistics done event takes place, please hook your function to the interrupt service routine by calling esp_isp_awb_register_event_callbacks(). All supported event callbacks are listed in esp_isp_awb_cbs_t:

Register ISP AE Environment Detector Event Callbacks

After the ISP AE environment detector starts up, it can generate a specific event dynamically. If you have some functions that should be called when the event happens, please hook your function to the interrupt service routine by calling esp_isp_ae_env_detector_register_event_callbacks(). All supported event callbacks are listed in esp_isp_ae_env_detector_evt_cbs_t:

Register ISP HIST Statistics Done Event Callbacks

After the ISP HIST controller finished statistics of brightness, it can generate a specific event dynamically. If you want to be informed when the statistics done event takes place, please hook your function to the interrupt service routine by calling esp_isp_hist_register_event_callbacks(). All supported event callbacks are listed in esp_isp_hist_cbs_t:

Thread Safety

The following factory function are guaranteed to be thread safe by the driver:

These functions can be called from different RTOS tasks without protection by extra locks. Other APIs are not guaranteed to be thread-safe.

Kconfig Options

IRAM Safe

By default, the ISP interrupt will be deferred when the cache is disabled because of writing or erasing the flash.

Kconfig option CONFIG_ISP_ISR_IRAM_SAFE will:

  • Enable the interrupt being serviced even when the cache is disabled

  • Place all functions that used by the ISR into IRAM

  • Place driver object into DRAM (in case it is mapped to PSRAM by accident)

This allows the interrupt to run while the cache is disabled, but comes at the cost of increased IRAM consumption. With this option enabled, the ISR callbacks will be running when cache is disabled. Therefore you should make sure the callbacks and its involved context are IRAM-safe as well.

Kconfig option CONFIG_ISP_CTRL_FUNC_IN_IRAM will:

Application Examples

  • peripherals/isp/multi_pipelines demonstrates how to use the ISP pipelines to process the image signals from camera sensors and display the video on LCD screen via DSI peripheral.

  • peripherals/isp/dma_input demonstrates how to feed a RAW8 BGGR image in memory into the ISP through DW-GDMA. pytest_isp_dma_input.py saves the processed RGB888 frames as PPM images and compares them pixel by pixel with the checked-in golden image.

  • esp_video/examples provides some examples of enabling ISP control algorithms.

API Reference

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.

Parameters:

  • 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

Returns:

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

Parameters:

af_ctrlr -- [in] AF controller handle

Returns:

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

Parameters:

af_ctrlr -- [in] AF controller handle

Returns:

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

Parameters:

af_ctrlr -- [in] AF controller handle

Returns:

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

Parameters:

  • 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

Returns:

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

Note

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.

Note

When continuous mode start, AF environment detector will be invalid

Parameters:

af_ctrlr -- [in] AF controller handle

Returns:

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

Parameters:

af_ctrlr -- [in] AF controller handle

Returns:

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

Note

When continuous mode start, AF environment detector will be invalid

Parameters:

  • af_ctrlr -- [in] AF controller handle

  • env_config -- [in] AF Env detector configuration

Returns:

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

Parameters:

  • af_ctrlr -- [in] AF controller handle

  • definition_thresh -- [in] Threshold for definition

  • luminance_thresh -- [in] Threshold for luminance

Returns:

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

Note

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.

Note

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.

Parameters:

  • 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

Returns:

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

Note

These callbacks are all running in an ISR environment.

Note

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.

Parameters:

  • 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

Returns:

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

Parameters:

ae_ctlr -- [in] AE controller handle

Returns:

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

Parameters:

ae_ctlr -- [in] AE controller handle

Returns:

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

Parameters:

ae_ctlr -- [in] AE controller handle

Returns:

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

Parameters:

  • 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

Returns:

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

Note

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.

Note

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

Parameters:

ae_ctlr -- [in] AE controller handle

Returns:

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

Parameters:

ae_ctlr -- [in] AE controller handle

Returns:

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

Parameters:

  • ae_ctlr -- [in] AE controller handle

  • env_config -- [in] AE Env detector configuration

Returns:

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

Parameters:

  • ae_ctlr -- [in] AE controller handle

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

Returns:

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

Note

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.

Note

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.

Parameters:

  • 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

Returns:

  • 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

AE sample point in the ISP pipeline. See TRM for more details. ISP_AE_SAMPLE_POINT_x: see TRM for more details

Different sample points collect different color statistics, which can be used to match different hardware pipelines and AE tuning strategies.

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.

Note

These callbacks are all running in an ISR environment.

Note

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

Parameters:

  • 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

Returns:

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

Parameters:

awb_ctlr -- [in] AWB controller handle

Returns:

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

Note

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

Parameters:

  • awb_ctlr -- [in] AWB controller handle

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

Returns:

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

Parameters:

awb_ctlr -- [in] AWB controller handle

Returns:

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

Parameters:

awb_ctlr -- [in] AWB controller handle

Returns:

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

Parameters:

  • 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

Returns:

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

Note

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.

Parameters:

awb_ctlr -- [in] AWB controller handle

Returns:

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

Parameters:

awb_ctlr -- [in] AWB controller handle

Returns:

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

Note

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.

Note

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.

Parameters:

  • 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

Returns:

  • 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_x: see TRM for more details

Different sample points collect different color statistics, which can be used to match different hardware pipelines and AWB tuning strategies.

isp_window_t window

Statistic main window of AWB. Suggest to set it at the middle of the image and a little smaller than the whole image. It will be more reliable because the edges of image are easily to be overexposure, the overexposure pixels are almost at maximum luminance, which are not good references to calculate the gain for white balance.

isp_window_t subwindow

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

isp_u32_range_t luminance

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

isp_float_range_t red_green_ratio

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

isp_float_range_t blue_green_ratio

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

struct esp_isp_awb_config_t white_patch

white patch configuration

int intr_priority

The interrupt priority, range 0~3, if set to 0, the driver will try to allocate an interrupt with a relative low priority (1,2,3)

struct esp_isp_awb_evt_data_t

Event data of callbacks.

Public Members

isp_awb_stat_result_t awb_result

The AWB white patch statistics result

struct esp_isp_awb_cbs_t

Group of ISP AWB callbacks.

Note

These callbacks are all running in an ISR environment.

Note

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.

Note

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

Parameters:

  • proc -- [in] Processor handle

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

Returns:

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

Parameters:

proc -- [in] Processor handle

Returns:

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

Parameters:

proc -- [in] Processor handle

Returns:

  • ESP_OK On success

  • ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

  • ESP_ERR_INVALID_STATE Driver state is invalid.

Structures

struct esp_isp_bf_config_t

ISP BF configurations.

Public Members

isp_bf_edge_padding_mode_t padding_mode

BF edge padding mode.

uint8_t padding_data

BF edge padding pixel data.

uint8_t bf_template[ISP_BF_TEMPLATE_X_NUMS][ISP_BF_TEMPLATE_Y_NUMS]

BF template data.

uint8_t denoising_level

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

uint8_t padding_line_tail_valid_start_pixel

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

uint8_t padding_line_tail_valid_end_pixel

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

uint32_t update_once_configured

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

struct esp_isp_bf_config_t flags

Driver behaviour flags.

Header File

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

  • This header file can be included with:

    #include "driver/isp_blc.h"

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

    REQUIRES esp_driver_isp

    or

    PRIV_REQUIRES esp_driver_isp

Functions

esp_err_t esp_isp_blc_configure(isp_proc_handle_t isp_proc, const esp_isp_blc_config_t *config)

ISP BLC configuration.

Note

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

Parameters:

  • isp_proc -- [in] Processor handle

  • config -- [in] BLC configurations

Returns:

  • ESP_OK On success

  • ESP_ERR_INVALID_STATE Not allowed to be called under current state

  • ESP_ERR_INVALID_ARG If the combination of arguments is invalid

  • ESP_ERR_NOT_SUPPORTED Not supported

esp_err_t esp_isp_blc_enable(isp_proc_handle_t isp_proc)

Enable ISP BLC function.

Parameters:

isp_proc -- [in] Processor handle

Returns:

  • ESP_OK On success

  • ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

  • ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_blc_set_correction_offset(isp_proc_handle_t isp_proc, esp_isp_blc_offset_t *offset)

Set the correction offset of ISP BLC function.

Parameters:

  • isp_proc -- [in] Processor handle

  • offset -- [in] Correction offset

esp_err_t esp_isp_blc_disable(isp_proc_handle_t isp_proc)

Disable ISP BLC function.

Parameters:

isp_proc -- [in] Processor handle

Returns:

  • ESP_OK On success

  • ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

  • ESP_ERR_INVALID_STATE Driver state is invalid.

Structures

struct esp_isp_blc_thresh_t

ISP BLC threshold configurations.

Public Members

uint8_t top_left_chan_thresh

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

uint8_t top_right_chan_thresh

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

uint8_t bottom_left_chan_thresh

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

uint8_t bottom_right_chan_thresh

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

struct esp_isp_blc_stretch_t

ISP BLC stretch configurations.

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

Public Members

bool top_left_chan_stretch_en

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

bool top_right_chan_stretch_en

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

bool bottom_left_chan_stretch_en

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

bool bottom_right_chan_stretch_en

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

struct esp_isp_blc_config_t

ISP BLC configurations.

Public Members

isp_window_t window

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

esp_isp_blc_thresh_t filter_threshold

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

bool filter_enable

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

esp_isp_blc_stretch_t stretch

Stretch configurations for each channel of the raw Bayer image.

uint32_t update_once_configured

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

struct esp_isp_blc_config_t flags

Driver behaviour flags.

struct esp_isp_blc_offset_t

ISP BLC correction offset.

Public Members

uint32_t top_left_chan_offset

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

uint32_t top_right_chan_offset

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

uint32_t bottom_left_chan_offset

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

uint32_t bottom_right_chan_offset

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

Header File

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

  • This header file can be included with:

    #include "driver/isp_lsc.h"

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

    REQUIRES esp_driver_isp

    or

    PRIV_REQUIRES esp_driver_isp

Functions

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

Helper function to allocate gain array for LSC.

Parameters:

  • isp_proc -- [in] Processor handle

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

  • out_array_size_per_channel -- [out] Array size

Returns:

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

Note

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

Parameters:

  • isp_proc -- [in] Processor handle

  • config -- [in] LSC configurations

Returns:

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

Parameters:

isp_proc -- [in] Processor handle

Returns:

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

Parameters:

isp_proc -- [in] Processor handle

Returns:

  • ESP_OK On success

  • ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

  • ESP_ERR_INVALID_STATE Driver state is invalid.

Structures

struct esp_isp_lsc_gain_array_t

LSC Gain array.

Public Members

isp_lsc_gain_t *gain_r

Gain for R channel.

isp_lsc_gain_t *gain_gr

Gain for GR channel.

isp_lsc_gain_t *gain_gb

Gain for GB channel.

isp_lsc_gain_t *gain_b

Gain for B channel.

struct esp_isp_lsc_config_t

ISP LSC configurations.

Public Members

esp_isp_lsc_gain_array_t *gain_array

Gain array.

Header File

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

  • This header file can be included with:

    #include "driver/isp_ccm.h"

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

    REQUIRES esp_driver_isp

    or

    PRIV_REQUIRES esp_driver_isp

Functions

esp_err_t esp_isp_ccm_configure(isp_proc_handle_t proc, const esp_isp_ccm_config_t *ccm_cfg)

ISP Color Correction Matrix (CCM) configuration.

Note

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

Parameters:

  • proc -- [in] Processor handle

  • ccm_cfg -- [in] CCM configurations

Returns:

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

Parameters:

proc -- [in] Processor handle

Returns:

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

Parameters:

proc -- [in] Processor handle

Returns:

  • ESP_OK On success

  • ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

Structures

struct esp_isp_ccm_config_t

Color Correction Matrix configurations.

Public Members

float matrix[ISP_CCM_DIMENSION][ISP_CCM_DIMENSION]

The color correction matrix in float

bool saturation

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

uint32_t update_once_configured

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

struct esp_isp_ccm_config_t flags

Driver behaviour flags.

Header File

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

  • This header file can be included with:

    #include "driver/isp_demosaic.h"

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

    REQUIRES esp_driver_isp

    or

    PRIV_REQUIRES esp_driver_isp

Functions

esp_err_t esp_isp_demosaic_configure(isp_proc_handle_t proc, const esp_isp_demosaic_config_t *config)

ISP Demosaic configuration.

Note

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

Parameters:

  • proc -- [in] Processor handle

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

Returns:

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

Parameters:

proc -- [in] Processor handle

Returns:

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

Parameters:

proc -- [in] Processor handle

Returns:

  • 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_dpc.h

  • This header file can be included with:

    #include "driver/isp_dpc.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_dpc_configure(isp_proc_handle_t isp_proc, const esp_isp_dpc_config_t *config)

Configure common ISP DPC settings.

Note

Call this while DPC is disabled, after configuring any required static and dynamic correction paths, and before esp_isp_dpc_enable(). This API configures the common clock and shadow-register update behavior; it does not configure or enable static or dynamic correction.

Parameters:

  • isp_proc -- [in] Processor handle

  • config -- [in] DPC common configuration

Returns:

  • ESP_OK On success

  • ESP_ERR_INVALID_STATE DPC is enabled

  • ESP_ERR_INVALID_ARG Invalid argument

esp_err_t esp_isp_dpc_enable(isp_proc_handle_t isp_proc)

Enable ISP DPC function.

Note

Call esp_isp_dpc_static_configure and/or esp_isp_dpc_dynamic_configure, then esp_isp_dpc_configure, first. Static and dynamic correction can be configured together. Static calibration is a separate flow started by esp_isp_dpc_static_calibration_start_once; that API enables DPC internally.

Parameters:

isp_proc -- [in] Processor handle

Returns:

  • 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_dpc_disable(isp_proc_handle_t isp_proc)

Disable ISP DPC function.

Parameters:

isp_proc -- [in] Processor handle

Returns:

  • 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_dpc_config_t

ISP DPC common configuration.

This configuration controls common DPC behavior only. Configure static LUT coordinates with esp_isp_dpc_static_configure() and dynamic algorithm parameters with esp_isp_dpc_dynamic_configure().

Public Members

uint32_t update_once_configured

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

struct esp_isp_dpc_config_t flags

Driver behavior flags.

Header File

  • components/esp_driver_isp/include/driver/isp_dpc_dynamic.h

  • This header file can be included with:

    #include "driver/isp_dpc_dynamic.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_dpc_dynamic_configure(isp_proc_handle_t isp_proc, const esp_isp_dpc_dynamic_config_t *config)

Configure dynamic DPC correction.

Note

Call this while DPC is disabled. This function enables dynamic correction but does not enable the DPC module; call esp_isp_dpc_configure() and then esp_isp_dpc_enable() afterwards. Static and dynamic correction can be configured together.

Parameters:

  • isp_proc -- [in] Processor handle

  • config -- [in] Dynamic correction configuration

Returns:

  • ESP_OK On success

  • ESP_ERR_INVALID_ARG Invalid argument or dynamic parameters

  • ESP_ERR_INVALID_STATE DPC is enabled

  • ESP_ERR_NOT_SUPPORTED Not supported

Structures

struct esp_isp_dpc_dynamic_config_t

ISP DPC dynamic correction configurations.

Note

Both methods examine the eight same-color neighboring pixels and replace a detected dead pixel with their median value. Method 1 directly compares the center pixel with the neighboring minimum and maximum using absolute thresholds. Method 2 first keeps pixels within a max8-based ratio range. For pixels outside that range, it compares the center pixel with the neighboring-pixel estimate using adaptive bright and dark thresholds.

Public Members

esp_isp_dpc_dynamic_method_t method

Dynamic correction method.

uint8_t high_threshold

A pixel above max8 + high_threshold is a bright dead-pixel candidate (0-255)

uint8_t low_threshold

A pixel below min8 - low_threshold is a dark dead-pixel candidate (0-255)

isp_dpc_ratio_t first_stage_upper_ratio

Upper bound of the first-stage normal-pixel range. Value = integer + decimal / ISP_DPC_RATIO_MAX. Range 0 ~ 1. Fractional values use integer 0 and decimal 0 ~ (ISP_DPC_RATIO_MAX - 1); 1.0 uses integer 1 and decimal 0. Must be greater than first_stage_lower_ratio.

isp_dpc_ratio_t first_stage_lower_ratio

Lower bound of the first-stage normal-pixel range. Value = integer + decimal / ISP_DPC_RATIO_MAX. Range 0 ~ 1. Fractional values use integer 0 and decimal 0 ~ (ISP_DPC_RATIO_MAX - 1); 1.0 uses integer 1 and decimal 0.

isp_dpc_deviation_factor_t bright_deviation_factor

Second-stage bright-pixel sensitivity. Value = integer + decimal / ISP_DPC_DEVIATION_FACTOR_MAX. Range 0 ~ 1. Fractional values use integer 0 and decimal 0 ~ (ISP_DPC_DEVIATION_FACTOR_MAX - 1); 1.0 uses integer 1 and decimal 0. A smaller value corrects bright pixels more aggressively.

isp_dpc_deviation_factor_t dark_deviation_factor

Second-stage dark-pixel sensitivity. Value = integer + decimal / ISP_DPC_DEVIATION_FACTOR_MAX. Range 0 ~ 1. Fractional values use integer 0 and decimal 0 ~ (ISP_DPC_DEVIATION_FACTOR_MAX - 1); 1.0 uses integer 1 and decimal 0. A smaller value corrects dark pixels more aggressively.

Enumerations

enum esp_isp_dpc_dynamic_method_t

ISP DPC dynamic correction method.

Method 1 uses absolute thresholds around the minimum and maximum of the eight neighboring pixels. Method 2 uses ratios and a second adaptive test against the neighboring-pixel estimate.

Values:

enumerator ESP_ISP_DPC_DYNAMIC_METHOD_1

Detects a pixel outside [min8 - low_threshold, max8 + high_threshold].

enumerator ESP_ISP_DPC_DYNAMIC_METHOD_2

Applies ratio screening followed by an estimate-based adaptive threshold test.

Header File

  • components/esp_driver_isp/include/driver/isp_dpc_static.h

  • This header file can be included with:

    #include "driver/isp_dpc_static.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_dpc_static_configure(isp_proc_handle_t isp_proc, const esp_isp_dpc_static_config_t *config)

Configure static DPC correction.

Note

Call this while DPC is disabled. This function writes the coordinates to the hardware LUT and enables static correction. It does not enable the DPC module; call esp_isp_dpc_configure() and then esp_isp_dpc_enable() afterwards. The driver reads dead_pixel_coords only during this call and does not retain the array after it returns.

Parameters:

  • isp_proc -- [in] Processor handle

  • config -- [in] Static correction configuration

Returns:

  • ESP_OK On success

  • ESP_ERR_INVALID_STATE DPC is enabled

  • ESP_ERR_INVALID_ARG Invalid argument or coordinates

  • ESP_ERR_NOT_SUPPORTED Not supported

esp_err_t esp_isp_dpc_static_calibration_start_once(isp_proc_handle_t isp_proc, esp_isp_dpc_calibration_image_t image_type, const esp_isp_dpc_calibration_config_t *config)

Start DPC static calibration onetime.

Note

After calling this function, input a uniform frame matching image_type, then call esp_isp_dpc_calibration_read_result to wait for completion and read the results. Static correction is enabled and dynamic correction is disabled while calibration check mode is enabled. DPC must not be enabled before calling this function.

Parameters:

  • isp_proc -- [in] Processor handle

  • image_type -- [in] Calibration image type

  • config -- [in] Calibration configuration

Returns:

  • 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_dpc_calibration_read_result(isp_proc_handle_t isp_proc, uint32_t timeout_ms, esp_isp_dpc_calibration_ref_t *result)

Read DPC static calibration results.

Note

This function waits for calibration completion, then disables check mode and DPC before reading the LUT. The result storage is supplied by the caller.

Parameters:

  • isp_proc -- [in] Processor handle

  • timeout_ms -- [in] Maximum wait time in milliseconds; zero polls once

  • result -- [out] Calibration coordinate reference

Returns:

  • ESP_OK On success

  • ESP_ERR_INVALID_ARG If the combination of arguments is invalid

  • ESP_ERR_INVALID_STATE Calibration is not running

  • ESP_ERR_TIMEOUT Calibration did not complete within the timeout

esp_err_t esp_isp_dpc_calibration_merge_result(const esp_isp_dpc_calibration_ref_t *const refs[], size_t ref_count, esp_isp_dpc_calibration_ref_t *merged_ref)

Merge static calibration coordinate references.

Note

This is a software-only utility. It does not access an ISP processor or any hardware resource. It combines the coordinates from ref_count references, sorts them by y/x, removes duplicates, and keeps at most ESP_ISP_DPC_MAX_DEAD_PIXELS coordinates. The output reference must not also appear in refs.

Parameters:

  • refs -- [in] Array of pointers to the coordinate references to merge

  • ref_count -- [in] Number of entries in refs, must be greater than zero

  • merged_ref -- [out] Merged coordinate reference

Returns:

  • ESP_OK On success

  • ESP_ERR_INVALID_ARG If the combination of arguments is invalid

Structures

struct esp_isp_dpc_pixel_coord_t

DPC pixel coordinate.

Public Members

uint16_t x

Horizontal coordinate.

uint16_t y

Vertical coordinate.

struct esp_isp_dpc_static_config_t

ISP DPC static correction configurations.

Public Members

const esp_isp_dpc_pixel_coord_t *dead_pixel_coords

Unique coordinates in ascending y/x order. Coordinates must be inside the input frame. The driver reads this array only during esp_isp_dpc_static_configure().

uint32_t dead_pixel_count

Number of dead pixels in the array (0 to ESP_ISP_DPC_MAX_DEAD_PIXELS)

struct esp_isp_dpc_calibration_config_t

ISP DPC static calibration configuration.

Public Members

uint8_t threshold

Dead-pixel threshold. For a white image, lower pixels are considered dead pixels; for a black image, higher pixels are considered dead pixels.

bool enable_output

Whether to output the calibration frame. When false, DPC records detected coordinates without outputting image data.

struct esp_isp_dpc_calibration_ref_t

ISP DPC calibration coordinate reference.

Public Members

esp_isp_dpc_pixel_coord_t dead_pixel_coords[ESP_ISP_DPC_MAX_DEAD_PIXELS]

Dead pixel coordinates.

uint32_t dead_pixel_count

Number of valid coordinates in dead_pixel_coords.

Macros

ESP_ISP_DPC_MAX_DEAD_PIXELS

Maximum number of dead pixels supported by the static DPC LUT.

Enumerations

enum esp_isp_dpc_calibration_image_t

DPC calibration image type.

Values:

enumerator ESP_ISP_DPC_CALIBRATION_IMAGE_WHITE

Uniform white frame, used to detect dark dead pixels.

enumerator ESP_ISP_DPC_CALIBRATION_IMAGE_BLACK

Uniform black frame, used to detect bright dead pixels.

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.

Note

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

Parameters:

  • proc -- [in] Processor handle

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

Returns:

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

Parameters:

proc -- [in] Processor handle

Returns:

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

Parameters:

proc -- [in] Processor handle

Returns:

  • ESP_OK On success

  • ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

  • ESP_ERR_INVALID_STATE Driver state is invalid.

Structures

struct esp_isp_sharpen_config_t

ISP Sharpen configurations.

Public Members

isp_sharpen_h_freq_coeff_t h_freq_coeff

High freq pixel sharpeness coeff.

isp_sharpen_m_freq_coeff m_freq_coeff

Medium freq pixel sharpeness coeff.

uint8_t h_thresh

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

uint8_t l_thresh

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

isp_sharpen_edge_padding_mode_t padding_mode

Sharpen edge padding mode.

uint8_t padding_data

Sharpen edge padding pixel data.

uint8_t sharpen_template[ISP_SHARPEN_TEMPLATE_X_NUMS][ISP_SHARPEN_TEMPLATE_Y_NUMS]

Sharpen template data.

uint8_t padding_line_tail_valid_start_pixel

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

uint8_t padding_line_tail_valid_end_pixel

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

uint32_t update_once_configured

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

struct esp_isp_sharpen_config_t flags

Driver behaviour flags.

Header File

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

  • This header file can be included with:

    #include "driver/isp_gamma.h"

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

    REQUIRES esp_driver_isp

    or

    PRIV_REQUIRES esp_driver_isp

Functions

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

ISP gamma Correction configuration.

Note

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

Parameters:

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

Returns:

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

Parameters:

proc -- [in] Processor handle

Returns:

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

Parameters:

proc -- [in] Processor handle

Returns:

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

Note

The raw values are sampled with equal spacing

Parameters:

  • 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

Returns:

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

Parameters:

  • 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

Returns:

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

Parameters:

hist_ctlr -- [in] hist controller handle

Returns:

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

Parameters:

hist_ctlr -- [in] hist controller handle

Returns:

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

Parameters:

hist_ctlr -- [in] hist controller handle

Returns:

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

Parameters:

  • 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

Returns:

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

Note

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.

Parameters:

hist_ctlr -- [in] hist controller handle

Returns:

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

Parameters:

hist_ctlr -- [in] hist controller handle

Returns:

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

Note

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.

Note

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.

Parameters:

  • 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

Returns:

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

Note

These callbacks are all running in an ISR environment.

Note

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.

Note

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

Note

API is ISR available

Parameters:

  • proc -- [in] Processor handle

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

Returns:

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

Parameters:

proc -- [in] Processor handle

Returns:

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

Parameters:

proc -- [in] Processor handle

Returns:

  • 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. Range 0 ~ 359, default 0.

int color_brightness

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

uint32_t update_once_configured

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

struct esp_isp_color_config_t flags

Driver behaviour flags.

Header File

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

  • This header file can be included with:

    #include "driver/isp_crop.h"

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

    REQUIRES esp_driver_isp

    or

    PRIV_REQUIRES esp_driver_isp

Functions

esp_err_t esp_isp_crop_configure(isp_proc_handle_t isp_proc, const esp_isp_crop_config_t *config)

ISP Crop configuration.

Note

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

Parameters:

  • isp_proc -- [in] Processor handle

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

Returns:

  • ESP_OK On success

  • ESP_ERR_INVALID_ARG If the combination of arguments is invalid

esp_err_t esp_isp_crop_enable(isp_proc_handle_t isp_proc)

Enable ISP crop function.

Parameters:

isp_proc -- [in] Processor handle

Returns:

  • ESP_OK On success

  • ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

  • ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_crop_disable(isp_proc_handle_t isp_proc)

Disable ISP crop function.

Parameters:

isp_proc -- [in] Processor handle

Returns:

  • ESP_OK On success

  • ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

  • ESP_ERR_INVALID_STATE Driver state is invalid.

Structures

struct esp_isp_crop_config_t

ISP crop configurations.

Public Members

isp_window_t window

Crop window coordinates

Header File

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

  • This header file can be included with:

    #include "driver/isp_core.h"

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

    REQUIRES esp_driver_isp

    or

    PRIV_REQUIRES esp_driver_isp

Functions

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

New an ISP processor.

Parameters:
Returns:

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

Parameters:

proc -- [in] Processor handle

Returns:

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

Parameters:

proc -- [in] Processor handle

Returns:

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

Parameters:

proc -- [in] Processor handle

Returns:

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

Note

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.

Note

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.

Parameters:

  • proc -- [in] Processor handle

  • cbs -- [in] Group of callback functions

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

Returns:

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

uint32_t dma_burst_size

DMA output burst length in units of 64-bit beats. Set to 0 to use default value 16.

int intr_priority

The interrupt priority, range 0~3, if set to 0, the driver will try to allocate an interrupt with a relative low priority (1,2,3)

uint32_t bypass_isp

Bypass ISP pipelines.

uint32_t byte_swap_en

Enable byte swap.

struct esp_isp_processor_cfg_t flags

Flags.

Header File

  • components/esp_driver_isp/include/driver/isp_dma.h

  • This header file can be included with:

    #include "driver/isp_dma.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_dma_process_frame(isp_proc_handle_t proc, void *output_buffer, const void *input_buffer, uint32_t timeout_ms)

Process one ISP DMA frame: feed the input buffer through the ISP and wait for completion.

Note

The driver synchronizes cacheable buffers before and after DMA access. Input buffers use an unaligned cache write-back, while cacheable output buffers and their derived frame sizes must be aligned to the cache line size.

Note

This function blocks until both input and output DMA channels finish. On timeout, the output buffer may still be owned by DMA and must not be accessed.

Parameters:

  • proc -- [in] Processor handle

  • output_buffer -- [in] Destination buffer for ISP output

  • input_buffer -- [in] Source input buffer for RAW frame data

  • timeout_ms -- [in] Timeout in milliseconds for waiting transfer completion

Returns:

  • ESP_OK On success

  • ESP_ERR_INVALID_ARG Invalid argument

  • ESP_ERR_TIMEOUT Wait timeout

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.

Note

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.

Note

Whether the edge value are included depends on the variable itself

Public Members

float min

Minimum float value.

float max

Maximum float value.

struct isp_af_result_t

ISP AF result.

Public Members

int definition[ISP_AF_WINDOW_NUM]

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

int luminance[ISP_AF_WINDOW_NUM]

Luminance, it refers how luminant an image is.

struct isp_awb_subwin_stat_result_t

ISP AWB subwindow result.

Public Members

uint32_t white_patch_num[ISP_AWB_WINDOW_X_NUM][ISP_AWB_WINDOW_Y_NUM]

white patch number that counted by AWB in the subwindow

uint32_t sum_r[ISP_AWB_WINDOW_X_NUM][ISP_AWB_WINDOW_Y_NUM]

The sum of R channel of these white patches.

uint32_t sum_g[ISP_AWB_WINDOW_X_NUM][ISP_AWB_WINDOW_Y_NUM]

The sum of G channel of these white patches.

uint32_t sum_b[ISP_AWB_WINDOW_X_NUM][ISP_AWB_WINDOW_Y_NUM]

The sum of B channel of these white patches.

struct isp_awb_stat_result_t

ISP AWB result.

Public Members

uint32_t white_patch_num

white patch number that counted by AWB in the window

uint32_t sum_r

The sum of R channel of these white patches.

uint32_t sum_g

The sum of G channel of these white patches.

uint32_t sum_b

The sum of B channel of these white patches.

isp_awb_subwin_stat_result_t subwin_result

The AWB subwindow statistics result.

struct isp_ae_result_t

ISP AE result.

Public Members

int luminance[ISP_AE_BLOCK_X_NUM][ISP_AE_BLOCK_Y_NUM]

Luminance, it refers how luminant an image is.

struct esp_isp_sharpen_evt_data_t

Event data structure.

Public Members

uint8_t high_freq_pixel_max

high freq pixel max value

struct esp_isp_evt_cbs_t

Group of ISP event callbacks.

Note

These callbacks are all running in an ISR environment.

Note

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/esp_hal_cam/include/hal/isp_types.h

  • This header file can be included with:

    #include "hal/isp_types.h"

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

    REQUIRES esp_hal_cam

    or

    PRIV_REQUIRES esp_hal_cam

Unions

union isp_demosaic_grad_ratio_t
#include <isp_types.h>

Gradient ratio.

Public Members

uint32_t decimal

Integer part.

uint32_t integer

Decimal part.

uint32_t reserved

Reserved.

struct isp_demosaic_grad_ratio_t
uint32_t val

32-bit gradient ratio value

union isp_sharpen_h_freq_coeff_t
#include <isp_types.h>

High freq pixel sharpeness coeff.

Public Members

uint32_t decimal

Decimal part.

uint32_t integer

Integer part.

uint32_t reserved

Reserved.

struct isp_sharpen_h_freq_coeff_t
uint32_t val

32-bit high freq pixel sharpeness coeff register value

union isp_sharpen_m_freq_coeff
#include <isp_types.h>

Medium freq pixel sharpeness coeff.

Public Members

uint32_t decimal

Decimal part.

uint32_t integer

Integer part.

uint32_t reserved

Reserved.

struct isp_sharpen_m_freq_coeff
uint32_t val

32-bit medium freq pixel sharpeness coeff register value

union isp_hist_weight_t
#include <isp_types.h>

ISP histogram weight value.

Public Members

uint32_t decimal

Decimal part.

uint32_t integer

Integer part.

uint32_t reserved

Reserved.

struct isp_hist_weight_t
uint32_t val

32-bit histogram weight value

union isp_hist_coeff_t
#include <isp_types.h>

ISP histogram coefficient value.

Public Members

uint32_t decimal

Decimal part.

uint32_t integer

Integer part.

uint32_t reserved

Reserved.

struct isp_hist_coeff_t
uint32_t val

32-bit histogram coefficient value

union isp_color_contrast_t
#include <isp_types.h>

Color contrast value.

Public Members

uint32_t decimal

Decimal part.

uint32_t integer

Integer part.

uint32_t reserved

Reserved.

struct isp_color_contrast_t
uint32_t val

32-bit color contrast value

union isp_color_saturation_t
#include <isp_types.h>

Color saturation value.

Public Members

uint32_t decimal

Decimal part.

uint32_t integer

Integer part.

uint32_t reserved

Reserved.

struct isp_color_saturation_t
uint32_t val

32-bit color saturation value

union isp_dpc_ratio_t
#include <isp_types.h>

ISP DPC first-stage ratio.

Note

Value = integer + decimal / ISP_DPC_RATIO_MAX. Range 0 ~ 1. Fractional values use integer 0 and decimal 0 ~ (ISP_DPC_RATIO_MAX - 1); 1.0 uses integer 1 and decimal 0.

Public Members

uint32_t decimal

Decimal part.

uint32_t integer

Integer part.

uint32_t reserved

Reserved.

struct isp_dpc_ratio_t
uint32_t val

32-bit first-stage ratio register value

union isp_dpc_deviation_factor_t
#include <isp_types.h>

ISP DPC second-stage deviation factor.

Note

Value = integer + decimal / ISP_DPC_DEVIATION_FACTOR_MAX. Range 0 ~ 1. Fractional values use integer 0 and decimal 0 ~ (ISP_DPC_DEVIATION_FACTOR_MAX - 1); 1.0 uses integer 1 and decimal 0.

Public Members

uint32_t decimal

Decimal part.

uint32_t integer

Integer part.

uint32_t reserved

Reserved.

struct isp_dpc_deviation_factor_t
uint32_t val

32-bit deviation factor register value

union isp_lsc_gain_t
#include <isp_types.h>

LSC gain.

Public Members

uint32_t decimal

Integer part.

uint32_t integer

Decimal part.

uint32_t reserved

Reserved.

struct isp_lsc_gain_t
uint32_t val

32-bit gradient ratio value

Structures

struct isp_coordinate_t

ISP coordinate type.

Public Members

uint32_t x

X coordinate of the point.

uint32_t y

Y coordinate of the point.

struct isp_window_t

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

Public Members

isp_coordinate_t top_left

The top left point coordinate.

isp_coordinate_t btm_right

The bottom right point coordinate.

struct isp_awb_gain_t

ISP AWB gain.

Public Members

uint32_t gain_r

White balance gain for R channel.

uint32_t gain_g

White balance gain for G channel.

uint32_t gain_b

White balance gain for B channel.

struct isp_gamma_curve_points_t

Structure that declares the points on an ISP gamma curve.

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

Public Members

uint8_t x

Raw value (0, 255].

uint8_t y

gamma-corrected value (0, 255]

struct isp_gamma_curve_points_t pt[ISP_GAMMA_CURVE_POINTS_NUM]

Point (x, y)

struct isp_hist_rgb_coefficient_t

ISP histogram r,g,b coefficient.

Public Members

isp_hist_coeff_t coeff_r

R coefficient.

isp_hist_coeff_t coeff_g

G coefficient.

isp_hist_coeff_t coeff_b

B coefficient.

struct isp_hist_result_t

ISP histogram result.

Public Members

uint32_t hist_value[ISP_HIST_SEGMENT_NUMS]

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

struct isp_wbg_gain_t

ISP White Balance Gain.

Public Members

uint32_t gain_r

White balance gain for R channel.

uint32_t gain_g

White balance gain for G channel.

uint32_t gain_b

White balance gain for B channel.

Macros

ISP_AE_BLOCK_X_NUM
ISP_AE_BLOCK_Y_NUM
ISP_AF_WINDOW_NUM
ISP_AWB_WINDOW_X_NUM
ISP_AWB_WINDOW_Y_NUM
ISP_BF_TEMPLATE_X_NUMS

BF template x field nums.

ISP_BF_TEMPLATE_Y_NUMS

BF template y field nums.

ISP_CCM_DIMENSION

ISP Color Correction Matrix dimension.

ISP_DEMOSAIC_GRAD_RATIO_INT_BITS
ISP_DEMOSAIC_GRAD_RATIO_DEC_BITS
ISP_DEMOSAIC_GRAD_RATIO_RES_BITS
ISP_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_DPC_RATIO_INT_BITS
ISP_DPC_RATIO_DEC_BITS
ISP_DPC_RATIO_RES_BITS
ISP_DPC_RATIO_MAX
ISP_DPC_DEVIATION_FACTOR_INT_BITS
ISP_DPC_DEVIATION_FACTOR_DEC_BITS
ISP_DPC_DEVIATION_FACTOR_RES_BITS
ISP_DPC_DEVIATION_FACTOR_MAX
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 packed in UYVY order.

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_0

AE sample point 0, see TRM for more details.

enumerator ISP_AE_SAMPLE_POINT_1

AE sample point 1, see TRM for more details.

enumerator ISP_AE_SAMPLE_POINT_AFTER_DEMOSAIC

Deprecated alias of ISP_AE_SAMPLE_POINT_0

enumerator ISP_AE_SAMPLE_POINT_AFTER_GAMMA

Deprecated alias of ISP_AE_SAMPLE_POINT_1

enum isp_awb_sample_point_t

ISP AWB sample point in the ISP pipeline.

Values:

enumerator ISP_AWB_SAMPLE_POINT_0

AWB sample point 0, see TRM for more details.

enumerator ISP_AWB_SAMPLE_POINT_1

AWB sample point 1, see TRM for more details.

enumerator ISP_AWB_SAMPLE_POINT_BEFORE_CCM

Deprecated alias of ISP_AWB_SAMPLE_POINT_0

enumerator ISP_AWB_SAMPLE_POINT_AFTER_CCM

Deprecated alias of ISP_AWB_SAMPLE_POINT_1

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

Was this page helpful?