////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Copyright (c) 2013-2023 Qualcomm Technologies, Inc.
// All Rights Reserved.
// Confidential and Proprietary - Qualcomm Technologies, Inc.
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

#ifndef __EIS2_INTERFACE_H__
#define __EIS2_INTERFACE_H__

/*------------------------------------------------------------------------
*       Include Files
* ----------------------------------------------------------------------- */

#include "is_interface.h"

#ifdef __cplusplus
extern "C" {
#endif

/*------------------------------------------------------------------------
*       API Declarations
* ----------------------------------------------------------------------- */

/**
*  @brief   This function allocates memory for EIS 2.x and initializes the algorithm.
*
*  @param [out] eis2_handle     EIS 2.x handle
*  @param [in]  init_common     Common input data to all sensors required to initialize the EIS 3.x algorithm
*  @param [in]  init_sensors    Array sensor specific input data required to initialize the EIS 3.x algorithm
*  @param [in]  num_sensors     init_sensors array size. Also number of sensors in the system, each instance
*                               requires a unique input data struct.
*
*  @return 0 in case of success, otherwise failed.
**/
EIS_VISIBILITY_PUBLIC
int32_t eis2_initialize(
    void** eis2_handle,
    const is_init_data_common* init_common,
    const is_init_data_sensor* init_sensors,
    uint32_t num_sensors);

/**
*  @brief   Calculates the total margin used by EIS 2.x algorithm.
*           if (do_virtual_upscale_in_transform == 0)
*               stabilizationMargins = Physical Margins + Virtual Margins
*               (on this case the Virtual Margins will be upscaled with FW interference, and be done either on upscaler or ICA)
*           else
*               stabilizationMargins = Physical Margins
*               (on this case the Virtual Margins will be upscaled using matrices with no FW interference)
*
*  @note This function must be called for each sensor separately
*
*  @param [in]  in                      input struct
*  @param [out] stabilizationMargins    Total margin for EIS 2.x algorithm, as supplied to the FW.
*
*  @return 0 in case of success, otherwise failed.
**/
EIS_VISIBILITY_PUBLIC
int32_t eis2_get_stabilization_margin_ex(
    const is_get_stabilization_margin* in,
    ImageDimensions* stabilizationMargins);

/**
*  @brief   Calculates the crop for total margins (Physical+Virtual) used by EIS algorithm (for digital zoom X1).
*
*  @note This function must be called for each sensor separately
*
*  @param [in]  in                          input struct
*  @param [out] stabilization_crop_ratio_x  crop of total margins done in ICA/GPU (for digital zoom X1) for x-axis
*  @param [out] stabilization_crop_ratio_y  crop of total margins done in ICA/GPU (for digital zoom X1) for y-axis
*
*  @return 0 in case of success, otherwise failed.
**/
EIS_VISIBILITY_PUBLIC
int32_t eis2_get_stabilization_crop_ratio_ex(
    const is_get_stabilization_margin* in,
    double* stabilization_crop_ratio_x,
    double* stabilization_crop_ratio_y);

/**
*  @brief   Returns requested margins and frame delay (for future looking EIS).
*           Based on video fps and resolution and setting from EIS Chromatix.
*
*  @note This function is called at margins negotiation.
*
*  @param [in]  is_chromatix_info          EIS Chromatix struct
*  @param [in]  is_output_frame_height     Video frame height
*  @param [in]  frame_fps                  Video fps
*  @param [out] requested_margin_y         Requested margins at y axis
*  @param [out] requested_margin_x         Requested margins at x axis
*  @param [out] frame_delay                If not NULL, frame delay (buffer size) for EIS3 future looking
*
*  @return 0 in case of success, otherwise failed.
**/
EIS_VISIBILITY_PUBLIC
int32_t eis2_get_requested_margins_and_frame_delay(
    const is_chromatix_info_t* is_chromatix_info,
    uint32_t  is_output_frame_height,
    uint32_t  frame_fps,
    float*    requested_margin_y,
    float*    requested_margin_x,
    uint32_t* frame_delay);

/**
*  @deprecated Use eis2_get_time_intervals() instead
*
*  @brief   Output the time interval for gyro data needed for this frame processing.
*           Should be called every frame after SOF, gyro output will use as input to eis2_process().
*
*  @param [in,out]  eis2_handle         EIS 2.x context opaque handle
*  @param [in]      frame_time_input    frame time input to pre-process
*  @param [in]      active_sensor_idx   Active sensor index
*  @param [out]     gyro_req_interval   time interval of gyro samples that should be available for processing this frame
*
*  @return 0 in case of success, otherwise failed.
**/
EIS_VISIBILITY_PUBLIC
int32_t eis2_get_gyro_time_interval(
    void* eis2_handle,
    const frame_times_t* frame_time_input,
    uint32_t active_sensor_idx,
    gyro_times_t *gyro_req_interval);

/**
* @deprecated Use eis2_get_time_intervals() instead
*
*  @brief   Output the time interval for gyro and OIS data needed for this frame processing.
*           Should be called every frame after SOF, gyro and OIS output will use as input to eis2_process().
*
*  @param [in,out]  eis2_handle         EIS 2.x handle
*  @param [in]      frame_time_input    frame time input to pre-process
*  @param [in]      active_sensor_idx   Active sensor index
*  @param [out]     gyro_req_interval   time interval of gyro samples that should be available for processing this frame
*  @param [out]     ois_req_interval    if not NULL, time interval of OIS samples that should be available for processing this frame
*
*  @return 0 in case of success, otherwise failed.
**/
EIS_VISIBILITY_PUBLIC
int32_t eis2_get_gyro_ois_time_interval(
    void* eis2_handle,
    const frame_times_t* frame_time_input,
    uint32_t active_sensor_idx,
    gyro_times_t* gyro_req_interval,
    ois_times_t* ois_req_interval);

/**
*  @brief   Output the time interval for gyro, OIS, and iFOVC data needed for this frame processing.
*           Should be called every frame after SOF. Gyro, OIS, and iFOVC output will use as input to eis2_process().
*
*  @param [in,out]  eis2_handle                 EIS 2.x handle
*  @param [in]      frame_time_input            frame time input to pre-process
*  @param [in]      active_sensor_idx           Active sensor index
*  @param [out]     required_time_intervals     Time intervals of the corresponding data samples that should be available
*                                               for processing this frame if the data samples are required.
*                                               Otherwise, the time interval will be set to [0,0]
*
*  @return 0 in case of success, otherwise failed.
**/
EIS_VISIBILITY_PUBLIC
int32_t eis2_get_time_intervals(
    void* eis2_handle,
    const frame_times_t* frame_time_input,
    uint32_t active_sensor_idx,
    is_time_intervals* required_time_intervals);

/**
*  @brief    Output the warpStruct in order to stabilize the image and correct distortion
*
*  @param [in,out]  eis2_handle     EIS 2.x handle
*  @param [in]      eis2_input      Input to EIS 2.x algorithm
*  @param [out]     is_output       Output of EIS 2.x algorithm
*
*  @warning Function can only be called if eis2_initialize() was initialized
*           with IS_TYPE_EIS_2_0 flag, otherwise function will fail
*
*  @return 0 in case of success, otherwise failed.
**/
EIS_VISIBILITY_PUBLIC
int32_t eis2_process(
    void* eis2_handle,
    const is_input_t* eis2_input,
    is_output_t* is_output);

/**
*  @brief    Output the warpStruct in order to stabilize the image and correct distortion.
*            Function will output the stabilization transform according to the latest frame that was processed by eis2_process().
*            Therefore functions must be called in sequential order: first eis2_process() second eis2_snapshot_stabilize_to_target().
*
*  @param [in,out]  eis2_handle              EIS 2.x handle
*  @param [in]      eis2_snapshot_input      Input to EIS 2.x algorithm
*  @param [out]     is_output                Output of EIS 2.x algorithm
*
*  @warning Function can only be called if eis2_initialize() was initialized
*           with IS_TYPE_EIS_2_0 flag and eis2_process() was executed successfully, otherwise function will fail
*
*  @return 0 in case of success, otherwise failed.
**/
EIS_VISIBILITY_PUBLIC
int32_t eis2_process_snapshot(
    void* eis2_handle,
    const is_input_snapshot_stabilize_t* eis2_snapshot_input,
    is_output_snapshot_stabilize_t* is_output);

/**
*  @brief    De-initializes the EIS 2.x algorithm context.
*
*  @param [in,out]  eis2_handle     EIS 2.x handle
*
**/
EIS_VISIBILITY_PUBLIC
int32_t eis2_deinitialize(void** eis2_handle);

#ifdef __cplusplus
}
#endif

#endif //__EIS2_INTERFACE_H__
