diff options
Diffstat (limited to 'include/ia_imaging/ia_aiq.h')
| -rw-r--r-- | include/ia_imaging/ia_aiq.h | 626 |
1 files changed, 626 insertions, 0 deletions
diff --git a/include/ia_imaging/ia_aiq.h b/include/ia_imaging/ia_aiq.h new file mode 100644 index 0000000..10c9372 --- /dev/null +++ b/include/ia_imaging/ia_aiq.h @@ -0,0 +1,626 @@ +/* + * Copyright (C) 2015 - 2018 Intel Corporation. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/*! + * \mainpage IA AIQ API documentation + * + * Browse Files and Classes tabs for details. + * + * \section general General info + * + * AIQ API has been designed to be re-entrant. Each algorithm function can be called multiple times per frame. + * Input parameters for the algorithms define what is the output ie. running an algorithm with same input parameters + * and same statistics produce the same output. For example one can run AE multiple times with different EV compensations + * to get parameters for exposure bracketing. + * + * AIQ (Algorithms and Image Quality) library contains several algorithm which are used to modify RAW image. + * Currently following features and algorithms are supported: + * - \ref aec (Automatic Exposure Control) + * - \ref awb (Automatic White Balance) + * - \ref af (Automatic Focus) + * - \ref sa (Shading Adaptor) + * - \ref pa (Parameter Adaptor) + * - \ref dsd (Discrete Scene Detection) + * - \ref gbce (Global Brightness and Contrast Enhancement) + * + * AIQ also supports calculation of parameters for multiframe bracketing cases: + * - \ref afbracket (Automatic Focus Bracket) + * - \ref aebracket (Automatic Exposure Bracket) + * + * Running AIQ algorithms requires following steps: + * - \ref init + * - \ref stats + * - \ref running + * - \ref deinit + * + * Some AIQ algorithms require coordinates as inputs to specify a certain area in the image. Coordinates are relative to + * the statistics thus not necessarily the whole sensor area. Coordinates are not absolute but relative. See \link ia_coordinate.h \endlink + * for detailed description of the used coordinate system. + * <br><hr><br> + * + * \section init Initialization of AIQ library + * + * \copybrief ia_aiq_init + * To create an instance of AIQ library one must call function: + * \code ia_aiq_init \endcode + * \copydetails ia_aiq_init + * + * <br><hr><br> + * + * \section stats Setting of frame statistics + * + * Algorithms depend on statistics collected from the RAW image. Some or all of the statistics are + * calculated by the ISP after RAW image capture from camera sensor. These statistics are always collected from + * captured image data. To convert statistics from ISP specific format to AIQ format, a helper function can be used: + * \code ia_isp_XXX_statistics_convert \endcode + * See ia_isp documentation for details. + * + * \copybrief ia_aiq_statistics_set + * To set statistics for algorithms AIQ library, one must call function: + * \code ia_aiq_statistics_set \endcode + * \copydetails ia_aiq_statistics_set + * + * Algorithms can also utilize external sensor data for making better decisions. For example external light sensor + * can be used by AEC to determine correct cold start exposure parameters when AEC is called the first time without + * statistics. + * + * \copybrief ia_aiq_sensor_events_set + * To set external sensor data statistics for algorithms AIQ library, one must call function: + * \code ia_aiq_sensor_events_set \endcode + * \copydetails ia_aiq_sensor_events_set + * + * <br><hr><br> + * + * \section running Running AIQ algorithms + * + * Once the AIQ instance is initialized and statistics are set, algorithms can be run in any order. + * \subsection af AF + * \copybrief ia_aiq_af_run + * \code ia_aiq_af_run \endcode + * \copydetails ia_aiq_af_run + * + * \subsection aec AEC + * \copybrief ia_aiq_ae_run + * \code ia_aiq_ae_run \endcode + * \copydetails ia_aiq_ae_run + * + * \subsection awb AWB + * \copybrief ia_aiq_awb_run + * \code ia_aiq_awb_run \endcode + * \copydetails ia_aiq_awb_run + * + * \subsection sa SA + * \copybrief ia_aiq_sa_run + * \code ia_aiq_sa_run \endcode + * \copydetails ia_aiq_sa_run + * + * \subsection pa PA + * \copybrief ia_aiq_pa_run + * \code ia_aiq_pa_run \endcode + * \copydetails ia_aiq_pa_run + * + * \subsection dsd DSD + * \copybrief ia_aiq_dsd_run + * \code ia_aiq_dsd_run \endcode + * \copydetails ia_aiq_dsd_run + * + * \subsection gbce GBCE + * \copybrief ia_aiq_gbce_run + * \code ia_aiq_gbce_run \endcode + * \copydetails ia_aiq_gbce_run + * + * \subsection afbracket AF Bracket + * \copybrief ia_aiq_af_bracket + * \code ia_aiq_af_bracket \endcode + * \copydetails ia_aiq_af_bracket + * + * \subsection aebracket AE Bracket & HDR + * AEC supports outputting of multiple exposure results. By setting the "num_exposures" parameter >1 in ia_aiq_ae_input_params, AEC determines + * the best exposure parameters to cover as much as possible of the sensor's dynamic range. AIQ's client can then queue the exposure parameters + * to the sensor for consecutive frames for best speed. + * + * HDR support in AEC works the same way. Client requests >1 "num_exposures" but also gives AIQ the resulting statistics from all requested + * exposures. AEC uses the given (multiple) statistics to calculate new exposure parameters. + * + * + * <br><hr><br> + * + * \section deinit De-initialization of AIQ library + * + * To de-initialize and free memory AIQ library instance has allocated, one must call function: + * \code + * ia_aiq_deinit + * \endcode + * + * After this call AIQ library instance is destroyed and can't be used. + */ + +/*! + * \file ia_aiq.h + * \brief Definitions and declarations of Intel 3A library. + */ + +#ifndef _IA_AIQ_H_ +#define _IA_AIQ_H_ + +#include "ia_aiq_types.h" +#include "ia_types.h" +#include "ia_face.h" +#include "ia_mkn_types.h" +#include "ia_cmc_types.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/*! + * \brief Initialize IA_AIQ and its submodules. + * This function must be called before any other function in the library. It allocates memories for all AIQ algorithms based on input parameters + * given by the user. AIQB (from CPFF) and NVM data are parsed and combined resulting camera module specific tuning parameters which the + * AIQ algorithms use. Initialization returns a handle to the AIQ instance, which is given as input parameter for all the + * algorithms. Therefore, multiple instances of AIQ library can running simultaneously. For example one instance per camera. + * + * \param[in] aiqb_data Mandatory although function will not return error, if it not given.\n + * Contains tuning parameters for AIQ algorithms. + * \param[in] nvm_data Optional.\n + * NVM (Non Volatile Memory) containing sensor unit specific calibration data. + * AIC uses camera unit specific calibration data, if given. + * \param[in] aiqd_data Optional.\n + * AIQ generic input data, provided by the host. Contains various AIQ related information, collected + * during run-time and stored in a host file system. AIQ will parse this data in to internal storage. + * \param[in] stats_max_width Mandatory.\n + * Maximum width of RGBS and AF statistics grids from ISP. Used to calculate size of + * memory buffers for the IA_AIQ algorithms. The same maximum width will be used for all RGBS + * and AF statistics grid allocations. + * \param[in] stats_max_height Mandatory.\n + * Maximum height of RGBS and AF statistics grids from ISP. Used to calculate size of + * memory buffers for the IA_AIQ algorithms. The same maximum height will be used for all RGBS + * and AF statistics grid allocations. + * \param[in] max_num_stats_in Mandatory.\n + * The maximum number of input statistics for one frame. Each statistics is related to different exposure. + * Used especially for sensors that support two or more simultaneous exposures (HDR). + * \param[in] ia_cmc Mandatory.\n + * Parsed camera module characterization structure. ia_cmc structure needs to be kept available by client for + * the lifetime of AIQ component. + * \param[in,out] ia_mkn Optional.\n + * Makernote handle which can be initialized with ia_mkn library. If debug data from AIQ is needed + * to be stored into EXIF, this parameter is needed. Algorithms will update records inside this makernote instance. + * Client writes the data into Makernote section in EXIF. + * return IA_AIQ handle. Use the returned handle as input parameter for the consequent IA_AIQ calls. + */ +LIBEXPORT ia_aiq* +ia_aiq_init(const ia_binary_data *aiqb_data, + const ia_binary_data *nvm_data, + const ia_binary_data *aiqd_data, + unsigned int stats_max_width, + unsigned int stats_max_height, + unsigned int max_num_stats_in, + ia_cmc_t *ia_cmc, + ia_mkn *ia_mkn); + +/*! + * \brief Set tuning to an existing AIQ instance. + * This function can be used to switch tunings on-the-fly in a way that 3A preserves its state and offers smooth transition from one tuning to another. + */ +LIBEXPORT ia_err +ia_aiq_set_tuning(ia_aiq *ia_aiq, + const ia_binary_data *aiqb_data); + +/*! + * \brief De-initialize IA_AIQ and its submodules. + * All memory allocated by AIQ algoriths are freed. AIQ handle can no longer be used. + * + * \param[in] ia_aiq Mandatory.\n + * AIQ instance handle. + */ +LIBEXPORT void +ia_aiq_deinit(ia_aiq *ia_aiq); + +/*! + * \brief Manual AEC limit parameters. + */ +typedef struct +{ + int manual_exposure_time_min; /*!< Optional. Minimum exposure time in microseconds. -1 if NA. */ + int manual_exposure_time_max; /*!< Optional. Maximum exposure time in microseconds. -1 if NA. */ + int manual_frame_time_us_min; /*!< Optional. Manual minimum frame length in microseconds. Defines maximum frame rate -1 if NA. */ + int manual_frame_time_us_max; /*!< Optional. Manual maximum frame length in microseconds. Defines minimum frame rate. -1 if NA. */ + short manual_iso_min; /*!< Optional. Manual minimum ISO. -1 if NA. */ + short manual_iso_max; /*!< Optional. Manual maximum ISO. -1 if NA. */ +} ia_aiq_ae_manual_limits; + +/*! + * \brief Input parameter structure for AE algorithm. + */ +typedef struct +{ + unsigned int num_exposures; /*!< Mandatory. The number of exposure outputs to have. Must be positive. One for LDR, two or more for HDR/exposure bracketing. */ + ia_aiq_frame_use frame_use; /*!< Mandatory. Target frame type of the AEC calculations (Preview, Still, video etc.). */ + ia_aiq_flash_mode flash_mode; /*!< Mandatory. Manual flash mode. If AEC should make flash decision, set mode to ia_aiq_flash_mode_auto. */ + ia_aiq_ae_operation_mode operation_mode; /*!< Mandatory. AEC operation mode. */ + ia_aiq_ae_metering_mode metering_mode; /*!< Mandatory. AEC metering mode. */ + ia_aiq_ae_priority_mode priority_mode; /*!< Mandatory. AEC priority mode. */ + ia_aiq_ae_flicker_reduction flicker_reduction_mode; /*!< Mandatory. AEC flicker reduction mode. */ + ia_aiq_exposure_sensor_descriptor *sensor_descriptor; /*!< Mandatory although function will not return error, if not given. + Sensor specific descriptor and limits of the used sensor mode for target frame use. + AEC will not limit and calculate sensor specific parameters, if not given */ + ia_rectangle *exposure_window; /*!< Optional. Rectangle of area which AEC uses to to calculate new exposure parameters. */ + ia_coordinate *exposure_coordinate; /*!< Optional. Coordinate for a point in which the exposure should be prioritized. + AEC increases weight of given point in final AEC results. */ + float ev_shift; /*!< Optional. Exposure Value shift [-4,4]. */ + long *manual_exposure_time_us; /*!< Optional. Manual exposure time in microseconds. NULL if NA. Otherwise, array of values + of num_exposures length. Order of exposure times corresponds to exposure_index of ae_results, + e.g., manual_exposure_time_us[ae_results->exposures[0].exposure_index] = 33000; */ + float *manual_analog_gain; /*!< Optional. Manual analog gain. NULL if NA. Otherwise, array of values of num_exposures length. + Order of gain values corresponds to exposure_index of ae_results, + e.g., manual_analog_gain[ae_results->exposures[0].exposure_index] = 4.0f; */ + short *manual_iso; /*!< Optional. Manual ISO. Overrides manual_analog_gain. NULL if NA. Otherwise, array of values + of num_exposures length. Order of ISO values corresponds to exposure_index of ae_results, + e.g., manual_iso[ae_results->exposures[0].exposure_index] = 100; */ + ia_aiq_ae_features *aec_features; /*!< Optional. AEC features in use when calculating new exposure parameters. */ + ia_aiq_ae_manual_limits *manual_limits; /*!< Optional. Manual limits which override limits defined in AEC tunings. */ + float manual_aperture_fn; /*!< Optional. Manual f-number of aperture (e.g. 2.8), -1.0 for N/A. Used only with P iris. */ + ia_aiq_aperture_control_dc_iris_command manual_dc_iris_command; /*!< Optional. Used only with DC iris. 0 (auto) for N/A. */ + ia_aiq_ae_exposure_distribution_priority exposure_distribution_priority; /*!< Mandatory. AEC exposure distribution priority mode. */ + float manual_convergence_time; /*!< Optional. Manual AEC convergence speed in seconds. -1.0 if NA. Overrides convergence speed from tunings. */ +} ia_aiq_ae_input_params; + +/*! + * \brief AEC calculation based on input parameters and frame statistics. + * AE calculates new exposure parameters to be used for the next frame based on previously given statistics and user parameters. + * + * \param[in] ia_aiq Mandatory.\n + * AIQ instance handle. + * \param[in] ae_input_params Mandatory.\n + * Input parameters for AEC calculations. + * \param[out] ae_results Mandatory.\n + * Pointer's pointer where address of ISP parameters are stored. + * Results from AEC calculations. Results can be used directly as input for AIC. + * \return Error code. + */ +LIBEXPORT ia_err +ia_aiq_ae_run(ia_aiq *ia_aiq, + const ia_aiq_ae_input_params *ae_input_params, + ia_aiq_ae_results **ae_results); + +/*! + * \brief Input parameter structure for AF algorithm. + */ +typedef struct +{ + ia_aiq_frame_use frame_use; /*!< Mandatory. Target frame type of the AF calculations (Preview, Still, video etc.). */ + int lens_position; /*!< Mandatory. Current lens position. */ + unsigned long long lens_movement_start_timestamp; /*!< Mandatory. Lens movement start timestamp in us. Timestamp is compared against statistics timestamp + to determine if lens was moving during statistics collection. */ + ia_aiq_af_operation_mode focus_mode; /*!< Mandatory. Focusing mode. */ + ia_aiq_af_range focus_range; /*!< Mandatory. Focusing range. Only valid when focus_mode is ia_aiq_af_operation_mode_auto. */ + ia_aiq_af_metering_mode focus_metering_mode; /*!< Mandatory. Metering mode (multispot, touch). */ + ia_aiq_flash_mode flash_mode; /*!< Mandatory. User setting for flash. */ + ia_rectangle *focus_rect; /*!< Optional. */ + ia_aiq_manual_focus_parameters *manual_focus_parameters; /*!< Optional. Manual focus parameters (manual lens position, manual focusing distance). Used only if + focus mode 'ia_aiq_af_operation_mode_manual' is used. */ + bool trigger_new_search; /*!< TRUE if new AF search is needed, FALSE otherwise. Host is responsible for flag cleaning. */ +} ia_aiq_af_input_params; + +/*! + * \brief AF calculation based on input parameters and frame statistics. + * AF calculates new lens position based on statistics and given input parameters. + * + * \param[in] ia_aiq Mandatory.\n + * AIQ instance handle. + * \param[in] af_input_params Mandatory.\n + * Input parameters for AF calculations. + * \param[out] af_results Mandatory.\n + * Pointer's pointer where address of AF results are stored. + * Results from AF calculations. + * \return Error code. + */ +LIBEXPORT ia_err +ia_aiq_af_run(ia_aiq *ia_aiq, + const ia_aiq_af_input_params *af_input_params, + ia_aiq_af_results **af_results); + +/*! + * \brief Input parameter structure for AWB algorithm. + */ +typedef struct +{ + ia_aiq_frame_use frame_use; /*!< Mandatory. Target frame type of the AWB calculations (Preview, Still, video etc.). */ + ia_aiq_awb_operation_mode scene_mode; /*!< Mandatory. AWB scene mode. */ + ia_aiq_awb_manual_cct_range *manual_cct_range; /*!< Optional. Manual CCT range. Used only if AWB scene mode 'ia_aiq_awb_operation_manual_cct_range' is used. */ + ia_coordinate *manual_white_coordinate; /*!< Optional. Manual white point coordinate relative to the full FOV of the scene. Used only if AWB scene mode 'ia_aiq_awb_operation_manual_white' is used. */ + float manual_convergence_time; /*!< Optional. Manual AWB convergence speed in seconds. -1.0 if NA. Overrides convergence speed from tunings. */ +} ia_aiq_awb_input_params; + +/*! + * \brief AWB calculation based on input parameters and frame statistics. + * + * \param[in] ia_aiq Mandatory.\n + * AIQ instance handle. + * \param[in] awb_input_params Mandatory.\n + * Input parameters for AWB calculations. + * \param[out] awb_results Mandatory.\n + * Pointer's pointer where address of AWB results are stored. + * Results from AWB calculations. Results can be used directly as input for ia_isp. + * \return Error code. + */ +LIBEXPORT ia_err +ia_aiq_awb_run(ia_aiq *ia_aiq, + const ia_aiq_awb_input_params *awb_input_params, + ia_aiq_awb_results **awb_results); + + +/*! + * \brief Input parameter structure for GBCE algorithm. + */ +typedef struct +{ + ia_aiq_gbce_level gbce_level; /*!< Mandatory. GBCE level. -1 to use tuning defaults.*/ + ia_aiq_tone_map_level tone_map_level; /*!< Mandatory. Tone Map level. -1 to use tuning defaults.*/ + ia_aiq_frame_use frame_use; /*!< Mandatory. Target frame type of the GBCE calculations (Preview, Still, video etc.). */ + float ev_shift; /*!< Optional. Exposure Value shift [-4,4]. */ +} ia_aiq_gbce_input_params; + +/*! + * \brief GBCE calculation based on input parameters and frame statistics. + * Computes gamma + * + * \param[in] ia_aiq Mandatory.\n + * AIQ instance handle. + * \param[in] gbce_input_params Mandatory.\n + * Input parameters for GBCE calculations. + * \param[out] gbce_results Mandatory.\n + * Pointer's pointer where address of GBCE results are stored. + * Results contain GBCE Gamma table. Results can be used directly as input for AIC. + * \return Error code. + */ +LIBEXPORT ia_err +ia_aiq_gbce_run(ia_aiq *ia_aiq, + const ia_aiq_gbce_input_params *gbce_input_params, + ia_aiq_gbce_results **gbce_results); + +/*! + * \brief Input parameter structure for DSD algorithm. + */ +typedef struct +{ + ia_aiq_af_results *af_results; /*!< Mandatory although function will not return error, if not given. + DSD will not return all scene modes, if not given. */ + ia_aiq_scene_mode scene_modes_selection; /*!<configure which scene modes should be detected by DSD*/ +} ia_aiq_dsd_input_params; + +/*! + * \brief DSD based on statistics analysis. + * Determine scene (DSD) the given image. + * + * \param[in] ia_aiq Mandatory.\n + * AIQ instance handle. + * \param[in] dsd_input_params Mandatory.\n + * Input parameters for DSD calculations. + * \param[out] dsd_scene Mandatory.\n + * Detected scene mode. + * \return Error code. + */ +LIBEXPORT ia_err +ia_aiq_dsd_run(ia_aiq *ia_aiq, + const ia_aiq_dsd_input_params *dsd_input_params, + ia_aiq_scene_mode *dsd_scene); + +/*! + * \brief Input parameter structure for Parameter adaptor. + */ +typedef struct +{ + ia_aiq_awb_results *awb_results; /*!< Mandatory. WB results which are to be used to calculate next ISP parameters (WB gains, color matrix,etc). */ + ia_aiq_exposure_parameters *exposure_params; /*!< Mandatory. Analog gain and exposure time. */ + ia_aiq_color_channels *color_gains; /*!< Optional. RGB gains for each color channels. These gain will be applied on top of RGB gains calculated from WB results. */ +} ia_aiq_pa_input_params; + +/*! + * \brief Parameter adaptor calculations for the next frame. + * Compute generic parameters (Color Correction Matrix and Black Level Correction), + * which should be used to correct the next frame. Calculations are based on previously calculated AIQ algorithm results. + * These generic results are converted to ISP specific parameters by ia_isp component. + * + * \param[in] ia_aiq Mandatory.\n + * AIQ instance handle. + * \param[in] pa_input_params Mandatory.\n + * Input parameters for PA calculations. + * \param[out] pa_results Mandatory.\n + * Pointer's pointer where address of parameter adaptor results are stored. + + * \return Error code. + */ +LIBEXPORT ia_err +ia_aiq_pa_run(ia_aiq *ia_aiq, + const ia_aiq_pa_input_params *pa_input_params, + ia_aiq_pa_results **pa_results); + +/*! + * \brief Input parameter structure for Shading Adaptor. + */ +typedef struct +{ + ia_aiq_frame_use frame_use; /*!< Mandatory. Target frame type of the AIC calculations (Preview, Still, video etc.). */ + ia_aiq_frame_params *sensor_frame_params; /*!< Mandatory. Sensor frame parameters. Describe frame scaling/cropping done in sensor. */ + ia_aiq_awb_results *awb_results; /*!< Mandatory. WB results which are to be used to calculate next ISP parameters (WB gains, color matrix,etc). */ +} ia_aiq_sa_input_params; + +/*! + * \brief Shading Adaptor calculations for the next frame. + * Compute shading correction parameters. + * which should be used to correct the next frame. Calculations are based on previously calculated AIQ algorithm results. + * These generic results are converted to ISP specific parameters by ia_isp component. + * + * \param[in] ia_aiq Mandatory.\n + * AIQ instance handle. + * \param[in] sa_input_params Mandatory.\n + * Input parameters for SA calculations. + * \param[out] sa_results Mandatory.\n + * Pointer's pointer where address of shading adaptor results are stored. + + * \return Error code. + */ +LIBEXPORT ia_err +ia_aiq_sa_run(ia_aiq *ia_aiq, + const ia_aiq_sa_input_params *sa_input_params, + ia_aiq_sa_results **sa_results); + +/*! + * \brief Input parameter structure for setting the statistics. + */ +typedef struct +{ + unsigned long long frame_id; /*!< The frame identifier which identifies to which frame the given statistics correspond. Must be positive. */ + unsigned long long frame_timestamp; /*!< Mandatory although function will not return error, if not given. + Start of frame timestamp in microseconds. This value is used in conjunction with timestamps + provided in the AIQ algorithms function calls to calculate the convergence + speed of AIQ algorithms. + AEC, AWB and AF will not converge, if not given. */ + const ia_aiq_ae_results *frame_ae_parameters; /*!< Mandatory although function will not return error, if not given. + Exposure results from AEC which were used to capture this frame. + AEC depends on this parameters. AEC will return cold start values if not given.*/ + const ia_aiq_af_results *frame_af_parameters; /*!< Mandatory although function will not return error, if not given. + Focus results from AF which were used to capture this frame. + AEC with AF assist light and flash usage in macro functionalities depend on these parameters. */ + const ia_aiq_rgbs_grid **rgbs_grids; /*!< Mandatory. Almost all AIQ algorithms require RGBS grid statistics. */ + unsigned int num_rgbs_grids; /*!< The number of RGBS grids. */ + const ia_aiq_hdr_rgbs_grid* hdr_rgbs_grid; /*!< Optional. HDR statistics grid. */ + const ia_aiq_af_grid **af_grids; /*!< Mandatory although function will not return error, if not given. + AF will return a NULL pointer, if not given. + DSD will not return all scene modes, if not given. */ + unsigned int num_af_grids; /*!< The number of AF grids. */ + const ia_aiq_histogram **external_histograms; /*!< Optional. If ISP calculates histogram, if can be given. If external histogram is not given, + AIQ internally calculates the histogram from the RGBS grid statistics and given AWB parameters. */ + unsigned int num_external_histograms; /*!< The number of external histograms. */ + const ia_aiq_pa_results *frame_pa_parameters; /*!< Optional (Mandatory if external_histogram is not given). + AWB results used in the frame from where the statistics are collected. + GBCE will give default gamma table if external histogram or AWB results are not available. */ + const ia_face_state *faces; /*!< Mandatory although function will not return error, if not given. + Face coordinates from external face detector. + DSD will not return all scene modes, if not given. + AWB will not take face information into account, if not given. */ + ia_aiq_camera_orientation camera_orientation; /*!< The orientation of the camera. Currently unused. */ + + const ia_aiq_awb_results *awb_results; /*!< Optional. Estimated AWB results from the previous run of AWB */ + const ia_aiq_sa_results *frame_sa_parameters; /*!< Optional. LSC results used in the frame for statistics collected. */ + const ia_aiq_depth_grid **depth_grids; /*!< Optional. Depth grid statistics */ + unsigned int num_depth_grids; /*!< Optional. Number of depth grid statistics */ +} ia_aiq_statistics_input_params; + +/*! + * \brief Set input statistics and information about the captured image. + * AIQ algorithms need various information about the conditions in which the frame and statistics were captured in order to + * calculate new parameters. + * + * \param[in] ia_aiq Mandatory.\n + * AIQ instance handle. + * \param[in] statistics_input_params Mandatory.\n + * Input parameters containing statistics and information about a frame. + * \return Error code. + */ +LIBEXPORT ia_err +ia_aiq_statistics_set(ia_aiq *ia_aiq, + const ia_aiq_statistics_input_params *statistics_input_params); + +/*! + * \brief Focus bracketing parameters. + */ +typedef struct +{ + unsigned char focus_positions; /*!< Number of focus positions */ + ia_aiq_af_results af_results; /*!< Autofocus results */ + ia_aiq_af_bracket_mode af_bracket_mode; /*!< Focus bracketing mode */ +} ia_aiq_af_bracket_input_params; + +/*! + * \brief Calculates the list of lens positions for focus bracketing. + * + * \param[in] ia_aiq Mandatory.\n + * AIQ instance handle. + * \param[in] af_bracket_input_params Mandatory.\n + * Autofocus bracketing parameters. + * \param[out] af_bracket_results Mandatory.\n + * Pointer's pointer where address of focus bracketing results are stored. + * \return Error code. + */ +LIBEXPORT ia_err +ia_aiq_af_bracket(ia_aiq *ia_aiq, + const ia_aiq_af_bracket_input_params *af_bracket_input_params, + ia_aiq_af_bracket_results **af_bracket_results); + +/*! + * \param[in] ia_aiq Mandatory.\n + * AIQ instance handle. + * \param[out] out_ia_aiq_data Mandatory.\n + * Contains various AIQ related information, collected during run-time and subject to + * be stored in a host file system. Host will copy this data, if ia_aiq_data->size > 0 + * and ia_aiq_data->data != NULL; AIQ is responsible to deallocate data buffer + * during ia_aiq_deinit(). + * \return Error code. + */ +LIBEXPORT ia_err +ia_aiq_get_aiqd_data(ia_aiq *ia_aiq, + ia_binary_data *out_ia_aiq_data); + + + +/*! +* \brief Data from external sensors +*/ +typedef struct +{ + ia_aiq_sensor_data *accelerometer_events; /*!< The data holds information on the acceleration of the device in mg/sec (miligravity per second). + Acceleration = Gravity + Linear Acceleration*/ + unsigned int num_accelerometer_events; /*!< Number of accelerometer events */ + ia_aiq_sensor_data *gravity_events; /*!< The data holds information on the gravitation of the device in mg/sec (miligravity per second) */ + unsigned int num_gravity_events; /*!< Number of gravity events */ + ia_aiq_sensor_data *gyroscope_events; /*!< The data holds information on the angular velocity of the device in rad/sec */ + unsigned int num_gyroscope_events; /*!< Number of gyroscope events */ + ia_aiq_ambient_light_events *ambient_light_events; /*!< The data holds information on the ambient light */ + unsigned int num_ambient_light_events; /*!< Number of ambient light events */ +} ia_aiq_sensor_events; + +/*! + * \brief Set event statistics. + * Some of the AIQ algorithms benefit from sensor information which tells about the conditions in which the device is in use + * + * \param[in] ia_aiq Mandatory.\n + * AIQ instance handle. + * \param[in] sensor_events_input Mandatory.\n + * Sensor events input holds data from libsensorhub. + * \return Error code. + */ +LIBEXPORT ia_err +ia_aiq_sensor_events_set(ia_aiq *ia_aiq, + const ia_aiq_sensor_events *sensor_events_input); + + + +/*! + * \brief Get version. + * Get version from version header. + * + * \return Version string. + */ +LIBEXPORT const char* ia_aiq_get_version(void); + + +#ifdef __cplusplus +} +#endif + +#endif /* _IA_AIQ_H_ */ |