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

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @file  chinisusecaseinterface.h
/// @brief CHI NIS(non-image sensor) nis usecase interface declarations
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

#ifndef CHINISUSECASEINTERFACE_H
#define CHINISUSECASEINTERFACE_H

#include <assert.h>
#include "camxcdktypes.h"
#include "chxdefs.h"
#include "camera3.h"


class NISUsecaseDevice;

/** @addtogroup chi_common_nis_usecase
@{ */

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// NIS usecase interface APIs
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

/// @brief Callback functions implemented in the Non-Image Sensor (NIS) use case device called by the CHI override module.
struct ChiNISUsecaseOps
{
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// @cond process_nis_result @endcond
    ///
    /// @brief Defines the prototype for the callback method to send completed capture results to the NIS use case.
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    VOID (*process_nis_result)(
        NISUsecaseDevice*,
        const camera3_capture_result_t*);

    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// @cond process_nis_message @endcond
    ///
    /// @brief Defines the prototype for the asynchronous notification callback method from to the NIS use case interface
    ///        class.
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    VOID (*process_nis_message)(
        NISUsecaseDevice*,
        const camera3_notify_msg_t*);

    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// @cond process_nis_message @endcond
    ///
    /// @ingroup chi_common_nis_usecase
    ///
    /// @brief Defines the prototype for the asynchronous notification callback method from to the NIS use case interface
    ///        class.
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    UINT (*get_frame_rate)(
        NISUsecaseDevice*);
};

/// @brief Private data used between a CHI override module and the NIS use case.
struct NISUsecaseInfo
{
    VOID*              pUsecase;          ///< Pointer to the use case class that is assigned by the CHI override module.
    UsecaseId          usecaseId;         ///< Identifier of the use case assigned by the CHI override module.

    BOOL               internalTrigger;   ///< Indicates whether the stream configuration is internally triggered.
                                          ///
                                          ///  @valuesbul
                                          ///   - 0 -- FALSE
                                          ///   - 1 -- TRUE @tablebulletend

    ChiNISUsecaseOps   NISUsecaseCb;      ///< Callback functions implemented in NISUsecaseDevice.
    NISUsecaseDevice*  pData;             ///< Pointer to the NISUsecaseDevice instance used for NIS use case callback
                                          ///  functions.

    BOOL               isAONUsecase;      ///< Indicates whether this instance is an Always ON use case.
                                          ///
                                          ///  @valuesbul
                                          ///   - 0 -- FALSE
                                          ///   - 1 -- TRUE @tablebulletend
};

/// @brief Callback data that contains the result buffer from the NISUsecaseDevice class.
typedef struct /** @cond */ ChiNISUsecaseIntfCbData /** @endcond */
{
    VOID*              pUsecase;        ///< Pointer to the handle of the NIS use case.
    UINT               physCameraId;    ///< Identifier of the physical camera in the NIS use case.
    UINT               frameNumber;     ///< Frame number of the result buffer.
    CHISTREAMFORMAT    streamformat;    ///< Format of the use case output stream.
    VOID*              pData;           ///< Pointer to the handle of the result buffer.
    UINT               dataSize;        ///< Data length of the result buffer.
    UINT64             timestamp;       ///< Timestamp of the result buffer.
} CHINISUSECASEINTFCBDATA;

/// @brief Contains the NIS use case message type.
typedef enum /** @cond */ ChiNISUsecaseMsgType /** @endcond */
{
    UsecasePCRError = 0,     ///< CSS use case hit a fatal error during a Process Capture Request (PCR).
} CHINISUSECASEMSGTYPE;

/// @brief Contains the callback message type for an NIS use case.
typedef struct /** @cond */ ChiNISUsecaseIntfCbMsg /** @endcond */
{
    UINT                 physCameraId;    ///< Unique identifier of the physical camera.
    CHINISUSECASEMSGTYPE messageType;     ///< Type of message.
} CHINISUSECASEINTFCBMSG;

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @cond PFNCLIENTDATACB @endcond
///
/// @brief Callback function for client data.
///
/// @datatypes
/// #CHINISUSECASEINTFCBDATA
///
/// @param[in] pClient  Pointer to the client.
/// @param[in] pCbData  Pointer to the callback data.
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
typedef VOID (*PFNCLIENTDATACB)(VOID* pClient, CHINISUSECASEINTFCBDATA* pCbData);

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @cond PFNCLIENTMSGCB @endcond
///
/// @brief Callback function for a message from the NIS use case to a client.
///
/// @datatypes
/// #CHINISUSECASEINTFCBMSG
///
/// @param[in] pClient  Pointer to the client.
/// @param[in] msg      Message contents.
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
typedef VOID (*PFNCLIENTMSGCB)(VOID* pClient, CHINISUSECASEINTFCBMSG msg);

/// @brief Parameters used when creating data for an NIS use case.
typedef struct /** @cond */ ChiNISUsecaseCreateData /** @endcond */
{
    UINT            physicalCamId;         ///< Identifier of the physical camera for the CSS use case.
    UINT            width;                 ///< Width of the result buffer.
    UINT            height;                ///< Height of the result buffer.
    UINT            bitsPerPixel;          ///< Result buffer bpp.
    UINT            frameRate;             ///< Result buffer frame rate of the result buffer.
    ChiStreamFormat outputStreamFormat;    ///< Format of the use case output stream.
    CHIDATASPACE    outputColorSpace;      ///< Data space for the use case output stream.

    BOOL            isExternalTrigger;     ///< Indicates whether the NIS use case is a framework external trigger.
                                           ///
                                           ///  @valuesbul
                                           ///   - 0 -- FALSE
                                           ///   - 1 -- TRUE @tablebulletend

    INT             logicCamIdOfClient;    ///< Identifier of the logical camera for the client.

    BOOL            isAONUsecaseData;      ///< Indicates whether this instance is an Always ON camera use case data.
                                           ///
                                           ///  @valuesbul
                                           ///   - 0 -- FALSE
                                           ///   - 1 -- TRUE @tablebulletend
    BOOL            isSyncCreate;          ///< Indicates whether this usecase creation is sync or async.
                                           ///
                                           ///  @valuesbul
                                           ///   - 0 -- FALSE
                                           ///   - 1 -- TRUE @tablebulletend
} CHINISUSECASECREATEDATA;

/// @brief Contains data used when creating a use case interface.
typedef struct /** @cond */ ChiNISUsecaseIntfCreateData /** @endcond */
{
    VOID*            pClient;              ///< Pointer to the client.
    PFNCLIENTDATACB  pFnClientDataCb;      ///< Callback for the client data.
    PFNCLIENTMSGCB   pFnClientMsgCb;       ///< Callback for client message.
} CHINISUECASEINTFCREATEDATA;

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @cond PFNINITNISUSECASEINTERFACE @endcond
///
/// @brief Initializes an instance of the NIS use case interface.
///
/// @datatypes
/// #CHINISUECASEINTFCREATEDATA
///
/// @param[in] pCreateData  Pointer to the data structure that contains parameters for initializing the instance.
///
/// @return None. @newpage
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
typedef VOID* (*PFNINITNISUSECASEINTERFACE)(CHINISUECASEINTFCREATEDATA* pCreateData);

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @cond PFNTRIGGERUSECASECREATION @endcond
///
/// @brief Creates an instance of the NIS use case interface.
///
/// @datatypes
/// #CHINISUSECASECREATEDATA
///
/// @param[in] pCreateData    Pointer to the data structure that contains parameters for creating the instance.
/// @param[in] pIntfInstance  Pointer to the instance of the interface.
///
/// @return None.
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
typedef VOID* (*PFNTRIGGERUSECASECREATION)(CHINISUSECASECREATEDATA* pCreateData, VOID* pIntfInstance);

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @cond PFNTRIGGERUSECASESTREAMON @endcond
///
/// @brief Triggers a stream ON operation for an NIS use case.
///
/// @param[in] pUsecase       Pointer to the use case.
/// @param[in] pIntfInstance  Pointer to the instance of the interface.
///
/// @return None.
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
typedef CDKResult (*PFNTRIGGERUSECASESTREAMON)(VOID* pUsecase, VOID* pIntfInstance);

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @cond PFNTRIGGERUSECASEUPDATEMETADATA @endcond
///
/// @brief Triggers a update metadata operation for an NIS use case.
///
/// @param[in] pUsecase       Pointer to the use case.
/// @param[in] pIntfInstance  Pointer to the instance of the interface.
/// @param[in] pData          Data used to update metadata
///
/// @return CDK result.
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
typedef CDKResult (*PFNTRIGGERUSECASEUPDATEMETADATA)(VOID* pUsecase, VOID* pIntfInstance, VOID* pdata);

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @cond PFNTRIGGERUSECASESTREAMOFF @endcond
///
/// @brief Triggers a stream OFF operation for an NIS use case.
///
/// @param[in] pUsecase       Pointer to the use case.
/// @param[in] pIntfInstance  Pointer to the instance of the interface.
///
/// @return None. @newpage
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
typedef CDKResult (*PFNTRIGGERUSECASESTREAMOFF)(VOID* pUsecase, VOID* pIntfInstance);

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @cond PFNTRIGGERUSECASEDESTROY @endcond
///
/// @brief Destroys an instance of the NIS use case interface.
///
/// @param[in] pUsecase       Pointer to the use case.
/// @param[in] pIntfInstance  Pointer to the instance of the interface.
///
/// @return None.
///
/// @dependencies
/// The use case must have been created via #PFNTRIGGERUSECASECREATION.
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
typedef CDKResult (*PFNTRIGGERUSECASEDESTROY)(VOID* pUsecase, VOID* pIntfInstance);

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @cond PFNUNINITNISUSECASEINTERFACE @endcond
///
/// @brief De-initializes an instance of the NIS use case interface.
///
/// @param[in] pIntfInstance  Pointer to the instance of the interface.
///
/// @return None.
///
/// @dependencies
/// The use case must have been initialized via #PFNINITNISUSECASEINTERFACE. @newpage
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
typedef CDKResult (*PFNUNINITNISUSECASEINTERFACE)(VOID* pIntfInstance);

/// @brief Contains operations performed on an instance of the NIS use case interface.
typedef struct /** @cond */ ChiNISUsecaseInterfaceOps /** @endcond */
{
    UINT32                          size;                           ///< Size of this structure.
    PFNINITNISUSECASEINTERFACE      pInitNISUsecaseInterface;       ///< Initialize an NIS use case instance.
    PFNTRIGGERUSECASECREATION       pTriggerUsecaseCreation;        ///< Trigger creation of an NIS use case instance.
    PFNTRIGGERUSECASESTREAMON       pTriggerUsecaseStreamOn;        ///< Trigger stream ON for an NIS use case instance.
    PFNTRIGGERUSECASEUPDATEMETADATA pTriggerUsecaseUpdateMetadata;  ///< Trigger update metadata for an NIS use case instance.
    PFNTRIGGERUSECASESTREAMOFF      pTriggerUsecaseStreamOff;       ///< Trigger stream OFF for an NIS use case instance.
    PFNTRIGGERUSECASEDESTROY        pTriggerUsecaseDestroy;         ///< Trigger destruction of an NIS use case instance.
    PFNUNINITNISUSECASEINTERFACE    pUninitNISUsecaseInterface;     ///< De-initialize an NIS use case instance.
                                                                    ///  @newpagetable
} CHINISUSECASEINTERFACEOPS;


///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @cond PCHXNISUSECASEINTERFACEENTRY @endcond
///
/// @brief Entry function to the use case interface.
///
/// @datatypes
/// #CHINISUSECASEINTERFACEOPS
///
/// @param[in] pNISUsecaseInterfaceOps  Pointer to the structure that contains the operation parameters.
///
/// @return None. @newpage
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
typedef VOID (*PCHXNISUSECASEINTERFACEENTRY)(CHINISUSECASEINTERFACEOPS* pNISUsecaseInterfaceOps);

/** @} */ /* end_addtogroup chi_common_nis_usecase */


#endif // CHINISUSECASEINTERFACE_H
