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

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @file  chiafinterface.h
/// @brief Autofocus Algorithm interface definitions
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

// NOWHINE FILE GR016: Typedefs must not be used for structs, classes, and enumerations

#ifndef CHIAFINTERFACE_H
#define CHIAFINTERFACE_H

#include "chistatsinterfacedefs.h"
#include "chiafcommon.h"

#ifdef __cplusplus
extern "C"
{
#endif // __cplusplus

// Data structures that are exposed to OEM must be packed to have the expected layout.
#pragma pack(push, CDK_PACK_SIZE)

/** @addtogroup chi_stats_af_haf
@{ */

/// @brief Types of Process input parameters for the Autofocus algorithm.
typedef enum
{
    AFInputTypeInvalid       = -1,          ///< Type is unknown or invalid.
    AFInputTypeBAFStats,                    ///< Bayer autofocus statistics. \n
                                            ///  Payload: #AFBAFStatistics
    AFInputTypeBGStats,                     ///< Bayer grid statistics. \n
                                            ///  Payload: #StatsBayerGrid
    AFInputTypeVendorTag,                   ///< List of vendor tags the algorithm depends on. \n
                                            ///  Payload: #StatsVendorTag
    AFInputTypeRequestId,                   ///< Identifier for the processed frame request.
    AFInputTypeDebugData,                   ///< Debug data information. This is optional and can be NULL. \n
                                            ///  Payload: #StatsDataPointer
    AFInputTypeStatsChiHandle,              ///< Handle of the create session. See #CHISTATSHANDLE.
    AFInputTypeCameraInfo,                  ///< Set camera information about the algorithm role (master or slave) and
                                            ///  camera ID. \n
                                            ///  Payload: #StatsCameraInfo
    AFInputTypeLastIndex,                   ///< Last valid index of the enumeration.
    AFInputTypeMax           = 0x7FFFFFFF   ///< Indicates the last item in the definition.
} AFAlgoInputType;

/// @brief Base structure of a Process input parameter for an Autofocus algorithm instance. This structure is used with
///        #AFAlgoInputList.
typedef struct
{
    VOID*           pAFInput;       ///< Pointer to the parameter payload.
    UINT32          sizeOfInput;    ///< Size of the payload data (in bytes).
    AFAlgoInputType inputType;      ///< Type of input parameter.
} AFAlgoInput;

/// @brief List of Process input parameters that are passed to #CHIAFAlgorithm::AFProcess().
typedef struct
{
    AFAlgoInput*    pAFInputs;           ///< Pointer to the array of parameters.
    SIZE_T          numberOfInputParam;  ///< Number of elements in the array.
} AFAlgoInputList;

/// @brief Types of Process output parameters for the Autofocus algorithm.
typedef enum
{
    AFOutputTypeInvalid                     = -1,                                   ///< Type is unknown or invalid.
    AFOutputTypeStatusParam,                                                        ///< Status of the AF algorithm. \n
                                                                                    ///  Payload: #AFAlgoStatusParam
    AFOutputTypeBAFFloatingWindowConfig,                                            ///< Payload: #AFBAFFloatingWindowConfig
    AFOutputTypeBAFStatsConfig              = AFOutputTypeBAFFloatingWindowConfig,  ///< Payload: #AFBAFFloatingWindowConfig
    AFOutputTypeBAFFloatingWindowROIConfig,                                         ///< Payload: #AFBAFFloatingWindowROIConfig
    AFOutputTypeROIDim,                                                             ///< Dimensions of the ROI rectangle. \n
                                                                                    ///  Payload: #AFROIDimension.
    AFOutputTypePDAFConfig,                                                         ///< Payload: #AFAlgoPDAFWindowConfig
    AFOutputTypeMoveLensParam,                                                      ///< Payload: #AFLensPositionInfo
    AFOutputTypeFOVCParam,                                                          ///< Payload: #AFFOVCInfo
    AFOutputTypeSoftwareStatsConfig,                                                ///< Deprecated. No longer supported.
    AFOutputTypeExposureCompensation,                                               ///< Indicates whether exposure
                                                                                    ///  compensation is enabled (1). \n
                                                                                    ///  Payload: #AFAlgoExposureCompensation.
    AFOutputTypeFocusMode,                                                          ///< Payload: #AFFocusMode
    AFOutputTypeFocusValue,                                                         ///< Type of focus value.
    AFOutputTypeDebugData,                                                          ///< Payload: #StatsDataPointer
    AFOutputTypeSpotLightDetected,                                                  ///< Payload: #AFAlgoSpotLightInfo
    AFOutputTypeVendorTag,                                                          ///< Vendor tags the algorithm is to
                                                                                    ///  publish.
    AFOutputPublishingVendorTagsInfo,                                               ///< Vendor tags published by the
                                                                                    ///  algorithm. \n
                                                                                    ///  Payload: #StatsVendorTagList
    AFOutputTypeCropMagnificationFactor,                                            ///< Payload:
                                                                                    ///  #AFAlgoCropMagnificationFactor
    AFOutputTypeIsDepthFocus,                                                       ///< Indicates the depth focus.
    AFOutputTypeBAFFixedWindowROIConfig,                                            ///< Payload: #AFBAFFixedWindowROIConfig
    AFOutputTypeDepthSensorConfig,                                                  ///< Payload: #DepthSensorConfig
    AFOutputTypeMFDOFInfo,                                                          ///< Payload: #AFBracketingSnapshot
    AFOutputTypeCAFStatsConfig,                                                     ///< Payload: #CAFConfigParams
    AFOutputTypeIsTouchAssistNeeded,                                                ///< Indicates if touch assist is needed
    AFOutputTypeLumaAlert,                                                          ///< Payload: #AFumaAlert
    AFOutputTypeBAFFlexiWindowROIConfig,                                            ///< Payload: #AFBAFFlexiWindowROIConfig
    AFOutputTypeFLRatio,                                                            ///< Payload: Last valid foucs length ratio.
    AFOutputTypeLastIndex,                                                          ///< Last valid index of the enumeration.
    AFOutputTypeMax                         = 0x7FFFFFFF                            ///< Indicates the last item in the
                                                                                    ///  definition.
} AFAlgoOutputType;

/// @brief Base structure of a Process output parameter for an Autofocus algorithm instance. This structure is used with
///        #ASDAlgoOutputList.
typedef struct
{
    VOID*               pAFOutput;              ///< Pointer to the payload. The type of data depends on the value of
                                                ///  outputType.
    UINT32              sizeOfAFOutput;         ///< Size of the payload data (in bytes).
    UINT32              sizeOfWrittenAFOutput;  ///< Size of the payload (in bytes) that is written back.
                                                ///  If there is no output, set this parameter to 0.
    AFAlgoOutputType    outputType;             ///< Type of output payload.
} AFAlgoOutput;

/// @brief List of Process output parameters that are passed to #CHIAFAlgorithm::AFProcess().
typedef struct
{
    AFAlgoOutput*       pAFOutputs;     ///< Pointer to the array of parameters.
    UINT32              outputCount;    ///< Number of elements in the array.
} AFAlgoOutputList;

/// @brief Defines the focus distances for the sensor.
typedef struct
{
    FLOAT nearFocusDistance;     ///< Near limit of the actuator.
    FLOAT optimalFocusDistance;  ///< Default focus distance (the starting point for lens positioning).
    FLOAT farFocusDistance;      ///< Far limit of the actuator.
} AFFocusDistance;

/// @brief Types of Get parameters for the Autofocus algorithm.
typedef enum
{
    AFGetParamTypeInvalid              = -1,                                ///< Type is unknown or invalid.
    AFGetParamTypeDebugData,                                                ///< Queries the AF debug data.
                                                                            ///  Payload: #StatsDataPointer
    AFGetParamTypeSWVersion,                                                ///< Version of the AF algorithm. \n
                                                                            ///  Payload: #StatsAlgorithmVersion
    AFGetParamFocusDistances,                                               ///< Focus distances from the AF algorithm.
    AFGetParamCurrentLensPosition,                                          ///< Information about the current lens position.
    AFGetParamFocusStatus,                                                  ///< Payload: #AFStatus
    AFGetParamFocusMode,                                                    ///< Payload: #AFFocusMode
    AFGetParamBAFFloatingWindowConfig,                                      ///< Payload: #AFBAFFloatingWindowConfig
    AFGetParamBAFStatsConfig          = AFGetParamBAFFloatingWindowConfig,  ///< Payload: #AFBAFFloatingWindowConfig
    AFGetParamBAFFloatingWindowROIConfig,                                   ///< Payload: #AFBAFFloatingWindowROIConfig
    AFGetParamROIDim,                                                       ///< Dimensions of the ROI rectangle.
    AFGetParamVendorTagList,                                                ///< Vendor tags published by the algorithm. \n
                                                                            ///  Payload: #StatsVendorTagInfoList
    AFGetParamDependentVendorTags,                                          ///< Vendor tags the algorithm depends on. \n
                                                                            ///  Payload: #StatsVendorTagInfoList
    AFGetParamPDAFWindowConfig,                                             ///< Payload: #PDLibWindowConfig
    AFGetParamPassCameraInfo,                                               ///< Current camera information that is passed to
                                                                            ///  a singleton algorithm. \n
                                                                            ///  Payload: #StatsCameraInfo
    AFGetParamInfoForPeer,                                                  ///< Camera information that is required for the
                                                                            ///  peer.
    AFGetParamFOVCInfo,                                                     ///< Payload: #AFFOVCInfo
    AFGetParamBAFFixedWindowROIConfig,                                      ///< Payload: #AFBAFFixedWindowROIConfig
    AFGetParamSlavePDAssistInfo,                                            ///< Specifies whether PD AF search assist is
                                                                            ///  enabled or not for slave from tuning.
    AFGetParamDefaultDepthTOFConfig,                                        ///< Payload: #DepthSensorConfig
    AFGetParamCAFStatsConfig,                                               ///< Payload: #CAFConfigParams
    AFGetParamBAFFlexiWindowROIConfig,                                      ///< Payload: #AFBAFFlexiWindowROIConfig
    AFGetParamLastIndex,                                                    ///< Last valid index of the enumeration.
    AFGetParamTypeMax             = 0x7FFFFFFF                              ///< Indicates the last item in the definition.
} AFAlgoGetParamType;

/// @brief Base structure of a Get output parameter for an Autofocus algorithm instance. This structure is used with
///        #AFAlgoGetParamInputList.
typedef struct
{
    VOID*               pInputData;         ///< Pointer to the parameter payload, which contains input metadata and
                                            ///  supporting information required for generating the output.
    UINT32              sizeOfInputData;    ///< Size of the payload data (in bytes).
    AFAlgoGetParamType  type;               ///< Type of parameter, which depends on the type of query.
} AFAlgoGetParamInput;

/// @brief List of Get input parameters for a query from an Autofocus algorithm instance.
///        This list is passed to #AFAlgoGetParam.
typedef struct
{
    AFAlgoGetParamInput*    pGetParamInputs;    ///< Pointer to the array of input parameters.
    UINT32                  getParamInputCount; ///< Number of elements in the array.
} AFAlgoGetParamInputList;


/// @brief Base structure of a Get output parameter for an Autofocus algorithm instance. This structure is used with
///        #AFAlgoGetParamOutputList.
typedef struct
{
    VOID*                       pGetParamOutput;                ///< Pointer to the payload that is the result of the query.
                                                                ///  The type of data depends on the value of
                                                                ///  getParamOutputType.
    UINT32                      sizeOfGetParamOutput;           ///< Size of the payload data (in bytes).
    UINT32                      sizeOfWrittenGetParamOutput;    ///< Size of the payload (in bytes) that is written back.
                                                                ///  If there is no output, set this parameter to 0.
    AFAlgoGetParamType          getParamOutputType;             ///< Type of output payload.
} AFAlgoGetParamOutput;

/// @brief List of Get output parameters for a query from an Autofocus algorithm instance.
///        This list is passed to #AFAlgoGetParam.
typedef struct
{
    AFAlgoGetParamOutput*   pGetParamOutputs;       ///< Pointer to the array of output parameters.
    UINT32                  getParamOutputCount;    ///< Number of elements in the array.
} AFAlgoGetParamOutputList;

/// @brief List of Get parameters that are passed to #CHIAFAlgorithm::AFGetParam().
typedef struct
{
    AFAlgoGetParamInputList     inputInfo;    ///< Input data that is necessary to support the query.
    AFAlgoGetParamOutputList    outputInfo;   ///< Output metadata that is returned as a result of the query.
} AFAlgoGetParam;

/// @brief Types of Set parameters for the Autofocus algorithm.
typedef enum
{
    AFSetParamTypeInvalid                   = -1,           ///< Type is unknown or invalid.
    AFSetParamTypeHardwareCapabilities,                     ///< Payload: #AFHWCapability
    AFSetParamTypeTuningData,                               ///< Payload: #StatsTuningData
    AFSetParamTypeISPStreamInfo,                            ///< Deprecated. No longer supported.
    AFSetParamTypeSensorInfo,                               ///< Payload: #AFSensorInfo
    AFSetParamTypeAECInfo,                                  ///< Output payload: #AFAECInfo
    AFSetParamTypeROI,                                      ///< ROI information for the Touch/Face focus mode. \n
                                                            ///  Payload: #AFROIInfo
    AFSetParamTypeGravityData,                              ///< Payload: #AFGravityData
    AFSetParamTypeGyroData,                                 ///< Payload: #AFGyroData
    AFSetParamTypeLinearAccelerometerData,                  ///< Payload: #AFLinearAccelerationData
    AFSetParamTypePDAFData,                                 ///< Payload: #AFPDAFData
    AFSetParamTypeTOFData,                                  ///< Laser data input to the AF algorithm. \n
                                                            ///  Payload: #StatsSinglePointTOFInfo
    AFSetParamTypeDebugData,                                ///< Payload: #StatsDataPointer
    AFSetParamTypeMeteringMode,                             ///< Payload: #AFMeteringType
    AFSetParamTypeFocusMode,                                ///< Payload: #AFFocusMode
    AFSetParamTypeFocusControlCommand,                      ///< Indicates the focus command from the upper layer. \n
                                                            ///  Payload: #AFControlCommand
    AFSetParamTypeRunMode,                                  ///< Payload: #AFRunMode
    AFSetParamTypeManualLensMoveInfo,                       ///< Payload: #AFFocusDistanceInfo
    AFSetParamTypeSoftwareStatistics,                       ///< Preview assisted autofocus statistics. \n
                                                            ///  Payload: #AFSoftwareStatistics
    AFSetParamTypeBGStats,                                  ///< Payload: #AFSetParamTypeBGStats
    AFSetParamTypeStabilizedFaceROI,                        ///< Payload: #StatsROIInformation
    AFSetParamTypeCameraInfo,                               ///< Payload: #StatsCameraInfo
    AFSetParamTypeSettings,                                 ///< Payload: #AFAlgoSettingInfo
    AFSetParamPeerInfo,                                     ///< Information about the peer camera.
    AFSetParamCropWindow,                                   ///< Payload: #StatsRectangle.
    AFSetParamTypeUnstabilizedFaceROI,                      ///< Uniform Face ROIs in 3A. \n
                                                            ///  Payload: #StatsROIInformation
    AFSetParamTypeTrackROI,                                 ///< Track ROIs in 3A. \n
                                                            ///  Payload: #StatsROIInformation
    AFSetParamTypeDepth16Data,                              ///< Depth16 data input for the AF algorithm. \n
                                                            ///  Payload: #StatsDepth16Info
    AFSetParamTypeBPSCamera,                                ///< Indicates whether the BPS real-time use case is selected (1).
    AFSetParamTypeSensorTemperature,                        ///< Payload: #SensorTemperatureInfo
    AFSetParamTypeSaliencyInfo,                             ///< Payload: #SaliencyMapData
    AFSetParamTypeTimer,                                    ///< Payload: #AFTimerData
    AFSetParamTypeASDInfo,                                  ///< Payload: ASD output
                                                            ///  Payload: ASD information
    AFSetParamTypeCustomPDInfo,                             ///< Sets custom PD information to the algorithm.
                                                            ///  Payload: VOID pointer
    AFSetParamTypeCATMapData,                               ///< Payload: #CHIIMAGELIST
    AFSetParamLastIndex,                                    ///< Last valid index of the enumeration.
    AFSetParamTypeMax                       = 0x7FFFFFFF    ///< Indicates the last item in the definition.
} AFAlgoSetParamType;

/// @brief Base structure of a Set parameter for an Autofocus algorithm instance. This structure is used with
///        #AFAlgoSetParamList.
typedef struct
{
    VOID*                 pAFSetParam;      ///< Pointer to the parameter payload.
    SIZE_T                sizeOfSetParam;   ///< Size of parameter data.
    AFAlgoSetParamType    setParamType;     ///< Type of parameter that is passed to the algorithm.
} AFAlgoSetParam;

/// @brief List of Set parameters that are passed to #CHIAFAlgorithm::AFSetParam().
typedef struct
{
    AFAlgoSetParam*     pAFSetParams;       ///< Pointer to the array of parameters.
    SIZE_T              numberOfSetParam;   ///< Number of elements in the array.
                                            ///  @newpagetable
} AFAlgoSetParamList;

/// @brief Autofocus features supported by the algorithm.
typedef enum
{
    AFAlgoFeatureNoFeature  = 0,
    AFAlgoFeatureMax        = 0x7FFFFFFF
} AFAlgoFeatureType;


/// @brief Function wrapper for the Autofocus algorithm.
typedef struct /** @cond */ CHIAFAlgorithm /** @endcond */
{
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// @cond AFProcess @endcond
    ///
    /// @brief Runs the statistics algorithm on the given inputs and the input parameter set by AFSetParam().
    ///
    /// @datatypes
    /// #AFAlgoInputList \n
    /// #AFAlgoOutputList
    ///
    /// @param[in] pAFAlgo  Pointer to the Autofocus algorithm instance.
    /// @param[in] pInput   Pointer to the statistics inputs interface. These inputs change per process.
    /// @param[in] pOutput  Pointer to the statistics data that the algorithm outputs.
    ///
    /// @return #CDKResultSuccess or an error code (see Section @xref{hdr:resultMessages}). @newpage
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    CDKResult (*AFProcess)(
        CHIAFAlgorithm*        pAFAlgo,
        const AFAlgoInputList* pInput,
        AFAlgoOutputList*      pOutput);

    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// @cond AFGetParam @endcond
    ///
    /// @brief Retrieves the most up to date Autofocus algorithm information. Typically, the output is updated after calling
    /// AFProcess().
    ///
    /// @datatypes
    /// #AFAlgoGetParam
    ///
    /// @param[in]  pAFAlgo    Pointer to the Autofocus algorithm instance.
    /// @param[out] pGetParam  Pointer to the metadata and associated data that is necessary to support the query.
    ///
    /// @return #CDKResultSuccess or an error code (see Section @xref{hdr:resultMessages}).
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    CDKResult (*AFGetParam)(
        CHIAFAlgorithm*       pAFAlgo,
        AFAlgoGetParam*       pGetParam);

    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// @cond AFSetParam @endcond
    ///
    /// @brief Sets configuration parameters to the Autofocus algorithm.
    ///
    /// @datatypes
    /// #AFAlgoSetParamList
    ///
    /// @param[in] pAFAlgo     Pointer to the Autofocus algorithm instance.
    /// @param[in] pSetParams  Pointer to the input parameter list. Each element in the list is of type #AFAlgoSetParamType.
    ///
    /// @return #CDKResultSuccess or an error code (see Section @xref{hdr:resultMessages}). @newpage
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    CDKResult (*AFSetParam)(
        CHIAFAlgorithm*             pAFAlgo,
        const AFAlgoSetParamList*   pSetParams);

    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// @cond AFGetFeatureCapability @endcond
    ///
    /// @brief Gets the features supported by the algorithm.
    ///
    /// @param[in] pAFAlgo    Pointer to the Autofocus algorithm instance.
    /// @param[in] pFeatures  Pointer to the bitmask of supported feature types (#AFAlgoFeatureType) returned from the
    ///                       Autofocus algorithm.
    ///
    /// @return #CDKResultSuccess or an error code (see Section @xref{hdr:resultMessages}).
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    CDKResult (*AFGetFeatureCapability)(
        CHIAFAlgorithm*   pAFAlgo,
        UINT64*           pFeatures);

    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// @cond AFDestroy @endcond
    ///
    /// @brief Destroys a derived instance of the Autofocus algorithm interface.
    ///
    /// @datatypes
    /// #AFAlgoDestroyParamList
    ///
    /// @param[in] pAFAlgo         Pointer to the algorithm instance.
    /// @param[in] pDestroyParams  Pointer to the list of parameters.
    ///
    /// @return None. @newpage
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    VOID (*AFDestroy)(
        CHIAFAlgorithm*               pAFAlgo,
        const AFAlgoDestroyParamList* pDestroyParams);

} CHIAFAlgorithm; // CHIAFAlgorithm interface

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @cond CREATEAF @endcond
///
/// @brief Creates an instance of the Autofocus algorithm.
///
/// @datatypes
/// #AFAlgoCreateParamList \n
/// #CHIAFAlgorithm
///
/// @param[in] pCreateParams  Pointer to the Create parameters.
/// @param[in] ppAfAlgorithm  Double pointer to the created algorithm instance.
///
/// @return #CDKResultSuccess or an error code (see Section @xref{hdr:resultMessages}).
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
typedef CDKResult (*CREATEAF)(
    const AFAlgoCreateParamList*   pCreateParams,
    CHIAFAlgorithm**               ppAfAlgorithm);

/** @} */ /* end_addtogroup chi_stats_af_haf */

#pragma pack(pop)

#ifdef __cplusplus
}
#endif // __cplusplus
#endif // CHIAFINTERFACE_H
