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

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @file  chihistalgointerface.h
/// @brief Local Hist Algorithm interfaces
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

#ifndef CHIHISTALGOINTERFACE_H
#define CHIHISTALGOINTERFACE_H

#include "chistatsinterfacedefs.h"
#include "chistatsdebug.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_hist
@{ */

/// @brief Types of Process output parameters for the Histogram algorithm.
typedef enum
{
    HistAlgoProcessOutputTypeInvalid = -1,           ///< Type is unknown or invalid.
    HistAlgoProcessOutputTypeLTCRatio,               ///< Output is a still photo. This value is a converted unit of the Local
                                                     ///  Tone Contrast (LTC) ratio (percentage to register the unit).
    HistAlgoProcessOutputTypeLTCRatioPercentage,     ///< Output is a still photo.
    HistAlgoProcessOutputTypeLastIndex,              ///< Last valid index of the enumeration.
    HistAlgoProcessOutputTypeMax = 0x7FFFFFFF,       ///< Indicates the last item in the definition.

} HistAlgoProcessOutputType;

/// @brief Base structure of a Process output parameter for an instance of the Histogram algorithm. This structure is used with
///        #HistAlgoProcessOutputList.
typedef struct
{
    VOID*                           pHistAlgoProcessOutput;  ///< Pointer to the payload that is the result of the query.
                                                             ///  The type of data depends on the value of outputType.
    UINT32                          sizeOfOutput;            ///< Size of the payload data (in bytes).
    UINT32                          sizeOfWrittenOutput;     ///< Size of the payload (in bytes) that is written back.
                                                             ///  If there is no output, set this parameter to 0.
    HistAlgoProcessOutputType       outputType;              ///< Type of output payload.
} HistAlgoProcessOutput;

/// @brief List of Process output parameters passed to #ChiHistAlgoProcess::HistAlgoProcess().
typedef struct
{
    HistAlgoProcessOutput*  pHistAlgoProcessOutputList;   ///< Pointer to the array of parameters.
    UINT32                  outputCount;                  ///< Number of elements in the array.
} HistAlgoProcessOutputList;

/// @brief Types of Process input parameters for the Histogram algorithm.
typedef enum
{
    HistAlgoProcessInputTypeInvalid         = -1,           ///< Type is unknown or invalid.
    HistAlgoProcessInputTypeYPlaneImageAddress,             ///< Address of the Y plane in the image.
    HistAlgoProcessInputTypeDRCGainLTM,                     ///< Dynamic range compression gain to be applied at the Local Tone
                                                            ///  Map (LTM) module.
    HistAlgoProcessInputTypeDRCDarkGain,                    ///< Dark gain for dynamic range compensation.
    HistAlgoProcessInputTypeSensorGain,                     ///< Sensor real gain that is programmed for this frame.
    HistAlgoProcessInputTypeLastIndex,                      ///< Last valid index of the enumeration.
    HistAlgoProcessInputTypeMax             = 0x7FFFFFFF,   ///< Indicates the last item in the definition.
} HistAlgoProcessInputType;

/// @brief Base structure of a Process input parameter for an instance of the Histogram algorithm. This structure is used with
///        #HistAlgoProcessInputList.
typedef struct
{
    VOID*                           pHistAlgoProcessInput;  ///< Pointer to the parameter payload.
    UINT32                          sizeOfInputType;        ///< Size of the payload data (in bytes).
    HistAlgoProcessInputType        inputType;              ///< Type of input payload.
} HistAlgoProcessInput;

/// @brief List of Process input parameters that are passed to #ChiHistAlgoProcess::HistAlgoProcess().
typedef struct
{
    HistAlgoProcessInput*   pHistAlgoProcessInputs;    ///< Pointer to the array of parameters.
    UINT32                  inputCount;                ///< Number of elements in the array.
} HistAlgoProcessInputList;

/// @brief Types of Destroy parameters for the Histogram algorithm.
typedef enum
{
    HistAlgoProcessDestroyParamTypeInvalid               = -1,           ///< Type is unknown or invalid.
    HistAlgoProcessDestroyParamTypeCameraCloseIndicator,                 ///< Indicates whether the camera is closed (0) or
                                                                         ///  open (1).
    HistAlgoProcessDestroyParamTypeCameraInfo,                           ///< Payload: #StatsCameraInfo.
    HistAlgoProcessDestroyParamTypeCount,                                ///< Total number of parameters.
    HistAlgoProcessDestroyParamTypeMax                   = 0x7FFFFFFF    ///< Indicates the last item in the definition.
                                                                         ///  @newpage
} HistAlgoProcessDestroyParamType;

/// @brief Base structure of a Destroy parameter for an instance of the Histogram algorithm. This structure is used with
///        #HistAlgoProcessDestroyParamList.
typedef struct
{
    HistAlgoProcessDestroyParamType     destroyParamType;       ///< Type of parameter that is passed to the algorithm.
    VOID*                               pParam;                 ///< Pointer to the parameter payload.
    UINT32                              sizeOfParam;            ///< Size of the payload data (in bytes).
} HistAlgoProcessDestroyParam;


/// @brief List of Destroy parameters that are passed to #ChiHistAlgoProcess::HistAlgoDestroy().
typedef struct
{
    HistAlgoProcessDestroyParam*   pParamList;    ///< Pointer to the array of parameters.
    UINT32                         paramCount;    ///< Number of elements in the array.
} HistAlgoProcessDestroyParamList;

/// @brief Types of Create parameters for the Histogram algorithm.
typedef enum
{
    HistAlgoProcessCreateParamTypeInvalid     = -1,         ///< Type is unknown or invalid.
    HistAlgoProcessCreateParamTypeCameraInfo,               ///< Payload: #StatsCameraInfo
    HistAlgoProcessCreateParamTypeCount,                    ///< Total number of parameters.
    HistAlgoProcessCreateParamTypeMax = 0x7FFFFFFF          ///< Indicates the last item in the definition.
} HistAlgoProcessCreateParamType;

/// @brief Base structure of a Create parameter for an instance of the Histogram algorithm. This structure is used with
///        #HistAlgoProcessCreateParamList.
typedef struct
{
    HistAlgoProcessCreateParamType  createParamType;  ///< Type of parameter that is passed to the algorithm.
    VOID*                           pParam;           ///< Pointer to the parameter payload.
    UINT32                          sizeOfParam;      ///< Size of the payload data (in bytes).
} HistAlgoProcessCreateParam;

/// @brief List of Create parameters that are passed to CREATEHISTOGRAMALGOPROCESS().
typedef struct
{
    HistAlgoProcessCreateParam*    pParamList;    ///< Pointer to the array of parameters.
    UINT32                         paramCount;    ///< Number of elements in the array.
                                                  ///  @newpagetable
} HistAlgoProcessCreateParamList;


/// @brief Function wrapper for the Histogram algorithm.
typedef struct /** @cond */ ChiHistAlgoProcess /** @endcond */
{
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// @cond HistAlgoProcess @endcond
    ///
    /// @brief Runs the Histogram algorithm on the given inputs.
    ///
    /// @datatypes
    /// #HistAlgoProcessInputList \n
    /// #HistAlgoProcessOutputList
    ///
    /// @param[in] pCHIHistAlgoProcess  Pointer to the algorithm instance.
    /// @param[in] pInputs              Pointer to the statistics inputs interface.
    /// @param[in] pOutputs             Pointer to the statistics data that the algorithm outputs.
    ///
    /// @return #CDKResultSuccess or an error code (see Section @xref{hdr:resultMessages}). @newpage
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    CDKResult(*HistAlgoProcess)(
        ChiHistAlgoProcess*                pCHIHistAlgoProcess,
        const HistAlgoProcessInputList*    pInputs,
        HistAlgoProcessOutputList*         pOutputs);

    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// @cond HistAlgoDestroy @endcond
    ///
    /// @brief Destroys a derived instance of the Histogram algorithm interface.
    ///
    /// @datatypes
    /// #HistAlgoProcessDestroyParamList
    ///
    /// @param[in] pCHIHistAlgoProcess  Pointer to the algorithm instance.
    /// @param[in] pDestroyParams       Pointer to the list of parameters.
    ///
    /// @return None. @newpage
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    VOID(*HistAlgoDestroy)(
        ChiHistAlgoProcess*                      pCHIHistAlgoProcess,
        const HistAlgoProcessDestroyParamList*   pDestroyParams);

} ChiHistAlgoProcess;  // ChiHistAlgoProcess interface


///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @cond CREATEHISTOGRAMALGOPROCESS @endcond
///
/// @brief Creates an instance of the Histogram algorithm interface.
///
/// @datatypes
/// #HistAlgoProcessCreateParamList \n
/// #ChiHistAlgoProcess
///
/// @param[in] pCreateParams      Pointer to the list of parameters.
/// @param[in] ppHistAlgoProcess  Double pointer to the created algorithm instance.
///
/// @return #CDKResultSuccess or an error code (see Section @xref{hdr:resultMessages}). @newpage
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
typedef CDKResult(*CREATEHISTOGRAMALGOPROCESS)(
    const HistAlgoProcessCreateParamList*  pCreateParams,
    ChiHistAlgoProcess**                   ppHistAlgoProcess);

/** @} */ /* end_addtogroup chi_stats_hist */

#pragma pack(pop)

#ifdef __cplusplus
}
#endif // __cplusplus

#endif // CHIHISTALGOINTERFACE_H
