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

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @file  chiasdinterface.h
/// @brief Auto Scene Detection algorithm interfaces
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

#ifndef CHIASDINTERFACE_H
#define CHIASDINTERFACE_H

#include "chistatsdebug.h"
#include "chistatsinterfacedefs.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)

/// @brief The Backlight information output by ASD algorithm after processing the statistics
typedef struct
{
    BOOL isLandscape; ///< Landscape or not
    BOOL isPortrait;  ///< Portrait or not
    BOOL isHDR;       ///< HDR scene or not.
} ASDAlgoSceneInfo;

/// @brief Represents ASD output type
typedef enum
{
    ASDAlgoOutputInvalid       = -1,         ///< Invalid type
    ASDAlgoOutputSceneInfo     = 0,          ///< Scene info.
                                             ///  Payload: ASDAlgoSceneInfo
    ASDAlgoOutputDebugData,                  ///< Debug data used
                                             ///  Payload: StatsDataPointer
    ASDAlgoOutputVendorTag,                  ///< Vendor tag data. List of vendor tags the algorithm wants to publish.
                                             ///  Payload StatsVendorTagList
    ASDAlgoOutputCount,                      ///< Indicate the total number of algorithm output
    ASDAlgoOutputMax           = 0x7FFFFFFF  ///< Anchor to indicate the last item in the defines
} ASDAlgoOutputType;

/// @brief Represents the one single type of ASD output from the algorithm
typedef struct
{
    VOID*                   pASDOutput;                 ///< Pointer to the payload. See ASDAlgoOutputType for details
                                                        ///  Algorithm implementer needs to do a deep copy
    SIZE_T                  sizeOfASDOutput;            ///< Size of input payload pointed to by pASDOutput
    SIZE_T                  sizeOfWrittenASDOutput;     ///< Size of payload written back
    ASDAlgoOutputType       outputType;                 ///< Type of the payload
} ASDAlgoOutput;

/// @brief Represents the array of ASD output from the algorithm
typedef struct
{
    ASDAlgoOutput* pASDOutputList;    ///< Pointer to ASDAlgoOutput array.
    SIZE_T         numberOfOutput;    ///< Number of elements in pOutputData
} ASDAlgoOutputList;

/// @brief This structure defines the format of the Exposure information input/AWB input info into the ASD algorithm.
typedef struct
{
    FLOAT           luxIndex;               ///< Lux index.
    FLOAT           asdExtremeGreenRatio;   ///< The extreme color green ratio.
    FLOAT           asdExtremeBlueRatio;    ///< The extreme color blue ratio.
    INT32           awbFinaldecision;       ///< AWB Final Decision.
} ASDAlgoAECAWBInfo;

/// @brief Identifies the type of input parameter to ASD algorithm
typedef enum
{
    ASDAlgoInputInvalid        = -1,            ///< Invalid type
    ASDInputRequestID          =  0,            ///< Request ID type.
                                                ///  Payload type: UINT64
    ASDAlgoInputBayerHist,                      ///< The Bayer histogram
                                                ///  Payload type: StatsBayerHist
    ASDAlgoInputFaceInfo,                       ///< The Face data
                                                ///  Payload type: StatsFaceInformation
    ASDAlgoInputAECAWBData,                     ///< AEC/AWB data input type
                                                ///  Payload type: ASDAlgoAECAWBInfo
    ASDAlgoInputVendorTag,                      ///< Vendor tag data. List of vendor tags the algori
                                                ///< thm dependents on.
                                                ///  Payload type: StatsVendorTagList
    ASDAlgoInputStatsChiHandle,                 ///< Algo needs to use this handle when querying vendor tags
                                                ///  Payload type: CHISTATSHANDLE
    ASDAlgoInputCount,                          ///< Indicate the total number of algorithm input
    ASDAlgoInputMax            = 0x7FFFFFFF     ///< Anchor to indicate the last item in the defines
} ASDAlgoInputType;

/// @brief Represents one single ASD input to the ASD algorithm
typedef struct
{
    VOID*               pASDInput;      ///< Pointer to the payload. See ASDAlgoInputType for details.
    UINT32              sizeOfASDInput; ///< Size of payload
    ASDAlgoInputType    inputType;      ///< Type of the payload
} ASDAlgoInput;

/// @brief Represents ASD module inputs to the ASD algorithm
typedef struct
{
    ASDAlgoInput*  pASDInputList;         ///< Pointer to the payload. See ASDAlgoInput for details.
    SIZE_T         numberOfASDInput;      ///< Number of discrete input
} ASDAlgoInputList;

/// @brief Identifies the type of input parameter to AWB algorithm
typedef enum
{
    ASDAlgoSetParamInvalid         = -1,         ///< Invalid type
    ASDAlgoSetParamChromatixData,                ///< The chromatix tuning header for ASD
                                                 ///  Payload type: StatsTuningData
    ASDAlgoSetParamFrameDim,                     ///< Frame Dimension
    ASDAlgoSetParamOverrideSettings,             ///< Override Settings
    ASDSetParamLastIndex,                        ///< Last valid index of the enum
                                                 ///  Payload: None
    ASDAlgoSetParamMax             = 0x7FFFFFFF  ///< Anchor to indicate the last item in the defines
} ASDAlgoSetParamType;

/// @brief Represents an AWB discreate input parameter
typedef struct
{
    VOID*                  pASDSetParam;         ///< Pointer to ASD input param data
                                                 ///  See ASDAlgoSetParamType for details
    UINT32                 sizeOfASDSetParam;    ///< Size of data pointed to by pASDInputParam
    ASDAlgoSetParamType    setParamType;         ///< Type of the input parameter
} ASDAlgoSetParam;


/// @brief Represents an AWB input parameter passed to AWBAlgorithm::SetInput()
typedef struct
{
    ASDAlgoSetParam*   pASDSetParamList;         ///< Pointer to ASD input param data
                                                 ///  See ASDAlgoSetParamType for details
    SIZE_T             numberOfASDSetParam;      ///< Number of input param parameters
} ASDAlgoSetParamList;

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @brief Describe ASD Algorithm Get Parameter definition
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @brief Indicates the type of ASD Get/Query of parameters
typedef enum
{
    ASDAlgoGetParameterTypeInvalid = -1,        ///< Invalid type
                                                ///  Payload: NULL & set size to zero.
    ASDAlgoGetParameterTypeSceneInfo,            ///< Queries the ASD scene info for landscape and portrait.
                                                ///  Payload in: NULL. Payload out: ASDGetParamSeverity
    ASDAlgoGetParamPublishingVendorTagsInfo,    ///< The vendor tags published by the algorithm
                                                ///  Payload in: NULL
                                                ///  Payload out: ASDAlgoGetParamOutputs include following type
    ASDAlgoGetParamDependentVendorTags,         ///< The vendor tags the algorithm depends on Input
                                                ///  Payload in: NULL
                                                ///  Payload out: ASDAlgoGetParamOutputs include following type
    ASDAlgoGetParamCount,                       ///< Indicate the total number of get param to algorithm
    ASDAlgoGetParameterTypeMax     = 0x7FFFFFFF
} ASDAlgoGetParamType;

/// @brief Represents the metadata to query for, and contains any associated data necessary to support that query
typedef struct
{
    VOID*   pInputData;         ///< Pointer to input data given in the query metadata
                                ///  to generate the output.
    UINT32  sizeOfInputData;    ///< Size of input data pointed to by pInputData
} ASDAlgoGetParamInputs;

/// @brief Represents the output for the metadata to query for
typedef struct
{
    VOID*   pOutputData;        ///< Pointer to output data for which queried the metadata.
    UINT32  sizeOfOutputData;   ///< Size of output data pointed to by pOutputData.
} ASDAlgoGetParamOutputs;

/// @Represents the ASD features supported by the algorithm
typedef enum
{
    ASDAlgoFeatureBasic = 1 << 0,        ///< Basic ASD Features - with basic functionalities
    ASDAlgoFeatureMax   = 1 << 31,       ///< Anchor to indicate the last item in the defines
} ASDAlgoFeatureType;

/// @brief Represents the structure to query information from ASD algorithm
typedef struct
{
    ASDAlgoGetParamType        type;       ///< Type of the metadta query
    ASDAlgoGetParamInputs      inputs;     ///< The input used to indicate the detail information to get
    ASDAlgoGetParamOutputs     outputs;    ///< The outputs of queried information
} ASDAlgoGetParam;

/// @Represents ASD create parameters information necessary to create ASD algorithm. See CreateASD.
typedef enum
{
    ASDAlgoCreateParamsInvalid              = -1,        ///< Invalid type
    ASDAlgoCreateParamsLoggerFunctionPtr,                ///< Logging function pointer
                                                         ///  Payload type: StatsLoggerFunction
    ASDCreateParamTypeCount,                             ///< Create Param Type Count
    ASDAlgoCreateParamsMax                  = 0x7FFFFFFF ///< Anchor to indicate the last item in the defines
} ASDAlgoCreateParamsType;

/// @brief Represents one single ASD create parameters used to create the ASD algorithm instance
typedef struct
{
    VOID*                        pCreateParam;       ///< Payload. See ASDAlgoCreateParamType for details
    UINT32                       sizeOfCreateParam;  ///< Size of payload pointed by data.
    ASDAlgoCreateParamsType createParamType;         ///< Create parameter type.
} ASDAlgoCreateParam;

/// @brief Represents ASD create parameter list used to create the ASD algorithm instance
typedef struct
{
    ASDAlgoCreateParam*     pCreateParamList;        ///< Payload. See ASDAlgoCreateParamType for details
    SIZE_T                  numberOfCreateParam;     ///< Number of create parameters.
} ASDAlgoCreateParamList;

/// @brief Defines any manual override settings be set to the algorithm
typedef struct
{
    // All the override flags will be added here
    // These setting will be used to override tuning settings
    UINT32 profile3A;                    ///< 3A Profiling value
} ASDAlgoOverrideSettingParam;


/// @brief Identifies the type of destroy parameter for ASD
enum ASDAlgoDestroyParamType
{
    ASDDestroyParamTypeInvalid               = -1,           ///< Type Invalid
    ASDDestroyParamTypeCameraCloseIndicator,                 ///< Camera Close Indicator
                                                             ///< UINT 0 - Camera Close 1 Camera Open
    ASDDestroyParamTypeCameraID,                             ///< Camera Info
                                                             ///  Payload: UINT32
    ASDDestroyParamTypeCount,                                ///< Destroy Param Type Count
    ASDDestroyParamTypeMax                   = 0x7FFFFFFF    ///< Max Destroy Param Type
};

/// @brief Represents an ASD destroy parameter
struct ASDAlgoDestroyParam
{
    ASDAlgoDestroyParamType  destroyParamType;       ///< Type of parameter passed
    VOID*                    pParam;                 ///< Payload of the particular parameter type
    UINT32                   sizeOfParam;            ///< Size of the payload.
};

/// @brief Represents ASD algorithm destroy parameters
struct ASDAlgoDestroyParamList
{
    ASDAlgoDestroyParam* pParamList;     ///< Pointer to ASD create-parameter
    UINT32               paramCount;     ///< Number of input destroy-parameters
};

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @brief Interface for ASD algorithm.
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
typedef struct CHIASDAlgorithm
{
    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// ASDProcess
    ///
    /// @brief  Runs the statistic algorithm on the given inputs. This method must only be called after the algorithm is
    ///         initialized.
    ///
    /// @param  pCHIASDAlgorithm   Pointer to CHIASDAlgorithm instance
    /// @param  pInput             Pointer to stats inputs interface
    /// @param  pOutput            Pointer to the stats data output by the algorithm
    ///
    /// @return CDKResultSuccess upon success.
    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    CDKResult (*ASDProcess)(
        CHIASDAlgorithm*            pCHIASDAlgorithm,
        const ASDAlgoInputList*     pInputs,
        ASDAlgoOutputList*          pOutputs);

    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// ASDGetParam
    ///
    /// @brief  This method retrieves the most up-to-date ASD algorithm metadata. The output
    ///         is generally updated after calling CHIASDAlgorithm::ASDProcess()
    ///
    /// @param  pCHIASDAlgorithm   Pointer to CHIASDAlgorithm instance
    /// @param  pGetParam          Describes the metadata to query for, and contains any associated data necessary to support
    ///                            that query
    ///
    /// @return CDKResultSuccess upon success.
    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    CDKResult (*ASDGetParam)(
        CHIASDAlgorithm*   pCHIASDAlgorithm,
        ASDAlgoGetParam*   pGetParam);

    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// ASDSetParam
    ///
    /// @brief  Sets configuration parameters to ASD.
    ///
    /// @param  pCHIASDAlgorithm  Pointer to CHIASDAlgorithm instance
    /// @param  pSetParams        Stats configuration parameters to set.Each element of the list is of type AECAlgorithmInputParams
    ///
    /// @return CDKResultSuccess upon success.
    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    CDKResult (*ASDSetParam)(
        CHIASDAlgorithm*              pCHIASDAlgorithm,
        const ASDAlgoSetParamList*    pSetParams);

    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// ASDGetFeatureCapability
    ///
    /// @brief  Get ASD Feature Capability.
    ///
    /// @param  pCHIASDAlgorithm   Pointer to CHIASDAlgorithm instance
    /// @param  pFeatures          Pointer to ASD Features.
    ///
    /// @return CDKResultSuccess upon success.
    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    CDKResult (*ASDGetFeatureCapability)(
        CHIASDAlgorithm*   pCHIASDAlgorithm,
        UINT64*            pFeatures);

    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// ASDDestroy
    ///
    /// @brief  This method destroys the derived instance of the interface
    ///
    /// @param  pCHIASDAlgorithm   Pointer to ASD Algorithm instance
    /// @param  pDestroyParams     Pointer to Destroy ASD parameters
    ///
    /// @return None
    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    VOID(*ASDDestroy)(
        CHIASDAlgorithm*               pCHIASDAlgorithm,
        const ASDAlgoDestroyParamList* pDestroyParams);

} CHIASDAlgorithm; // CHIASDAlgorithm interface

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// CreateASD
///
/// @brief  This function pointer to method creates an instance to the CHIASDAlgorithm.
///
/// @param  pCreateParams       Pointer to create params
/// @param  ppCHIASDAlgorithm   Pointer to the created CHIASDAlgorithm instance
///
/// @return CDKResultSuccess upon success.
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
typedef CDKResult (*CREATEASD)(
    const ASDAlgoCreateParamList*    pCreateParams,
    CHIASDAlgorithm**                ppCHIASDAlgorithm);

#pragma pack(pop)

#ifdef __cplusplus
}
#endif // __cplusplus

#endif // CHIASDINTERFACE_H
