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

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @file  chipdlibinterface.h
/// @brief PD Library interfaces
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

// NOWHINE FILE GR016: Typedefs must not be used for structs, classes, and enumerations
// NOWHINE FILE NC009: File names must start with camx

#ifndef CHIPDLIBINTERFACE_H
#define CHIPDLIBINTERFACE_H

#include "camxcdktypes.h"
#include "chipdlibcommon.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_pdlib_datatypes
@{ */

/// @brief Contains calibration data for the PD Library.
typedef struct /** @cond */ PDLibCreateParams /** @endcond */
{
    PDLibInitParam  initParam;              ///< Parameters used for initialization, including pattern information,
                                            ///  calibration, and sensor-related information.
    StatsTuningData tuningStats;            ///< Contains all tuning parameters for each camera mode.
    BOOL            isSensorType1VPD;       ///< Whether sensor support PDAF type1 vertical PD.
} PDLibCreateParams;

/// @brief Types of PD Library configuration.
typedef enum
{
    PDConfigParamTypeInvalid            = -1,                   ///< Type is invalid or unknown.
    PDConfigParamTypePDLibInitInfo,                             ///< Initialization parameter based on the current
                                                                ///  sensor mode.
                                                                ///  Payload: #PDLibCreateParams
    PDConfigParamTypeStripingInfo,                             ///< Config pdlib with striping info. for PDAFLite
    PDConfigParamTypeMax                                        ///< Total number of parameter types.
} PDLibConfigParamType;

/// @brief Base structure of a Set parameter for a PD Library.
///        This structure is used with #PDLibConfigParams.
typedef struct
{
    VOID*                       pConfigParam;                   ///< Pointer to the configuration parameter payload.
    UINT32                      sizeOfConfigParam;              ///< Size of the payload data (in bytes).
    PDLibConfigParamType        configParamType;                ///< Type of configuration parameter.
} PDLibConfigParam;

/// @brief Configuration parameters that are passed to #CHIPDLib::PDLibConfigure().
typedef struct
{
    PDLibConfigParam*           pConfigParams;                  ///< Pointer to the array of output parameters.
    UINT32                      numberOfConfigParam;            ///< Number of elements in the array.
} PDLibConfigParams;

/// @brief Defines the early and late trigger types.
typedef enum
{
    PDTriggerTypeInvalid = -1,                                  ///< Type is unknown or invalid.
    PDTriggerEarly,                                             ///< Trigger is targeted for early processing.
    PDTriggerNormal,                                            ///< Trigger is targeted for normal processing.
    PDTriggerTypeCount                                          ///< Trigger is used for the array size.
} PDTriggerType;

/// @brief Contains input parameters for a query from the PD Library.
typedef struct
{
    PDLibParam          processParam;           ///< Process the PD Raw buffer.
    UINT                numOfWrittenPDlines;    ///< Number of PD data lines written.
    VOID*               pMemoryPool;            ///< Pointer to the memory for saving the PD output.
    UINT64              requestId;              ///< Unique ID of the current request.
    PDTriggerType       trigger;                ///< Indicates whether the trigger type is early or late.
    VOID*               pChiStatsSession;       ///< Pointer to the CHI session data statistics.
    StatisticsStartUp   startupMode;            ///< Startup mode statistics.
} PDLibInputs;

/// @brief Contains the output parameter for a query from the PD Library.
typedef struct
{
    PDLibOutputData libOutput;  ///< Defocus data of the main grids.
} PDLibOutputs;

/// @brief Types of Get parameters for a query from the PD Library.
typedef enum
{
    PDLibGetParamInvalid    = -1,           ///< Type is unknown or invalid.
    PDLibGetParamHWConfig,                  ///< Sparse or dual PD hardware.
    PDLibGetParamSWInfo,                    ///< Software information from the PD Library.
    PDLibGetParamHWInfo,                    ///< Hardware information from the PD Library.
    PDLibGetParamBufferInfo,                ///< Get the maximum buffer width and height for parsed and preprocessed buffers. \n
                                            ///  Input payload: #PDSensorInfoArray \n
                                            ///  Output payload: #PDHwBufferInfo
    PDLibGetParamCustomInfo,                ///< Custom information from the PD Library. \n
                                            ///  Payload: VOID pointer
    PDLibGetParamHWOverride,                ///< Client override request for PDHW config. Input: cameraId Output: PDHwOverride.
    PDLibGetParamSensorOverride,            ///< Client override request for sensor config.
                                            ///  Input: cameraId Output: sensorOverrideConfig
    PDLibGetParamMax        = 0x7FFFFFFF,   ///< Indicates the last item.
} PDLibGetParamType;

/// @brief Contains the output data for a query from the PD Library.
typedef union
{
    PDHwConfig              config;             ///< Configuration information for the sparse or dual PD hardware.
    PDSwInfo                pdSwInfo;           ///< Contains software PD information.
    PDHwInfo                pdHwInfo;           ///< Contains hardware PD information.
    PDHwBufferInfo          pdHwBufferInfo;     ///< Contains hardware buffer information.
    VOID*                   pdCustomInfo;       ///< Contains custom PD information.
    PDHwOverride            overrideSettings;   ///< Client override request for PDHW configuration.
    SensorOverridePDConfig  sensorOverride;     ///< Client override request for sensor configuration.
} PDLibGetParamOutputData;

/// @brief Contains the required input data for PDLibGetParamHWInfo query from the PD Library.
typedef struct
{
    StatsTuningData     tuningStats;            ///< Required tuning statistics.
    BOOL                isSensorType1VPD;       ///< Whether sensor support PDAF type1 vertical PD.
} PDLibGetParamInputPDHWInfo;

/// @brief Contains the required input data for a query from the PD Library.
typedef struct
{
    UINT32                      cameraId;           ///< cameraId is required parameters for PDLib GetParam
                                                    ///  Needs to be filled correctly.
    union
    {
        PDLibCreateParams           initParam;          ///< Required parameters for PD Library initialization.
        PDLibGetParamInputPDHWInfo  PDHWInfoInput;      ///< required input for PDLibGetParamHWInfo
        PDSensorInfoArray           sensorInfoArray;    ///< Required information by PDLib to calculate maximum buffer size
                                                        ///  for parsed and preprocessed buffer
    };
} PDLibGetParamInputData;

/// @brief Contains query information to get from the PD Library. This information is passed to #CHIPDLib::PDLibGetParam().
typedef struct
{
    PDLibGetParamType       type;       ///< Type of parameter to get from the library.
    PDLibGetParamOutputData outputData; ///< List of output data for the query.
    PDLibGetParamInputData  inputData;  ///< List of input data for the query.
                                        ///  @newpagetable
} PDLibGetParams;


/// @brief This Strucutres encapsulate IFE striping cuts
typedef struct
{
    UINT32              leftStart;      ///< Left TFE start offset
    UINT32              leftEnd;        ///< Left TFE end offset
    UINT32              rightStart;     ///< Right TFE start offset
    UINT32              rightEnd;       ///< Right TFE end offset
    UINT32              ifeMode;        ///< 0 - SingleIFE : 1 - DualIFE
} PDLibIFEStripingInfo;
/** @} *//* end_addtogroup chi_pdlib_datatypes */

/** @addtogroup chi_pdlib_functions
@{ */

/// @brief Function wrapper for the PD Library.
typedef struct /** @cond */CHIPDLib/** @endcond */
{
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// @cond PDLibInitialize @endcond
    ///
    /// @brief Initializes the PD Library.
    ///
    /// @datatypes
    /// #PDLibCreateParams
    ///
    /// @param[in] pPDLib        Pointer to the created library instance.
    /// @param[in] pCreateParam  Pointer to the list of parameters.
    ///
    /// @return #CDKResultSuccess or an error code (see Section @xref{hdr:resultMessages}). @newpage
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    CDKResult(*PDLibInitialize)(
        CHIPDLib*                   pPDLib,
        const PDLibCreateParams*    pCreateParam);

    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// @cond PDLibDestroy @endcond
    ///
    /// @brief  Destroys a derived instance of the interface.
    ///
    /// @datatypes
    /// #PDLibDestroyParamList
    ///
    /// @param[in] pPDLib          Pointer to the library instance.
    /// @param[in] pDestroyParams  Pointer to the list of parameters.
    ///
    /// @return None
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    VOID(*PDLibDestroy)(
        CHIPDLib*                       pPDLib,
        const PDLibDestroyParamList*    pDestroyParams);

    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// @cond PDLibConfigure @endcond
    ///
    /// @brief  Sets configuration parameters to the PD Library.
    ///
    /// @datatypes
    /// #PDLibConfigParams
    ///
    /// @param[in] pPDLib   Pointer to the library instance.
    /// @param[in] pConfig  Pointer to the configuration parameters to set to the library.
    ///
    /// @return #CDKResultSuccess or an error code (see Section @xref{hdr:resultMessages}). @newpage
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    CDKResult(*PDLibConfigure)(
        CHIPDLib*                   pPDLib,
        const PDLibConfigParams*    pConfig);

    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// @cond PDLibGetParam @endcond
    ///
    /// @brief  Retrieves the most up-to-date PD Library data. Typically, the output is updated after calling PDLibProcess() or
    ///         PDLibInitialize().
    ///
    /// @datatypes
    /// #PDLibGetParams
    ///
    /// @param[in]  pPDLib     Pointer to the library 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(*PDLibGetParam)(
        CHIPDLib*       pPDLib,
        PDLibGetParams*  pGetParam);

    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// @cond PDLibProcess @endcond
    ///
    /// @brief  Runs the PD Library on the specified inputs. This method must only be called after the library is initialized.
    ///
    /// @datatypes
    /// #PDLibInputs \n
    /// #PDLibOutputs
    ///
    /// @param[in] pPDLib   Pointer to the library instance.
    /// @param[in] pInput   Pointer to the statistics inputs interface.
    /// @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(*PDLibProcess)(
        CHIPDLib*           pPDLib,
        const PDLibInputs*  pInput,
        PDLibOutputs*       pOutput);

} CHIPDLib; // CHIPDLib interface

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @cond CREATEPD @endcond
///
/// @brief  Creates an instance of the PD Library.
///
/// @datatypes
/// #CHIPDLib \n
/// #PDLibCreateParamList
///
/// @param[in] ppPDLib        Double pointer to the created library instance.
/// @param[in] pCreateParams  Pointer to the list of input parameters.
///
/// @return #CDKResultSuccess or an error code (see Section @xref{hdr:resultMessages}).
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
typedef CDKResult(*CREATEPD)(
    CHIPDLib**                  ppPDLib,
    const PDLibCreateParamList* pCreateParams);

/* @} *//* end_addtogroup chi_pdlib_functions */

#pragma pack(pop)

#ifdef __cplusplus
}
#endif // __cplusplus

#endif // CHIPDLIBINTERFACE_H
