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

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @file  chiawbinterface.h
/// @brief Auto White Balance algorithm interfaces
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

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

#ifndef CHIAWBINTERFACE_H
#define CHIAWBINTERFACE_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_awb
@{ */

static const UINT32 AWBAlgoRotationMatrixSize       = 9;   ///< Defines the size of the geometrical disparity calibration
                                                           ///  matrix for a dual camera.
static const UINT32 AWBAlgoDecisionMapSize          = 64;  ///< Number of AWB decision maps or areas.
static const UINT32 AWBAlgoExternalInputSize        = 12;  ///< Number of AWB external input sizes.

static const UINT32 AWBAlgoCustomizedSAOutputSize   = 20;  ///< Number of AWB customized scene analyzer output sizes.

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Describe AWB Algorithm Input Data definition
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

/// @brief Valid flash states.
typedef enum
{
    AWBAlgoFlashInvalid             = -1,           ///< Flash state Invalid.
    AWBAlgoFlashInactive,                           ///< Flash is OFF or inactive.
    AWBAlgoPreFlashStart,                           ///< Estimation Starts; Preflash turns on
    AWBAlgoPreFlashTriggerFD,                       ///< Start face detection under preflash.
    AWBAlgoPreFlashTriggerAF,                       ///< Start autofocus under preflash.
    AWBAlgoPreFlashTriggerAWB,                      ///< Start automatic white balance under preflash.
    AWBAlgoPreFlashCompleteLED,                     ///< Estimation completes with LED, and preflash turns OFF. The estimation
                                                    ///  requires a flash capture.
    AWBAlgoPreFlashCompleteNoLED,                   ///< Estimation completes but no LED is required and no flash is required.
    AWBAlgoMainFlash,                               ///< Main flash capture is in progress.
    AWBAlgoTorchFlash,                              ///< No preflash sequence.
    AWBAlgoLEDMax                   = 0x7FFFFFFF    ///< Indicates the last item in the definition.
} AWBAlgoFlashState;

/// @brief Exposure information that is input to the AWB algorithm.
typedef struct
{
    FLOAT   luxIndex;                                 ///< Indicates the scene brightness.

    BOOL    AECSettled;                               ///< Indicates whether the AEC is currently settled.
                                                      ///
                                                      ///  @valuesbul
                                                      ///  - 0 -- FALSE
                                                      ///  - 1 -- TRUE @tablebulletend

    UINT64  frameDuration;                            ///< Indicates the length of the frame (in milliseconds).
    FLOAT   BETemplateMatrix[BETemplateMatrixSize];   ///< Template matching matrix based on BE stats.
} AWBAlgoExposureInformation;

/// @brief Depth information for the AWB algorithm.
typedef struct
{
    UINT*   ConfidenceMap;          ///< Mapping table between the grid index and the confidence level.
    UINT*   DistanceMap;            ///< Mapping table between the grid index and the estimated distance.
    BOOL*   AFSelectionMap;         ///< Mapping table that indicates which grid indices were considered during the focus
                                    ///  operation.
    UINT32  horiNumOfRegion;        ///< Number of horizontal grids.
    UINT32  vertNumOfRegion;        ///< Number of vertical grids.
    UINT32  widthOfRegion;          ///< Width of each grid cell.
    UINT32  heightOfRegion;         ///< Height of each grid cell.
    UINT32  horiRegionOffset;       ///< Horizontal offset for grid.
    UINT32  vertRegionOffset;       ///< Vertical offset for a grid.
    UINT32  isDepthMapAvaiable;     ///< Availability of the depth map.
}AWBAlogDepthInformation;

/// Information about focusing on a distant object.
typedef struct
{
    BOOL        isAFSettled;                           ///< Indicates whether focusing is done.
                                                       ///
                                                       ///  @valuesbul
                                                       ///  - 0 -- FALSE
                                                       ///  - 1 -- TRUE @tablebulletend

    FLOAT       focusDistance[FocusDistanceMaxIndex];  ///< Array of distances where an object appears to be in focus
                                                       ///  (in meters).
} AWBAlgoObjectDistanceInfo;

/// @brief Identifies the type of input to AWB algorithm.
typedef enum
{
    AWBInputTypeInvalid         = -1,           ///< Type is unknown or invalid.
    AWBInputTypeRequestNumber,                  ///< Unique identifier of the request.
    AWBInputTypeBGStats,                        ///< Payload: #StatsBayerGrid
    AWBInputTypeAECData,                        ///< Payload: #AWBAlgoExposureInformation
    AWBInputTypeDebugData,                      ///< Optional member; can be NULL. \n
                                                ///  Payload: #StatsDebugDataInfo
    AWBInputTypeVendorTag,                      ///< List of vendor tags the algorithm depends on. \n
                                                ///  Payload: #StatsVendorTagList
    AWBInputTypeStatsChiHandle,                 ///< Handle of the create session. See #CHISTATSHANDLE.
    AWBInputTypeCameraInfo,                     ///< Camera information about the algorithm role (master or slave) and camera
                                                ///  ID. \n
                                                ///  Payload: #StatsCameraInfo
    AWBInputTypeBGStatsROI,                     ///< Payload: #StatsRectangle
    AWBInputTypeIsOffline,                      ///< Indicates whether Bayer grid statistics are offline (1) or not (0).
    AWBInputTypeIsStatsForLongExposureFrame,    ///< Indicates whether the AWB statistics are for a long exposure frame (1)
                                                ///  or not (0).
    AWBInputTypeBFWStats,                       ///< Bayer floating window statistics. \n
                                                ///  Payload: #StatsBayerFloatingWindow
    AWBInputTypeAFData,                         ///< Payload: #AWBAlgoObjectDistanceInfo
    AWBInputTypeASDData,                        ///< Payload: #StatsMotionVectorInfo
    AWBInputTypeLastIndex,                      ///< Last valid index of the enumeration.
    AWBInputTypeMax             = 0x7FFFFFFF,   ///< Indicates the last item in the definition.
} AWBAlgoInputType;

/// @brief Base structure of a Process input parameter for an AWB algorithm instance. This structure is used with
///        #AWBAlgoInputList.
typedef struct
{
    VOID*               pAWBInput;       ///< Pointer to the parameter payload.
    UINT32              sizeOfAWBInput;  ///< Size of the payload data (in bytes).
    AWBAlgoInputType    inputType;       ///< Type of input payload.
} AWBAlgoInput;

/// @brief List of Process input parameters that are passed to #CHIAWBAlgorithm::AWBProcess().
typedef struct
{
    AWBAlgoInput*   pAWBInputs;  ///< Pointer to the array of  parameters.
    UINT32          inputCount;  ///< Number of elements in the array.
} AWBAlgoInputList;

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Describe AWB Algorithm Output Data definition
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

/// @brief AWB gains for red, green, and blue channels.
typedef struct
{
    FLOAT   red;    ///< Gains on the red channel.
    FLOAT   green;  ///< Gains on the green channel.
    FLOAT   blue;   ///< Gains on the blue channel.
} AWBAlgoGains;

/// @brief AWB algorithm data points.
typedef struct
{
    FLOAT   rg;     ///< Ratio of the red channel over the green channel.
    FLOAT   bg;     ///< Ratio of the blue channel over the green channel.
} AWBAlgoPoint;

/// @brief Valid AWB state types.
typedef enum
{
    AWBAlgoStateInvalid     = -1,           ///< State is unknown or invalid.
    AWBAlgoStateInactive,                   ///< AWB is not in Auto mode or it has not started metering.
    AWBAlgoStateSearching,                  ///< AWB does not have a good set of control values for the current scene.
    AWBAlgoStateConverged,                  ///< AWB has a good set of control values for the current scene.
    AWBAlgoStateLocked,                     ///< AWB has been locked.
    AWBAlgoStateMax         = 0x7FFFFFFF,   ///< Indicates the last item in the definition.
} AWBAlgoState;

/// @brief Types of Process output parameters for the AWB algorithm.
typedef enum
{
    AWBOutputTypeInvalid            = -1,           ///< Type is unknown or invalid.
    AWBOutputTypeDebugData,                         ///< Payload: #StatsDataPointer
    AWBOutputTypeGains,                             ///< Payload: #AWBAlgoGains
    AWBOutputTypeColorTemperature,                  ///< Color temperature in degrees Kelvin.
    AWBOutputTypeIlluminantType,                    ///< AWB illuminant source decision. \n
                                                    ///  Payload: #StatsIlluminantType
    AWBOutputTypeSampleDecision,                    ///< AWB array of sample decisions. \n
                                                    ///  Payload: #StatsIlluminantType [AWBAlgoDecisionMapSize]
    AWBOutputTypeBGConfig,                          ///< (Optional) Payload: #StatsBayerGridBayerExposureConfig
    AWBOutputTypeState,                             ///< AWB algorithm state. \n
                                                    ///  Payload: #AWBAlgoState
    AWBOutputTypeMode,                              ///< AWB algorithm mode used for processing. \n
                                                    ///  Payload: #AWBAlgoMode
    AWBOutputTypeLock,                              ///< Indicates whether the AWB algorithm is locked (1) or unlocked (0).
    AWBOutputTypeVendorTag,                         ///< List of vendor tags the AWB algorithm is to publish. \n
                                                    ///  Payload: #StatsVendorTagList
    AWBOutputTypeCCM,                               ///< AWB algorithm color correction matrix values. \n
                                                    ///  Payload: #StatsAWBCCMList
    AWBOutputTypeCurrentDecision,                   ///< Current frame AWB decision point. \n
                                                    ///  Payload: #AWBAlgoDecisionInformation
    AWBOutputTypeSkipBGStatsParse,                  ///< Indicates whether BG statistics is to skip parsing (1). (Default =
                                                    ///  0 for no skip)
    AWBOutputTypeSAConf,                            ///< Output confidences for the Scene Analyzer. \n
                                                    ///  Payload: #AWBSAConfInfo
    AWBOutputTypeAdjustedFaceROI,                   ///< Face ROI filtered by the AWB face Scene Analyzer. \n
                                                    ///  Payload: #AWBFaceSAAdjustedROI
    AWBOutputTypeLocalGainAdjust,                   ///< Gets the local gains adjusted by the AWB algorithm. \n
                                                    ///  Payload: LocalGainAdjustData
    AWBOutputTypeFaceToneInfo,                      ///< Get the face tone decision. \n
                                                    ///  Payload: AWBFaceToneInfo
    AWBOutputTypeLastIndex,                         ///< Last valid index of the enumeration.
    AWBOutputTypeMax                = 0x7FFFFFFF,   ///< Indicates the last item in the definition.
} AWBAlgoOutputType;

/// @brief Base structure of a Process output parameter for an AWB algorithm instance. This structure is used with
///        #AWBAlgoOutputList.
typedef struct
{
    VOID*               pAWBOutput;              ///< Pointer to the payload that is the result of the query. The type of data
                                                 ///  depends on the value of outputType. The algorithm implementer must do a
                                                 ///  deep copy to the specified memory.
    UINT32              sizeOfAWBOutput;         ///< Size of the payload data (in bytes).
    UINT32              sizeOfWrittenAWBOutput;  ///< Size of the payload (in bytes) that is written back.
                                                 ///  If there is no output, set this parameter to 0.
    AWBAlgoOutputType   outputType;              ///< Type of output payload.
} AWBAlgoOutput;

/// @brief List of Process output parameters that are passed to #CHIAWBAlgorithm::AWBProcess().
typedef struct
{
    AWBAlgoOutput*  pAWBOutputs;    ///< Pointer to the array of parameters.
    UINT32          outputCount;    ///< Number of elements in the array.
} AWBAlgoOutputList;

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Describe AWB Algorithm Get Parameter definition
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

/// @brief AWB flash estimation states.
typedef enum
{
    AWBAlgoFlashEstimationInvalid   = -1,            ///< Flash estimation state is invalid.
    AWBAlgoFlashEstimationInactive,                  ///< AWB is not performing any flash estimation.
    AWBAlgoFlashEstimationRunning,                   ///< Flash estimation in progress.
    AWBAlgoFlashEstimationDone,                      ///< Flash estimation is done.
    AWBAlgoFlashEstimationMax       = 0x7FFFFFFF,    ///< Indicates the last item in the definition.
} AWBAlgoFlashEstimationProgress;

/// @brief Valid AEC flash states.
typedef enum
{
    AWBAlgoFlashOff,                ///< Flash is in the Off state.
    AWBAlgoFlashPre,                ///< Flash is in Preflash state.
    AWBAlgoFlashMain,               ///< Flash in in Main flash state.
    AWBAlgoFlashMax = 0x7FFFFFFF    ///< Indicates the last item in the definition.
} AWBAlgoFlashInfoType;

/// @brief Defines flash-related information.
typedef struct
{
    AWBAlgoFlashState       flashState;         ///< Flash sequence state.
    FLOAT                   LEDInfluenceRatio;  ///< Sensitivity ratio that is calculated as sensitivity with no flash or
                                                ///  sensitivity with preflash.
    FLOAT                   LEDRGRatio;         ///< Red-green ratio when the LED flash is ON.
    FLOAT                   LEDBGRatio;         ///< Blue-green ratio when the LED flash is ON.
    AWBAlgoFlashInfoType    flashType;          ///< Indicates whether the flash type is preflash or main flash.

    BOOL                    bIsTorch;           ///< Indicates whether torch plus capture is enabled.
                                                ///
                                                ///  @valuesbul
                                                ///  - 0 -- FALSE
                                                ///  - 1 -- TRUE @tablebulletend
} AWBAlgoFlashInformation;

/// @brief Defines the AWB warm start gains and correlated color temperature (CCT).
typedef struct
{
    AWBAlgoGains        gains;                        ///< AWB algorithm gains.
    FLOAT               correlatedColorTemperature;   ///< CCT (in degrees Kelvin) provided to AWB.
    AWBDecisionPoint    curFrameDecisionAfterTC;      ///< Current frame decision after a temporal convergence.
} AWBAlgoWarmstartInformation;

/// @brief Contains the ambient rate information for the AWB algorithm.
struct AmbientRateTOFData
{
    UINT16  width;                                      ///< Width of the data.
    UINT16  height;                                     ///< Height of the data.
    UINT16  stride;                                     ///< Stride of the data.
    UINT32* pAmbientRate;                               ///< Pointer to the ambient rate of the configured grids.
};
/// @brief External information that is input to the AWB algorithm.
typedef struct
{
    FLOAT                   inputData[AWBAlgoExternalInputSize];   ///< Array of AWB external input data.
    AmbientRateTOFData*     pMultiPointTOFData;                    ///< Time of Flight sensor data from a multipoint sensor.
} AWBAlgoExternalInformation;

/// @brief Types of E-spectral sensor information.
typedef enum
{
    AWBAlgoEspectralSensorTypeInvalid   = -1,        ///< Type is unknown or invalid.
    AWBAlgoEspectralSensorSingleIR,                  ///< No flicker detection and no clear.
    AWBAlgoEspectralSensorSingleUV,                  ///< No flicker detection and no clear.
    AWBAlgoEspectralSensorDualIRMode1,               ///< IR1+IR2, but no flicker detection and no clear.
    AWBAlgoEspectralSensorDualIRMode2,               ///< IR1+IR2, but no flicker detection and with clear.
    AWBAlgoEspectralSensorDualIRMode3,               ///< IR1+IR2, but with flicker detection and clear.
    AWBAlgoEspectralSensorIRAndUVMode1,              ///< UV+IR, but no flicker detection and no clear.
    AWBAlgoEspectralSensorIRAndUVMode2,              ///< UV+IR, but no flicker detection and with clear.
    AWBAlgoEspectralSensorIRAndUVMode3,              ///< UV+IR, but with flicker detection and clear.
    AWBAlgoEspectralSensorTypeMax     = 0x7FFFFFFF,  ///< Indicates the last item in the definition.
} AWBAlgoEspectralSensorInfoType;

/// @brief E-spectral sensor information that is input to the AWB algorithm.
typedef struct
{
    BOOL                            eSensorInfoAvailable;  ///< Indicates whether sensor information input to the AWB algorithm
                                                           ///  is available.
                                                           ///
                                                           ///  @valuesbul
                                                           ///  - 0 -- FALSE
                                                           ///  - 1 -- TRUE @tablebulletend

    AWBAlgoEspectralSensorInfoType  eSpectralSensorMode;   ///< Specifies the type of E-spectral sensor mode: single IR/UV,
                                                           ///  dual IR, or IR/UV.
    FLOAT                           dataIR;                ///< IR1 (dual IR sensor, long wavelength IR) or IR (IR UV sensor)
                                                           ///  value.
    FLOAT                           dataIR2;               ///< IR2 (dual IR sensor, short wavelength IR) value.
    FLOAT                           dataUV;                ///< UV (ir_uv sensor) value.
    FLOAT                           dataR;                 ///< Red value.
    FLOAT                           dataG;                 ///< Green value.
    FLOAT                           dataB;                 ///< Blue value.
    FLOAT                           dataClear;             ///< No color filter sensor output.
    FLOAT                           flickerFrequency;      ///< Flicker frequency of the ambient light.
    FLOAT                           CCT;                   ///< Color correction temperature is derived from the red, green,
                                                           ///  and blue channel pixel data.
    FLOAT                           luxIndex;              ///< Indicates the scene brightness computed by the E-spectral
                                                           ///  sensor.
} AWBAlgoEspectralSensorInformation;

/// @brief Customized scene analyzer information that is input to the AWB algorithm.
typedef struct
{
    UINT32          customizedSACount;                              ///< Number of customized scene analyzer used.
    AWBAlgoPoint    decisionPoint[AWBAlgoCustomizedSAOutputSize];   ///< Decision points for customized scene analyzers.
    FLOAT           confidence[AWBAlgoCustomizedSAOutputSize];      ///< Confidence levels for customized scene analyzers.
    UINT32          SAID[AWBAlgoCustomizedSAOutputSize];            ///< IDs of the customized scene analyzers.
    UINT32          SASubID[AWBAlgoCustomizedSAOutputSize];         ///< Submodule IDs of the customized scene analyzers.
    FLOAT           weight[AWBAlgoCustomizedSAOutputSize];          ///< Weights for customized scene analyzerss.
} AWBAlgoCustomizedSAInformation;

#ifndef DOXYGEN_SHOULD_SKIP_THIS

// To generate enum from macros
#define AWB_GENERATE_ENUM(ENUM) ENUM,

// To generate string for enum from macros
#define AWB_GENERATE_STRING(STRING) #STRING,

#if 0
// @brief Get parameters for queries from the AWB algorithm.
typedef enum
{
    AWBGetParamTypeInvalid                      = -1,           ///< Type is unknown or invalid.
    AWBGetParamTypeDebugData,                                   ///< Queries the AWB debug data.
                                                                ///  Payload: #AWBGetParamOutputTypeDebugData
    AWBGetParamTypeLastOutput,                                  ///< Queries the last valid output.
                                                                ///  Payload: #AWBGetParamOutputTypeOutputList
    AWBGetParamTypeFlashOutput,                                 ///< Requests AWB flash output data based on the last
                                                                ///  statistics or pre-flash.
                                                                ///  Payload: #AWBGetParamOutputTypeOutputList
    AWBGetParamTypeSWVersion,                                   ///< Queries the software version
                                                                ///  Payload: #AWBGetParamOutputTypeAlgoVersion.
    AWBGetParamTypeIsStatsDataRequired,                         ///< Queries whether the AWB algorithm is required to process
                                                                ///  data at this time.
                                                                ///  This will be called before parsing incoming statistics,
                                                                ///  such as before a process is called into the algorithm.
                                                                ///  Payload: #AWBGetParamOutputTypeStatsRequired
    AWBGetParamTypeFlashEstimationState,                        ///< Queries the current flash estimation state
                                                                ///  Payload: #AWBAlgoFlashEstimationProgress.
    AWBGetParamTypePublishingVendorTagsInfo,                    ///< vendor tags published by the algorithm
                                                                ///  Payload: #StatsVendorTagInfoList
    AWBGetParamTypeDependentVendorTags,                         ///< vendor tags dependent by the algorithm
                                                                ///  Payload: #StatsVendorTagInfoList
    AWBGetParamTypePeerInfo,                                    ///< Multi-camera peer information
    AWBGetParamTypeCctToGain,                                   ///< Gets the AWB gains based on CCT value
    AWBGetParamTypeGainToCCT,                                   ///< Gets the CCT value base AWB gains
    AWBGetParamTypeBGConfig,                                    ///< Gets AWB statistics config
                                                                ///  Payload: #StatsBayerGridBayerExposureConfig
    AWBGetParamTypeFaceTone,                                    ///< Pass skin tone information to AEC
    AWBGetParamTypeLastIndex,                                   ///< Last valid index of the enumeration.
    AWBGetParamTypeMax                          = 0x7FFFFFFF,   ///< Indicates the last item in the definition.
} AWBAlgoGetParamType;
#endif // if 0

// Defines the Get parameters for AWB algorithm queries.
#define AWB_GET_ENUM_LIST(ADD_ENTRY)                     \
    ADD_ENTRY(AWBGetParamTypeInvalid)                    \
    ADD_ENTRY(AWBGetParamTypeDebugData)                  \
    ADD_ENTRY(AWBGetParamTypeLastOutput)                 \
    ADD_ENTRY(AWBGetParamTypeFlashOutput)                \
    ADD_ENTRY(AWBGetParamTypeSWVersion)                  \
    ADD_ENTRY(AWBGetParamTypeIsStatsDataRequired)        \
    ADD_ENTRY(AWBGetParamTypeFlashEstimationState)       \
    ADD_ENTRY(AWBGetParamTypePublishingVendorTagsInfo)   \
    ADD_ENTRY(AWBGetParamTypeDependentVendorTags)        \
    ADD_ENTRY(AWBGetParamTypePeerInfo)                   \
    ADD_ENTRY(AWBGetParamTypeCctToGain)                  \
    ADD_ENTRY(AWBGetParamTypeGainToCCT)                  \
    ADD_ENTRY(AWBGetParamTypeBGConfig)                   \
    ADD_ENTRY(AWBGetParamTypeFaceTone)                   \
    ADD_ENTRY(AWBGetParamTypeLastIndex)                  \
    ADD_ENTRY(AWBGetParamTypeMax)                        \

#endif /* DOXYGEN_SHOULD_SKIP_THIS */

/// @brief Types of Get parameters for the AWB algorithm.
typedef enum
{
    AWB_GET_ENUM_LIST(AWB_GENERATE_ENUM)  ///< List of query parameters. \n
                                          ///  AWBGetParamTypeInvalid \n
                                          ///  AWBGetParamTypeDebugData \n
                                          ///  AWBGetParamTypeLastOutput \n
                                          ///  AWBGetParamTypeFlashOutput \n
                                          ///  AWBGetParamTypeSWVersion \n
                                          ///  AWBGetParamTypeIsStatsDataRequired \n
                                          ///  AWBGetParamTypeFlashEstimationState \n
                                          ///  AWBGetParamTypePublishingVendorTagsInfo \n
                                          ///  AWBGetParamTypeDependentVendorTags \n
                                          ///  AWBGetParamTypePeerInfo \n
                                          ///  AWBGetParamTypeCctToGain \n
                                          ///  AWBGetParamTypeGainToCCT \n
                                          ///  AWBGetParamTypeBGConfig \n
                                          ///  AWBGetParamTypeFaceTone \n
                                          ///  AWBGetParamTypeLastIndex \n
                                          ///  AWBGetParamTypeMax
} AWBAlgoGetParamType;

/// @brief Types of Get input parameters for the AWB algorithm.
typedef enum
{
    AWBGetParamInputTypeInvalid             = -1,           ///< Type is unknown or invalid.
    AWBGetParamInputTypeAECData,                            ///< Payload: #AWBAlgoExposureInformation
    AWBGetParamInputTypeFlashInformation,                   ///< Payload: #AWBAlgoFlashInformation
    AWBGetParamInputTypeCameraInfo,                         ///< Payload: #StatsCameraInfo
    AWBGetParamInputTypeCCT,                                ///< CCT value passed to the algorithm to get the gains.
    AWBGetParamInputTypeGain,                               ///< AWB gains passed to the algorithm to get the CCT.
    AWBGetParamInputTypeLastIndex,                          ///< Last valid index of the enumeration.
    AWBGetParamInputTypeMax                 = 0x7FFFFFFF,   ///< Indicates the last item in the definition.
} AWBAlgoGetParamInputType;

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

/// @brief List of Get input parameters for a query from the AWB algorithm. This list is passed to #AWBAlgoGetParam.
typedef struct
{
    AWBAlgoGetParamInput*   pGetParamInputs;     ///< Pointer to the array of parameters.
    UINT32                  getParamInputCount;  ///< Number of elements in the array.
} AWBAlgoGetParamInputList;

/// @brief Types of Get output parameters for queries from the AWB algorithm.
typedef enum
{
    AWBGetParamOutputTypeInvalid                    = -1,           ///< Type is unknown or invalid.
    AWBGetParamOutputTypeDebugData,                                 ///< Payload: #StatsDataPointer
    AWBGetParamOutputTypeOutputList,                                ///< Payload: #AWBAlgoOutputList
    AWBGetParamOutputTypeAlgoVersion,                               ///< Payload: #StatsAlgorithmVersion
    AWBGetParamOutputTypeStatsRequired,                             ///< Specifies whether the AWB algorithm requires
                                                                    ///  statistics (1) or not (0).
    AWBGetParamOutputTypeFlashEstimationProgress,                   ///< AWB flash estimation progress or status. \n
                                                                    ///  Payload: #AWBAlgoFlashEstimationProgress
    AWBGetParamOutputTypePublishingVendorTagsInfo,                  ///< Vendor tags from the AWB algorithm. \n
                                                                    ///  Payload: #StatsVendorTagInfoList
    AWBGetParamOutputTypeDependentVendorTags,                       ///< Vendor tags from the AWB algorithm. \n
                                                                    ///  Payload: #StatsVendorTagInfoList
    AWBGetParamOutputTypePeerInfo,                                  ///< Pointer to the data structure for the algorithm
                                                                    ///  internal peer information.
    AWBGetParamOutputTypeCCT,                                       ///< AWB gains based on the correlated color temperature
                                                                    ///  value from the AWB algorithm.
    AWBGetParamOutputTypeGains,                                     ///< Correlated color temperature value based on AWB gains
                                                                    ///  from the AWB algorithm.
    AWBGetParamOutputTypeBGConfig,                                  ///< Get AWB statistics configuration. \n
                                                                    ///  Payload: #StatsBayerGridBayerExposureConfig
    AWBGetParamOutputTypeFaceTone,                                  ///< face tone information mainly to AEC
    AWBGetParamOutputTypeLastIndex,                                 ///< Last valid index of the enumeration.
    AWBGetParamOutputTypeMax                        = 0x7FFFFFFF,   ///< Indicates the last item in the definition.
} AWBAlgoGetParamOutputType;

/// @brief Base structure of a Get output parameter for an AWB algorithm instance. This structure is used with
///        #AWBAlgoGetParamOutputList.
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. The algorithm implementer must do
                                                                ///  a deep copy to the specified memory.
    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.
    AWBAlgoGetParamOutputType   getParamOutputType;             ///< Type of output payload.
} AWBAlgoGetParamOutput;

/// @brief Get output parameters for a query from the AWB algorithm. This structure is used with #AWBAlgoGetParam.
typedef struct
{
    AWBAlgoGetParamOutput*  pGetParamOutputs;       ///< Pointer to the array of parameters.
    UINT32                  getParamOutputCount;    ///< Number of elements in the array.
} AWBAlgoGetParamOutputList;

/// @brief List of Get parameters that are passed to #CHIAWBAlgorithm::AWBGetParam().
typedef struct
{
    AWBAlgoGetParamType         type;            ///< Type of information to get from the algorithm. This type describes the
                                                 ///  metadata for the caller.
    AWBAlgoGetParamInputList    inputInfoList;   ///< Input data that is necessary to support the query.
    AWBAlgoGetParamOutputList   outputInfoList;  ///< Output metadata that is returned as a result of the query.
} AWBAlgoGetParam;

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Describe AWB Algorithm Set Parameter definition
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

/// @brief Defines the illuminant factors.
typedef struct
{
    BOOL    isAvailable;                ///< Indicates whether white balance calibration data is available.
                                        ///
                                        ///  @valuesbul
                                        ///  - 0 -- FALSE
                                        ///  - 1 -- TRUE @tablebulletend

    UINT32  correlatedColorTemperature; ///< CCT in degrees Kelvin.
    FLOAT   ratioRG;                    ///< Red-green ratio.
    FLOAT   ratioBG;                    ///< Blue-green ratio.
} AWBAlgoIlluminatFactor;

/// @brief Defines the illuminant calibration factors.
typedef struct
{
    UINT32                  numberOfIlluminants;                ///< Number of illuminants that are calibrated.
    AWBAlgoIlluminatFactor  illuminant[StatsIlluminantCount];   ///< Array of calibration factors.
} AWBAlgoIlluminantsCalibrationFactor;

/// @brief Defines geometric disparity calibration for a dual camera.
typedef struct
{
    UINT32  versionFormat;                                      ///< Format of the calibration data version.

    FLOAT   focalLengthMaster;                                  ///< Focal length of the master camera.
    FLOAT   focalLengthRatioMaster;                             ///< Focal length ratio of the master camera.

    FLOAT   focalLengthAuxiliary;                               ///< Focal length of the auxiliary camera.
    FLOAT   focalLengthRatioAuxiliar;                           ///< Focal length ratio of the auxiliary camera.

    INT32   sensorMirrorFlipSettingMaster;                      ///< Mirror and flip setting for the master sensor.
    INT32   sensorMirrorFlipSettingAuxiliar;                    ///< Mirror and flip setting for the auxiliary sensor.
    INT32   moduleOrientationFlag;                              ///< Motion Sensor module orientation.
    INT32   rotationFlag;                                       ///< Motion Sensor module rotation.

    FLOAT   relativePrinciplePointOffsetX;                      ///< Offset X of the relative principle point.
    FLOAT   relativePrinciplePointOffsetY;                      ///< Offset Y of the relative principle point.

    INT32   relativePositionFlag;                               ///< Relative position flag.
                                                                ///
                                                                ///  @valuesbul
                                                                ///  - 0 -- Main camera is to the left of the auxiliary camera
                                                                ///  - 1 -- Main camera is to the right of the auxiliary camera
                                                                ///  @tablebulletend

    FLOAT   relativeBaselineDistance;                           ///< Separation of the main and auxiliary cameras (in
                                                                ///  millimeters).
    UINT32  numberOfRelativeRotationMatrix;                     ///< Number of entries in the relativeRotationMatrix array.
    FLOAT   relativeRotationMatrix[AWBAlgoRotationMatrixSize];  ///< Array of relative rotations.
} AWBAlgoGeometricalDisparityCalibration;

/// @brief Valid AWB processing modes.
typedef enum
{
    AWBAlgoModeOff              = 0,            ///< Manual mode: use correlated color temperature or gains.
    AWBAlgoModeAuto,                            ///< Automatic white balance is ON.
    AWBAlgoModeIncandescent,                    ///< Preset value for illuminant A.
    AWBAlgoModeFluorescent,                     ///< Preset value for illuminant F2.
    AWBAlgoModeWarmFluorescent,                 ///< Preset value for illuminant F4.
    AWBAlgoModeDaylight,                        ///< Preset value for illuminant D65.
    AWBAlgoModeCloudyDaylight,                  ///< Preset value for cloudy daylight.
    AWBAlgoModeTwilight,                        ///< Preset value for twilight.
    AWBAlgoModeShade,                           ///< Preset value for shade.
    AWBAlgoModeMax              = 0x7FFFFFFF,   ///< Indicates the last item in the definition.
} AWBAlgoMode;


/** @name AWB scene modes
  @xreflabel{AwbSceneModes}
  Defines AWB scene modes. These values mirror the APIs.
@{ */

static const UINT32 AWBAlgoSceneModeDisabled            = 0;    ///< No scene mode is given.
static const UINT32 AWBAlgoSceneModeFacePriority        = 1;    ///< If a face is detected, it is given priority during AWB.
static const UINT32 AWBAlgoSceneModeAction              = 2;    ///< Optimized for moving objects.
static const UINT32 AWBAlgoSceneModePortrait            = 3;    ///< Optimized for still photos of people.
static const UINT32 AWBAlgoSceneModeLandscape           = 4;    ///< Optimized for distant objects.
static const UINT32 AWBAlgoSceneModeNight               = 5;    ///< Optimized for low-light.
static const UINT32 AWBAlgoSceneModeNightPortrait       = 6;    ///< Optimized for still photos of people in low light.
static const UINT32 AWBAlgoSceneModeTheatre             = 7;    ///< Optimized for dim indoor settings where flash must be OFF.
static const UINT32 AWBAlgoSceneModeBeach               = 8;    ///< Optimized for beach scenes.
static const UINT32 AWBAlgoSceneModeSnow                = 9;    ///< Optimized for snow.
static const UINT32 AWBAlgoSceneModeSunset              = 10;   ///< Optimized for sunsets.
static const UINT32 AWBAlgoSceneModeSteadyphoto         = 11;   ///< Optimized to avoid hand jitter.
static const UINT32 AWBAlgoSceneModeFireworks           = 12;   ///< Optimized for night-time fireworks.
static const UINT32 AWBAlgoSceneModeSports              = 13;   ///< Optimized for people who are moving fast.
static const UINT32 AWBAlgoSceneModeParty               = 14;   ///< Optimized for dim indoor settings with people moving.
static const UINT32 AWBAlgoSceneModeCandlelight         = 15;   ///< Optimized for dim settings with candles as the main source
                                                                ///  of light.
static const UINT32 AWBAlgoSceneModeBarcode             = 16;   ///< Optimized for barcode pictures.
static const UINT32 AWBAlgoSceneModeBacklight           = 17;   ///< Optimized for scenes with backlighting.
static const UINT32 AWBAlgoSceneModeFlowers             = 18;   ///< Optimized for flowers.
static const UINT32 AWBAlgoSceneModeAugmentedReality    = 19;   ///< Optimized for augmented reality.
static const UINT32 AWBAlgoSceneModeHDR                 = 20;   ///< Optimized for HDR feature.
static const UINT32 AWBAlgoSceneModeDeviceCustomStart   = 100;  ///< Beginning of custom scene mode enumerations
                                                                ///  (including this one).

/** @} */ /* end_name AWB scene modes */


/// @brief Contains parameters for manual AWB configuration.
typedef struct
{
    AWBAlgoGains    gains;                        ///< White balance gain provided to AWB for manual control.
    FLOAT           correlatedColorTemperature;   ///< CCT (in degrees Kelvin) provided to AWB for manual control.
} AWBAlgoManualConfiguration;

/// @brief Flash illumination types.
typedef enum
{
    AWBAlgoFlashTypeLED,
    AWBAlgoFlashTypeLCD,
    AWBAlgoFlashTypeMax     = 0x7FFFFFFF,
} AWBAlgoFlashType;

/// @brief Operation modes for the AWB algorithm.
typedef enum
{
    AWBAlgoOperationModeInit,                           ///< AWB is in the initial state.
    AWBAlgoOperationModeStreaming,                      ///< AWB is in the streaming/preview state.
    AWBAlgoOperationModePreflash,                       ///< AWB is in the preflash state.
    AWBAlgoOperationModeFastConvergence,                ///< AWB is in fast AEC mode.
    AWBAlgoOperationModeMax              = 0x7FFFFFFF   ///< Indicates the last item in the definition.
} AWBAlgoOperationModeType;


#ifndef DOXYGEN_SHOULD_SKIP_THIS
#if 0
// @brief Identifies the type of input parameter to AWB algorithm.
typedef enum
{
    AWBSetParamTypeInvalid                          = -1,           ///< Type is unknown or invalid.
    AWBSetParamTypeDebugDataMode,                                   ///< Sets the debug data mode.
    AWBSetParamTypeSensorInfo,                                      ///< Sensor information type. \n
                                                                    ///  Payload: #StatsSensorInfo
    AWBSetParamTypeStatsWindow,                                     ///< Window information where statistics are been taken. \n
                                                                    ///  Payload: StatsWindowInfo
    AWBSetParamTypeChromatixData,                                   ///< Chromatix data type. \n
                                                                    ///  Payload: StatsTuningData
    AWBSetParamTypeIlluminantsCalibrationFactor,                    ///< Illuminants calibration. \n
                                                                    ///  Payload: AWBAlgoIlluminantsCalibrationFactor
    AWBSetParamTypeGeometricalDisparityCalibration,                 ///< Dual camara calibration for geometrical disparity. \n
                                                                    ///  Payload: AWBAlgoGeometricalDisparityCalibration
    AWBSetParamTypeLEDCalibrationData,                              ///< Factory calibration data done once LEDs are mounted on
                                                                    ///  device. \n
                                                                    ///  Payload: StatsLEDCalibrationDataInput
    AWBSetParamTypeManualSettings,                                  ///< Set manual WB configuration used in manual mode and to
                                                                    ///  set initial AWB settings before any statistics is
                                                                    ///  processed. \n
                                                                    ///  Payload: AWBAlgoManualConfiguration
    AWBSetParamTypeWhiteBalanceMode,                                ///< Main switch for AWB, sets algorithm in automatic,
                                                                    ///  manual, or pre-defined illuminant target. \n
                                                                    ///  Payload: AWBAlgoMode
    AWBSetParamTypeLock,                                            ///< Indicates whether the AWB is locked to the last
                                                                    ///  calculated value. (0 = FALSE, 1 = TRUE)
    AWBSetParamTypeSceneMode,                                       ///< Control which scene mode/best shot is active, if
                                                                    ///  any. \n
                                                                    ///  For details, see#AWBAlgoSceneMode.
    AWBSetParamTypeStabilizedFaceROI,                               ///< Face detection algorithm provides face region of
                                                                    ///  interest. Using FD stabilized ROI data. \n
                                                                    ///  Payload: StatsROIInformation
    AWBSetParamTypeTouchROI,                                        ///< Touch from UI provides the region of interest. \n
                                                                    ///  Payload: StatsRectangle
    AWBSetParamTypeFlashType,                                       ///< Informs algorithm about the flash type. ex. LED,
                                                                    ///  LCD. \n
                                                                    ///  Payload: AWBAlgoFlashType
    AWBSetParamTypeFlashData,                                       ///< Information about the flash state and ratios. \n
                                                                    ///  Payload: AWBAlgoFlashInformation
    AWBSetParamTypeCameraInfo,                                      ///< Information about camera id, role and type. \n
                                                                    ///  Payload: StatsCameraInfo
    AWBSetParamTypeOperationMode,                                   ///< Information about statistics Processing Mode. \n
                                                                    ///  Payload: AWBAlgoOperationModeType
    AWBSetParamTypePeerInfo,                                        ///< Multi camera peer information.
    AWBSetParamTypeUnstabilizedFaceROI,                             ///< Unstabilized Face ROI data. \n
                                                                    ///  Payload: StatsROIInformation
    AWBSetParamTypeWarmstart,                                       ///< Warmstart gains and CCT. \n
                                                                    ///  Payload: AWBAlgoWarmstartInformation
    AWBSetParamTypeExternalInfo,                                    ///< Information about the external input. \n
                                                                    ///  Payload: AWBAlgoExternalInformation
    AWBSetParamTypeCustomizedSAInfo,                                ///< Information about AWBAlgoCustomizedSAInformation. \n
                                                                    ///  Payload: AWBAlgoCustomizedSAInformation
    AWBSetParamTypeIsFixedFocus,                                    ///< Flag indicating whether sensor is fixed focus.
    AWBSetParamTypeDynamicConvergenceSpeed,                         ///< Dynamic convergence speed
    AWBSetParamTypeEspectralSensorInfo,                             ///< Information about the e-spectral sensor input
                                                                    ///  information: IR/UV/R/G/B/Clear/flicker frequency. \n
                                                                    ///  Payload: AWBAlgoEspectralSensorInformation
    AWBSetParamTypePipelineDelay,                                   ///< Information about delay in the pipeline.
    AWBSetParamTypeGyroData,                                        ///< Gyro data. \n
                                                                    ///  Payload: StatsGyroInfo
    AWBSetParamTypeAccelerometerData,                               ///< Accelerometer data. \n
                                                                    ///  Payload: StatsAccelerometerInfo
    AWBSetParamTypeFaceMetaData,                                    ///< Face metadata with with facial feature data
                                                                    ///  Payload: StatsFaceMetaData
    AWBSetParamTypeCATMapData,                                      ///< CatMap data. \n
                                                                    ///  Payload: CHIIMAGELIST
    AWBSetParamTypeLastIndex,                                       ///< Last valid index of the enumeration.
    AWBSetParamTypeMax                              = 0x7FFFFFFF,   ///< Indicates the last item in the definition.
} AWBAlgoSetParamType;
#endif // #if 0

// Defines the Set parameters for the AWB algorithm.
#define AWB_SET_ENUM_LIST(ADD_ENTRY)                            \
    ADD_ENTRY(AWBSetParamTypeInvalid)                           \
    ADD_ENTRY(AWBSetParamTypeDebugDataMode)                     \
    ADD_ENTRY(AWBSetParamTypeSensorInfo)                        \
    ADD_ENTRY(AWBSetParamTypeStatsWindow)                       \
    ADD_ENTRY(AWBSetParamTypeChromatixData)                     \
    ADD_ENTRY(AWBSetParamTypeIlluminantsCalibrationFactor)      \
    ADD_ENTRY(AWBSetParamTypeGeometricalDisparityCalibration)   \
    ADD_ENTRY(AWBSetParamTypeLEDCalibrationData)                \
    ADD_ENTRY(AWBSetParamTypeManualSettings)                    \
    ADD_ENTRY(AWBSetParamTypeWhiteBalanceMode)                  \
    ADD_ENTRY(AWBSetParamTypeLock)                              \
    ADD_ENTRY(AWBSetParamTypeSceneMode)                         \
    ADD_ENTRY(AWBSetParamTypeStabilizedFaceROI)                 \
    ADD_ENTRY(AWBSetParamTypeTouchROI)                          \
    ADD_ENTRY(AWBSetParamTypeFlashType)                         \
    ADD_ENTRY(AWBSetParamTypeFlashData)                         \
    ADD_ENTRY(AWBSetParamTypeCameraInfo)                        \
    ADD_ENTRY(AWBSetParamTypeOperationMode)                     \
    ADD_ENTRY(AWBSetParamTypePeerInfo)                          \
    ADD_ENTRY(AWBSetParamTypeUnstabilizedFaceROI)               \
    ADD_ENTRY(AWBSetParamTypeWarmstart)                         \
    ADD_ENTRY(AWBSetParamTypeExternalInfo)                      \
    ADD_ENTRY(AWBSetParamTypeCustomizedSAInfo)                  \
    ADD_ENTRY(AWBSetParamTypeIsFixedFocus)                      \
    ADD_ENTRY(AWBSetParamTypeDynamicConvergenceSpeed)           \
    ADD_ENTRY(AWBSetParamTypeOverrideSettings)                  \
    ADD_ENTRY(AWBSetParamTypeFrameId)                           \
    ADD_ENTRY(AWBSetParamTypeROIBasedAWBData)                   \
    ADD_ENTRY(AWBSetParamTypeEspectralSensorInfo)               \
    ADD_ENTRY(AWBSetParamTypePipelineDelay)                     \
    ADD_ENTRY(AWBSetParamTypeGyroData)                          \
    ADD_ENTRY(AWBSetParamTypeAccelerometerData)                 \
    ADD_ENTRY(AWBSetParamTypeSensorExposureCount)               \
    ADD_ENTRY(AWBSetParamTypeFaceMetaData)                      \
    ADD_ENTRY(AWBSetParamTypeCATMapData)                        \
    ADD_ENTRY(AWBSetParamTypeLastIndex)                         \
    ADD_ENTRY(AWBSetParamTypeMax)                               \

#endif /* DOXYGEN_SHOULD_SKIP_THIS */

/// @brief Types of Set parameters for the AWB algorithm.
typedef enum
{
    AWB_SET_ENUM_LIST(AWB_GENERATE_ENUM)  ///< List of configuration parameters. \n
                                          ///  AWBSetParamTypeInvalid \n
                                          ///  AWBSetParamTypeDebugDataMode \n
                                          ///  AWBSetParamTypeSensorInfo \n
                                          ///  AWBSetParamTypeStatsWindow \n
                                          ///  AWBSetParamTypeChromatixData \n
                                          ///  AWBSetParamTypeIlluminantsCalibrationFactor \n
                                          ///  AWBSetParamTypeGeometricalDisparityCalibration \n
                                          ///  AWBSetParamTypeLEDCalibrationData \n
                                          ///  AWBSetParamTypeManualSettings \n
                                          ///  AWBSetParamTypeWhiteBalanceMode \n
                                          ///  AWBSetParamTypeLock \n
                                          ///  AWBSetParamTypeSceneMode \n
                                          ///  AWBSetParamTypeStabilizedFaceROI \n
                                          ///  AWBSetParamTypeTouchROI \n
                                          ///  AWBSetParamTypeFlashType \n
                                          ///  AWBSetParamTypeFlashData \n
                                          ///  AWBSetParamTypeCameraInfo \n
                                          ///  AWBSetParamTypeOperationMode \n
                                          ///  AWBSetParamTypePeerInfo \n
                                          ///  AWBSetParamTypeUnstabilizedFaceROI \n
                                          ///  AWBSetParamTypeWarmstart \n
                                          ///  AWBSetParamTypeExternalInfo \n
                                          ///  AWBSetParamTypeCustomizedSAInfo \n
                                          ///  AWBSetParamTypeIsFixedFocus \n
                                          ///  AWBSetParamTypeDynamicConvergenceSpeed \n
                                          ///  AWBSetParamTypeOverrideSettings \n
                                          ///  AWBSetParamTypeFrameId \n
                                          ///  AWBSetParamTypeROIBasedAWBData \n
                                          ///  AWBSetParamTypeEspectralSensorInfo \n
                                          ///  AWBSetParamTypePipelineDelay \n
                                          ///  AWBSetParamTypeGyroData \n
                                          ///  AWBSetParamTypeAccelerometerData \n
                                          ///  AWBSetParamTypeSensorExposureCount \n
                                          ///  AWBSetParamTypeFaceMetaData \n
                                          ///  AWBSetParamTypeCATMapData \n
                                          ///  AWBSetParamTypeLastIndex \n
                                          ///  AWBSetParamTypeMax
} AWBAlgoSetParamType;

/// @brief Base structure of a Set parameter for an AWB algorithm instance. This structure is used with #AWBAlgoSetParamList.
typedef struct
{
    const VOID*         pAWBSetParam;       ///< Pointer to the parameter payload.
    UINT32              sizeOfInputParam;   ///< Size of the payload data (in bytes).
    AWBAlgoSetParamType setParamType;       ///< Type of parameter that is passed to the algorithm.
} AWBAlgoSetParam;

/// @brief List of Set parameters that are passed to #CHIAWBAlgorithm::AWBSetParam().
typedef struct
{
    AWBAlgoSetParam*    pAWBSetParams;      ///< Pointer to the array of parameters.
    UINT32              inputParamsCount;   ///< Number of elements in the array.
} AWBAlgoSetParamList;

/// @brief Parameters used when creating an AWB algorithm instance.
typedef enum
{
    AWBCreateParamsTypeInvalid              = -1,           ///< Type is unknown or invalid.
    AWBCreateParamsTypeTuningData,                          ///< Payload: #StatsTuningData
    AWBCreateParamsTypeLoggerFunctionPtr,                   ///< Pointer to the logging function. \n
                                                            ///  Payload: Statistics logger function
    AWBCreateParamTypeOperationMode,                        ///< Payload: #AWBAlgoOperationModeType
    AWBCreateParamTypeSessionHandle,                        ///< Handle of the create session. \n
                                                            ///  Payload: #CHISTATSHANDLE.
    AWBCreateParamTypeCameraOpenIndicator,                  ///< Indicates whether the camera is open (1) or closed (0).
    AWBCreateParamTypeCameraInfo,                           ///< Camera information about the algorithm role (master or
                                                            ///  slave). \n
                                                            ///  Payload: #StatsCameraInfo
    AWBCreateParamsTypeCalibrationData,                     ///< Illuminant calibration factor. \n
                                                            ///  Payload: #AWBAlgoIlluminantsCalibrationFactor
    AWBCreateParamTypeCount,                                ///< Total number of parameters.
    AWBCreateParamsTypeMax                  = 0x7FFFFFFF    ///< Indicates the last item in the definition.
} AWBAlgoCreateParamType;

/// @brief Base structure of a Create parameter for an AWB algorithm instance. This structure is used with
///        #AWBAlgoCreateParamList.
typedef struct
{
    VOID*                   pCreateParam;       ///< Pointer to the parameter payload.
    UINT32                  sizeOfCreateParam;  ///< Size of the payload data (in bytes).
    AWBAlgoCreateParamType  createParamType;    ///< Type of parameter that is passed to the algorithm.
} AWBAlgoCreateParam;

/// @brief List of Create parameters that are passed to CREATEAWB().
typedef struct
{
    AWBAlgoCreateParam* pCreateParams;        ///< Pointer to the array of parameters.
    UINT32              createParamsCount;    ///< Number of elements in the array.
} AWBAlgoCreateParamList;

/// @brief Types of Destroy parameters used for the AWB algorithm.
typedef enum
{
    AWBDestroyParamTypeInvalid               = -1,          ///< Type is unknown or invalid.
    AWBDestroyParamTypeCameraCloseIndicator,                ///< Indicates whether the camera is closed (0) or open&nbsp;(1).
    AWBDestroyParamTypeCameraInfo,                          ///< Close state of the actual camera. \n
                                                            ///  Payload: #StatsCameraInfo
    AWBDestroyParamTypeCount,                               ///< Total number of parameters.
    AWBDestroyParamTypeMax                   = 0x7FFFFFFF   ///< Indicates the last item in the definition.
} AWBAlgoDestroyParamType;

/// @brief Base structure of a Destroy parameter for an AWB algorithm instance. This structure is used with
///        #AWBAlgoDestroyParamList.
typedef struct
{
    AWBAlgoDestroyParamType 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).
} AWBAlgoDestroyParam;

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

/// @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
    BOOL   enable3ADebugData;              ///< Flag to enable or disable 3A debug data.
    BOOL   enableConcise3ADebugData;       ///< Flag to enable or disable Concise 3A debug data.
    BOOL   enable3ADebugDataCustomFilter;  ///< Flag to enable or disable 3A debug data filter.
                                           ///  @newpagetable
} AWBAlgoOverrideSettingParam;

// AWB algorithm feature capabilities
static const UINT64 AWBAlgoCapabilityAutoWB     = 0x1;          ///< Automatic white balance capability.
static const UINT64 AWBAlgoCapabilityManualWB   = (0x1 << 1);   ///< Manual white balance capability.
static const UINT64 AWBAlgoCapabilitySingleLED  = (0x1 << 2);   ///< Single LED capability.
static const UINT64 AWBAlgoCapabilityDualLED    = (0x1 << 3);   ///< Dual LED capability.
static const UINT64 AWBAlgoCapabilitySceneMode  = (0x1 << 4);   ///< Scene mode capability.
                                                                ///  @newpage

/// @brief Function wrapper for the AWB algorithm.
typedef struct /** @cond */ CHIAWBAlgorithm /** @endcond */
{
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// @cond AWBProcess @endcond
    ///
    /// @brief Runs the AWB algorithm on the given inputs.
    ///
    /// @datatypes
    /// #AWBAlgoInputList \n
    /// #AWBAlgoOutputList
    ///
    /// @param[in] pCHIAWBAlgorithm  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 (*AWBProcess)(
        CHIAWBAlgorithm*           pCHIAWBAlgorithm,
        const AWBAlgoInputList*    pInputs,
        AWBAlgoOutputList*         pOutputs);

    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// @cond AWBGetParam @endcond
    ///
    /// @brief Retrieves the most up-to-date AWB algorithm information. Typically, the output is updated after calling
    ///        AWBProcess().
    ///
    /// @datatypes
    /// #AWBAlgoGetParam
    ///
    /// @param[in]  pCHIAWBAlgorithm  Pointer to the 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(*AWBGetParam)(
        CHIAWBAlgorithm*    pCHIAWBAlgorithm,
        AWBAlgoGetParam*    pGetParam);

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

    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// @cond AWBGetFeatureCapability @endcond
    ///
    /// @brief Gets the features supported by the AWB algorithm. This interface can be invoked after the algorithm is created.
    ///
    /// @param[in] pCHIAWBAlgorithm  Pointer to the algorithm instance.
    /// @param[in] pFeatures         Pointer to the feature capabilities that the algorithm supports.
    ///
    /// @return #CDKResultSuccess or an error code (see Section @xref{hdr:resultMessages}).
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    CDKResult(*AWBGetFeatureCapability)(
        CHIAWBAlgorithm*   pCHIAWBAlgorithm,
        UINT64*            pFeatures);

    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// @cond AWBDestroy @endcond
    ///
    /// @brief Destroys a derived instance of the AWB algorithm interface.
    ///
    /// @datatypes
    /// #AWBAlgoDestroyParamList
    ///
    /// @param[in] pCHIAWBAlgorithm  Pointer to the algorithm instance.
    /// @param[in] pDestroyParams    Pointer to the list of parameters.
    ///
    /// @detdesc
    /// After the algorithm is destroyed, the client does not store any data or state associated with the current session.
    ///
    /// @return None. @newpage
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    VOID (*AWBDestroy)(
        CHIAWBAlgorithm*                 pCHIAWBAlgorithm,
        const AWBAlgoDestroyParamList*   pDestroyParams);
} CHIAWBAlgorithm; // CHIAWBAlgorithm interface

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @cond CreateAWB @endcond
///
/// @brief Creates an instance of the AWB algorithm.
///
/// @datatypes
/// #AWBAlgoCreateParamList \n
/// #CHIAWBAlgorithm
///
/// @param[in] pCreateParams      Pointer to the parameters used to create the instance.
/// @param[in] ppCHIAWBAlgorithm  Double pointer to the created algorithm instance.
///
/// @return #CDKResultSuccess or an error code (see Section @xref{hdr:resultMessages}). @newpage
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
typedef CDKResult (*CREATEAWB)(
    const AWBAlgoCreateParamList*   pCreateParams,
    CHIAWBAlgorithm**               ppCHIAWBAlgorithm);

/** @} */ /* end_addtogroup chi_stats_awb */

#pragma pack(pop)

#ifdef __cplusplus
}
#endif // __cplusplus

#endif // CHIAWBINTERFACE_H
