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

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @file  camxmlawbinterface.h
/// @brief Machine Learning(ML) based  Auto White Balance(AWB) algorithm interface
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
#ifndef CAMXMLAWBINTERFACE_H
#define CAMXMLAWBINTERFACE_H

#include "chistatsinterfacedefs.h"
#include "camxformats.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 MLAWBImageBufferDimensions Represents the dimension info for the input buffers
struct MLAWBImageBufferDimensions
{
    StatsDimension          imgBufDim;          ///< Img buffer dimension
    UINT32                  planeStride;        ///< Img buffer planeStride
    UINT32                  sliceHeight;        ///< Img buffer plane slice height
};

/// @brief  Represents the plane address and plane size
struct ImageBufferPlaneInfo
{
    BYTE*                            pPlaneAddress;    ///< Address
    MLAWBImageBufferDimensions       bufferDimensions; ///< Buffer Dimensions
    SIZE_T                           planeSize;        ///< Plane Size
};
/// @brief  Represents the plane address and plane size and Image buffer's format and dimensions
struct MLAWBImageBufferInfo
{
    ChiBufferFormat                  imageBufferFormat;                   ///< Img Buffer format
    UINT                             numOfPlanes;                         ///< Number of planes
    ImageBufferPlaneInfo             planeInfo[CamX::FormatsMaxPlanes];   ///< Plane info
};

/// @brief Exposure information that is input to the ML AWB algorithm.
typedef struct
{
    FLOAT           luxIndex;          ///< Indicates the scene brightness.
    FLOAT           compenADRCGain;    ///< Gain compensation when ADRC is enabled.
    AWBGainParams   AWBGains;          ///< Per-channel gains (red, green, blue).
    UINT32          colorTemperature;  ///< CCT from AWB Algo
    FLOAT           LEDInfluenceRatio; ///< sensitivity with no flash or sensitivity with preflash ratio.
} MLAWBStatsAlgoInfo;

/// @brief Types of Create parameters for the ML AWB algorithm.
typedef enum
{
    MLAWBCreateParamsTypeInvalid      = -1,       ///< Invalid type
    MLAWBCreateParamsTypeLogFunctionPointer,      ///< Logger function
                                                  ///  Payload: StatsLoggingFunction
    MLAWBCreateParamsTypeCameraInfo,              ///< Camera ID
                                                  ///  Payload: UINT32
    MLAWBCreateParamsTypeCount,                   ///< Count of MLAWBAlgoCreateParamType
} MLAWBAlgoCreateParamType;

/// @brief Base structure of a parameter used when creating an ML AWB algorithm instance.
typedef struct
{
    MLAWBAlgoCreateParamType    createParamType;        ///< Type of parameter.
    VOID*                       pCreateParam;           ///< Pointer to the parameter payload.
    UINT32                      sizeOfCreateParam;      ///< Size of the payload data (in bytes).
} MLAWBAlgoCreateParam;

/// @brief List of parameters that are passed to CREATEMLAWB().
typedef struct
{
    MLAWBAlgoCreateParam*       pCreateParamList;          ///< Pointer to the array of parameters.
    UINT32                      createParamsCount;         ///< Number of elements in the array.
} MLAWBAlgoCreateParamList;

/// @brief Types of Destroy parameters for the ML AWB algorithm.
typedef enum
{
    MLAWBDestroyParamTypeInvalid               = -1,  ///< Type Invalid
    MLAWBDestroyParamTypeCameraId,                    ///< Camera ID
                                                      ///  Payload: UINT32
    MLAWBDestroyParamTypeCount,                       ///< Count of destroy params
} MLAWBAlgoDestroyParamType;

/// @brief Base structure of a parameter used when destroying ML AWB algorithm
typedef struct
{
    MLAWBAlgoDestroyParamType   destroyParamType;       ///< Type of parameter.
    VOID*                       pDestroyParam;          ///< Pointer to the parameter payload.
    UINT32                      sizeOfDestroyParam;     ///< Size of the payload data (in bytes).
} MLAWBAlgoDestroyParam;

/// @brief List of parameters that are passed to ML AWB Destroy
typedef struct
{
    MLAWBAlgoDestroyParam*    pDestroyParamList;         ///< Pointer to the array of parameters.
    UINT32                    destroyParamCount;         ///< Number of elements in the array.
} MLAWBAlgoDestroyParamList;


/// @brief Types of Process input parameters for the ML AWB algorithm.
typedef enum
{
    MLAWBInputTypeInvalid         = -1,           ///< Invalid type.
    MLAWBInputTypeFullImageBuffer,                ///< Input Full Image buffers
                                                  ///  Payload: MLAWBImageBufferInfo
    MLAWBInputTypeDownScaleImageBuffer,           ///< Input Down Scale Image buffers
                                                  ///  Payload: MLAWBImageBufferInfo
    MLAWBInputTypeCount,                          ///< Count of input types
} MLAWBAlgoInputType;

/// @brief Base structure of a Process input parameter for an MLAWB algorithm instance.
typedef struct
{
    MLAWBAlgoInputType      inputType;            ///< Type of payload.
    VOID*                   pMLAWBInput;          ///< Pointer to the parameter payload.
    UINT32                  sizeOfMLAWBInput;     ///< Size of payload data.
} MLAWBAlgoInput;

/// @brief List of Process input parameters that are passed to MLAWBProcess().
typedef struct
{
    MLAWBAlgoInput*         pMLAWBInputs;    ///< Pointer to the array of parameters.
    UINT32                  inputCount;      ///< Number of elements in the array.
} MLAWBAlgoInputList;


/// @brief Types of Process output parameters for the ML AWB algorithm.
typedef enum
{
    MLAWBOutputTypeInvalid            = -1,           ///< Invalid type
    MLAWBOutputTypeImageBuffer,                       ///< Buffer to hold local gain adjusted image
                                                      ///  Payload: MLAWBImageBufferInfo
    MLAWBOutputTypeCount,                             ///< Count of the enum
} MLAWBAlgoOutputType;

/// @brief Base structure of a Process output parameter for an ML AWB algorithm instance.
///        This structure is used with #MLAWBAlgoOutputList.
typedef struct
{
    VOID*                   pMLAWBOutput;             ///< Pointer to the parameter payload.
                                                      ///  The type of data depends on the value of outputType.
                                                      ///  Node should be the owner of the memory
    UINT32                  sizeOfMLAWBOutput;        ///< Size of the payload data (in bytes).
    UINT32                  sizeOfWrittenMLAWBOutput; ///< Size of the payload data that is written back. If there is no
                                                      ///  output, set this value to 0.
    MLAWBAlgoOutputType     outputType;               ///< Type of parameter.
} MLAWBAlgoOutput;

/// @brief List of Process output parameters that will be processed by ML AWB Algo
typedef struct
{
    MLAWBAlgoOutput*      pMLAWBOutputs;    ///< Pointer to the array of parameters.
    UINT32                outputCount;      ///< Number of elements in the array.
} MLAWBAlgoOutputList;


/// @brief Types of Get input parameters for the ML AWB algorithm.
typedef enum
{
    MLAWBGetParamInputTypeInvalid = -1,              ///< Invalid type.
    MLAWBGetParamInputTypeCount,                     ///< Count of the enum
} MLAWBAlgoGetParamType;

/// @brief Base structure of a Get input parameter for an ML algorithm instance.
///        This structure is used with #MLAWBAlgoGetParamInputList.
typedef struct
{
    VOID*                           pGetParamInput;         ///< Pointer to the parameter payload.
    UINT32                          sizeOfGetParamInput;    ///< Size of the payload data (in bytes).
    MLAWBAlgoGetParamType           getParamInputType;      ///< Type of parameter.
} MLAWBAlgoGetParamInput;

/// @brief List of Get input parameters for an ML AWB algorithm instance. This list is passed to #MLAWBAlgoGetParam.
typedef struct
{
    MLAWBAlgoGetParamInput*       pGetParamInputs;    ///< Pointer to the array of parameters.
    UINT32                        getParamInputCount; ///< Number of elements in the array.
} MLAWBAlgoGetParamInputList;


/// @brief Base structure of a Get output parameter for an ML AWB algorithm instance.
///        This structure is used with #MLAWBAlgoGetParamOutputList.
typedef struct
{
    VOID*                           pGetParamOutput;                ///< Pointer to the parameter 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 written back. If there is no
                                                                    ///  output, set this value to 0.
    MLAWBAlgoGetParamType           getParamOutputType;             ///< Type of parameter.
} MLAWBAlgoGetParamOutput;

/// @brief List of Get output parameters for an ML AWB algorithm instance. This structure is used with #MLAWBAlgoGetParam.
typedef struct
{
    MLAWBAlgoGetParamOutput*      pGetParamOutputs;       ///< Pointer to the outputs array.
    UINT32                        getParamOutputCount;    ///< Number of elements in pGetParamOutputs.
} MLAWBAlgoGetParamOutputList;

/// @brief List of Get parameters that are passed to #MLAWBAlgorithm::MLAWBGetParam().
typedef struct
{
    MLAWBAlgoGetParamInputList    inputInfoList;  ///< Input data that is necessary to support the query.
    MLAWBAlgoGetParamOutputList   outputInfoList; ///< Output metadata that is returned as a result of the query.
} MLAWBAlgoGetParam;

/// @brief Type of a Set parameter for the ML AWB algorithm.
typedef enum
{
    MLAWBSetParamTypeInvalid          = -1,           ///< Invalid type
    MLAWBSetParamTypeTuningData,                      ///< Tuning data type to set per frame
                                                      ///  Payload type: StatsTuningData
    MLAWBSetParamTypeStatsAlgoData,                   ///< 3A Algo data input type
                                                      ///  Payload: MLAWBStatsAlgoInfo
    MLAWBSetParamTypeCount,                           ///< Count of the enum
} MLAWBAlgoSetParamType;

/// @brief Base structure of a Set parameter for an ML AWB algorithm instance.
///        This structure is used with #MLAWBAlgoSetParamList.
typedef struct
{
    const VOID*              pMLAWBSetParam;        ///< Pointer to the parameter payload.
    UINT32                   sizeOfSetParam;        ///< Size of the payload data (in bytes).
    MLAWBAlgoSetParamType    setParamType;          ///< Type of parameter.
} MLAWBAlgoSetParam;

/// @brief List of Set parameters that are passed to #MLAWBAlgorithm::MLAWBSetParam().
typedef struct
{
    MLAWBAlgoSetParam*          pMLAWBSetParams;    ///< Pointer to the array of parameters.
    UINT32                      setParamsCount;     ///< Number of elements in the array.
} MLAWBAlgoSetParamList;


////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @brief Function wrapper for the ML AWB algorithm.
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
typedef struct  /** @cond */ MLAWBAlgorithm /** @endcond */
{
    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// @cond MLAWBProcess @endcond
    ///
    /// @brief  Runs the ML AWB algorithm on the given inputs.
    ///
    /// @param[in] pMLAWBAlgorithm       Pointer to the algorithm instance.
    /// @param[in] pInputs               Pointer to the statistics inputs interface.
    /// @param[in] pOutputs              Pointer to statistics data output by the algorithm.
    ///
    /// @return #CDKResultSuccess.
    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    CDKResult (*MLAWBProcess)(
        MLAWBAlgorithm*              pMLAWBAlgorithm,
        const MLAWBAlgoInputList*    pInputs,
        MLAWBAlgoOutputList*         pOutputs);

    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// @cond MLAWBGetParam @endcond
    ///
    /// @brief  Retrieves the queried info from the algo.
    ///
    /// @param[in] pMLAWBAlgorithm    Pointer to algorithm instance.
    /// @param[in] pGetParam          Pointer to the metadata and any associated data necessary to support the query.
    ///
    /// @return #CDKResultSuccess.
    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    CDKResult(*MLAWBGetParam)(
        MLAWBAlgorithm*       pMLAWBAlgorithm,
        MLAWBAlgoGetParam*    pGetParam);

    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// @cond MLAWBSetParam @endcond
    ///
    /// @brief  Sets configuration parameters to the ML AWB  algorithm.
    ///
    /// @param[in] pMLAWBAlgorithm    Pointer to algorithm instance.
    /// @param[in] pSetParams         Pointer to the input parameter list.
    ///
    /// @return #CDKResultSuccess.
    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    CDKResult(*MLAWBSetParam)(
        MLAWBAlgorithm*                pMLAWBAlgorithm,
        const MLAWBAlgoSetParamList*   pSetParams);

    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// @cond MLAWBDestroy @endcond
    ///
    /// @brief  Destroys a derived instance of the ML AWB interface.
    ///
    /// @param[in] pMLAWBAlgorithm  Pointer to algorithm instance.
    /// @param[in] pDestroyParams   Pointer to the parameter list.
    ///
    /// @return None.
    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    VOID (*MLAWBDestroy)(
        MLAWBAlgorithm*                    pMLAWBAlgorithm,
        const MLAWBAlgoDestroyParamList*   pDestroyParams);
} MLAWBAlgorithm;

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @cond CREATEMLAWB @endcond
///
/// @brief  Creates an instance of the ML AWB algorithm.
///
/// @datatypes
/// #MLAWBAlgoCreateParamList \n
/// #MLAWBAlgorithm
///
/// @param[in] pCreateParams       Pointer to create params
/// @param[in] ppMLAWBAlgorithm    Double pointer  to the created algorithm instance.
///
/// @return #CDKResultSuccess.
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
typedef CDKResult (*CREATEMLAWB)(
    const MLAWBAlgoCreateParamList*   pCreateParams,
    MLAWBAlgorithm**                  ppMLAWBAlgorithm);
#pragma pack(pop)

#ifdef __cplusplus
}
#endif // __cplusplus

#endif // CAMXMLAWBINTERFACE_H