ntv2driverinterface.h

Go to the documentation of this file.

/* SPDX-License-Identifier: MIT */
#ifndef NTV2DRIVERINTERFACE_H
#define NTV2DRIVERINTERFACE_H
 
#include "ajatypes.h"
#include "ntv2enums.h"
#include "ntv2nubtypes.h"
#include "ntv2nubaccess.h"
#include "ntv2publicinterface.h"
#include "ntv2utils.h"
#include "ntv2devicefeatures.h"
#if defined(NTV2_WRITEREG_PROFILING)    //  Register Write Profiling
    #include "ajabase/system/lock.h"
#endif  //  NTV2_WRITEREG_PROFILING     Register Write Profiling
#include <string>
 
//  Check consistent use of AJA_USE_CPLUSPLUS11 and NTV2_USE_CPLUSPLUS11
#ifdef AJA_USE_CPLUSPLUS11
    #ifndef NTV2_USE_CPLUSPLUS11
        #error "AJA_USE_CPLUSPLUS11 && !NTV2_USE_CPLUSPLUS11"
    #else
        //#warning "AJA_USE_CPLUSPLUS11 && NTV2_USE_CPLUSPLUS11"
    #endif
#else
    #ifdef NTV2_USE_CPLUSPLUS11
        #error "!AJA_USE_CPLUSPLUS11 && NTV2_USE_CPLUSPLUS11"
    #else
        //#warning "!AJA_USE_CPLUSPLUS11 && !NTV2_USE_CPLUSPLUS11"
    #endif
#endif
 
#if defined(AJALinux ) || defined(AJAMac)
//  #include <sys/types.h>  //  ** MrBill **    Not needed for AJALinux, needed for AJAMac?
//  #include <netinet/in.h> //  ** MrBill **    Not needed for AJALinux, needed for AJAMac?
    #include <unistd.h> //  for usleep
#elif defined(MSWindows)
    #include <WinSock2.h>
    #include <assert.h>
#endif
 
 
#define AsNTV2DriverInterfaceRef(_x_)   reinterpret_cast<CNTV2DriverInterface&>(_x_)
#define AsNTV2DriverInterfacePtr(_x_)   reinterpret_cast<CNTV2DriverInterface*>(_x_)
 
 
typedef struct
{
    std::string     buildNumber;
    std::string     packageNumber;
    std::string     date;
    std::string     time;
} PACKAGE_INFO_STRUCT, *PPACKAGE_INFO_STRUCT;
 
 
class AJAExport CNTV2DriverInterface
{
    //  STATIC (CLASS) METHODS
    public:
        static NTV2StringList   GetLegalSchemeNames (void); 
        static inline UWord     MaxNumDevices (void)    {return 32;}    
 
        static void             SetShareMode (const bool inSharedMode);
        static bool             GetShareMode (void);    
 
        static void             SetOverlappedMode (const bool inOverlapMode);
        static bool             GetOverlappedMode (void);   
 
    public:
                CNTV2DriverInterface();     
        virtual ~CNTV2DriverInterface();    
 
    private:
        AJA_VIRTUAL CNTV2DriverInterface & operator = (const CNTV2DriverInterface & inRHS);
 
        CNTV2DriverInterface (const CNTV2DriverInterface & inObjToCopy);
 
    public:
        AJA_VIRTUAL NTV2DeviceID    GetDeviceID (void); 
        AJA_VIRTUAL inline UWord    GetIndexNumber (void) const {return _boardNumber;}  
        AJA_VIRTUAL inline bool     IsOpen (void) const         {return _boardOpened;}  
 
        AJA_VIRTUAL bool        IsDeviceReady (const bool inCheckValid = false);
        AJA_VIRTUAL bool        IsMBSystemValid (void); 
        AJA_VIRTUAL bool        IsMBSystemReady (void); 
        AJA_VIRTUAL inline bool IsIPDevice (void)   {return ::NTV2DeviceCanDoIP(GetDeviceID());}    
 
 
        AJA_VIRTUAL bool        Open (const UWord inDeviceIndex);
 
        AJA_VIRTUAL bool        Open (const std::string & inURLSpec);
 
        AJA_VIRTUAL bool        Close (void);
 
 
        AJA_VIRTUAL bool    WriteRegister (const ULWord inRegNum,  const ULWord inValue,  const ULWord inMask = 0xFFFFFFFF,  const ULWord inShift = 0);
 
        AJA_VIRTUAL bool    ReadRegister (const ULWord inRegNum,  ULWord & outValue,  const ULWord inMask = 0xFFFFFFFF,  const ULWord inShift = 0);
 
        template<typename T> bool   ReadRegister(const ULWord inRegNum,  T & outValue,  const ULWord inMask = 0xFFFFFFFF,  const ULWord inShift = 0)
                                    {
                                        ULWord regValue(0);
                                        bool result (ReadRegister(inRegNum, regValue, inMask, inShift));
                                        if (result)
                                            outValue = T(regValue);
                                        return result;
                                    }
 
#if !defined(READREGMULTICHANGE)
 
        AJA_VIRTUAL bool    ReadRegisters (NTV2RegisterReads & inOutValues);
#endif  //  !defined(READREGMULTICHANGE)
        AJA_VIRTUAL bool    RestoreHardwareProcampRegisters() = 0;
 
 
        AJA_VIRTUAL bool    DmaTransfer (const NTV2DMAEngine    inDMAEngine,
                                        const bool              inIsRead,
                                        const ULWord            inFrameNumber,
                                        ULWord *                pFrameBuffer,
                                        const ULWord            inCardOffsetBytes,
                                        const ULWord            inTotalByteCount,
                                        const bool              inSynchronous = true);
 
        AJA_VIRTUAL bool    DmaTransfer (const NTV2DMAEngine    inDMAEngine,
                                        const bool              inIsRead,
                                        const ULWord            inFrameNumber,
                                        ULWord *                pFrameBuffer,
                                        const ULWord            inCardOffsetBytes,
                                        const ULWord            inTotalByteCount,
                                        const ULWord            inNumSegments,
                                        const ULWord            inHostPitchPerSeg,
                                        const ULWord            inCardPitchPerSeg,
                                        const bool              inSynchronous = true)   = 0;
 
        AJA_VIRTUAL bool    DmaTransfer (const NTV2DMAEngine        inDMAEngine,
                                        const NTV2Channel           inDMAChannel,
                                        const bool                  inTarget,
                                        const ULWord                inFrameNumber,
                                        const ULWord                inCardOffsetBytes,
                                        const ULWord                inByteCount,
                                        const ULWord                inNumSegments,
                                        const ULWord                inSegmentHostPitch,
                                        const ULWord                inSegmentCardPitch,
                                        const PCHANNEL_P2P_STRUCT & inP2PData)  = 0;
 
        AJA_VIRTUAL bool    ConfigureSubscription (const bool bSubscribe, const INTERRUPT_ENUMS inInterruptType, PULWord & outSubcriptionHdl);
        AJA_VIRTUAL bool    ConfigureInterrupt (const bool bEnable,  const INTERRUPT_ENUMS eInterruptType) = 0;
        AJA_VIRTUAL bool    GetInterruptCount (const INTERRUPT_ENUMS eInterrupt,  ULWord & outCount) = 0;
 
        AJA_VIRTUAL bool    WaitForInterrupt (const INTERRUPT_ENUMS eInterrupt, const ULWord timeOutMs = 68);
 
        AJA_VIRTUAL HANDLE  GetInterruptEvent (const INTERRUPT_ENUMS eInterruptType);
        AJA_VIRTUAL bool    GetInterruptEventCount (const INTERRUPT_ENUMS inEventCode, ULWord & outCount);
 
        AJA_VIRTUAL bool    SetInterruptEventCount (const INTERRUPT_ENUMS inEventCode, const ULWord inCount);
 
 
        AJA_VIRTUAL bool        AutoCirculate (AUTOCIRCULATE_DATA & pAutoCircData);
 
        AJA_VIRTUAL bool        NTV2Message (NTV2_HEADER * pInMessage);
 
        AJA_VIRTUAL inline bool HevcSendMessage (HevcMessageHeader * pMessage)      {(void) pMessage; return false;}
 
        AJA_VIRTUAL bool    ControlDriverDebugMessages (NTV2_DriverDebugMessageSet msgSet,  bool enable) = 0;
 
        AJA_VIRTUAL inline ULWord   GetNumFrameBuffers (void) const             {return _ulNumFrameBuffers;}
        AJA_VIRTUAL inline ULWord   GetFrameBufferSize (void) const             {return _ulFrameBufferSize;}
 
        AJA_VIRTUAL bool DriverGetBitFileInformation (BITFILE_INFO_STRUCT & outBitFileInfo,  const NTV2BitFileType inBitFileType = NTV2_VideoProcBitFile);
 
        AJA_VIRTUAL bool DriverGetBuildInformation (BUILD_INFO_STRUCT & outBuildInfo);
 
        AJA_VIRTUAL bool GetPackageInformation (PACKAGE_INFO_STRUCT & outPkgInfo);
 
        AJA_VIRTUAL bool BitstreamWrite (const NTV2Buffer & inBuffer, const bool inFragment, const bool inSwap);
        AJA_VIRTUAL bool BitstreamReset (const bool inConfiguration, const bool inInterface);
        AJA_VIRTUAL bool BitstreamStatus (NTV2ULWordVector & outRegValues);
        AJA_VIRTUAL bool BitstreamLoad (const bool inSuspend, const bool inResume);
 
 
        AJA_VIRTUAL bool        IsSupported (const NTV2BoolParamID inParamID)   //  New in SDK 17.0
                                    {   ULWord value(0);
                                        GetBoolParam (ULWord(inParamID), value);
                                        return bool(value);
                                    }
        AJA_VIRTUAL ULWord      GetNumSupported (const NTV2NumericParamID inParamID)    //  New in SDK 17.0
                                    {   ULWord value(0);
                                        GetNumericParam (ULWord(inParamID), value);
                                        return value;
                                    }
 
        AJA_VIRTUAL ULWordSet   GetSupportedItems (const NTV2EnumsID inEnumsID);    //  New in SDK 17.0
 
        // stream channel operations
        AJA_VIRTUAL bool    StreamChannelOps (const NTV2Channel inChannel,
                                                ULWord flags,
                                                NTV2StreamChannel& status);
 
        // stream buffer operations
        AJA_VIRTUAL bool    StreamBufferOps (const NTV2Channel inChannel,
                                                NTV2_POINTER inBuffer,
                                                ULWord64 bufferCookie,
                                                ULWord flags,
                                                NTV2StreamBuffer& status);
    
 
        AJA_VIRTUAL bool AcquireStreamForApplicationWithReference (const ULWord inAppType, const int32_t inProcessID);
 
        AJA_VIRTUAL bool ReleaseStreamForApplicationWithReference (const ULWord inAppType, const int32_t inProcessID);
 
        AJA_VIRTUAL bool AcquireStreamForApplication (const ULWord inAppType, const int32_t inProcessID);
 
        AJA_VIRTUAL bool ReleaseStreamForApplication (const ULWord inAppType, const int32_t inProcessID);
 
        AJA_VIRTUAL bool SetStreamingApplication (const ULWord inAppType, const int32_t inProcessID);
 
        AJA_VIRTUAL bool GetStreamingApplication (ULWord & outAppType, int32_t & outProcessID);
 
        AJA_VIRTUAL bool                ReadRP188Registers (const NTV2Channel inChannel, RP188_STRUCT * pRP188Data);
        AJA_VIRTUAL inline std::string  GetHostName (void) const    {return IsRemote() ? _pRPCAPI->Name() : "";}    
        AJA_VIRTUAL inline bool         IsRemote (void) const       {return _pRPCAPI ? true : false;}   
 
        AJA_VIRTUAL inline std::string  GetDescription (void) const {return IsRemote() ? _pRPCAPI->Description() : "";} //  New in SDK 17.0
#if defined(NTV2_NUB_CLIENT_SUPPORT)  &&  !defined(NTV2_DEPRECATE_16_0)
        AJA_VIRTUAL inline NTV2NubProtocolVersion   GetNubProtocolVersion (void) const  {return 0;} 
#endif
 
        //  DEPRECATED FUNCTIONS
#if !defined(NTV2_DEPRECATE_16_0)
    // SuspendAudio/ResumeAudio were only implemented on MacOS
    AJA_VIRTUAL inline NTV2_SHOULD_BE_DEPRECATED(bool SuspendAudio(void))   {return true;}
    AJA_VIRTUAL inline NTV2_SHOULD_BE_DEPRECATED(bool ResumeAudio(const ULWord inFBSize))   {(void) inFBSize; return true;}
    //  Memory Mapping/Unmapping
    AJA_VIRTUAL inline NTV2_DEPRECATED_f(bool MapFrameBuffers(void))    {return false;} 
    AJA_VIRTUAL inline NTV2_DEPRECATED_f(bool UnmapFrameBuffers(void))  {return true;}  
    AJA_VIRTUAL inline NTV2_DEPRECATED_f(bool MapRegisters(void))       {return false;} 
    AJA_VIRTUAL inline NTV2_DEPRECATED_f(bool UnmapRegisters(void))     {return true;}  
    AJA_VIRTUAL inline NTV2_DEPRECATED_f(bool MapXena2Flash(void))      {return false;} 
    AJA_VIRTUAL inline NTV2_DEPRECATED_f(bool UnmapXena2Flash(void))    {return true;}  
    //  Others
    AJA_VIRTUAL inline NTV2_DEPRECATED_f(bool DmaUnlock(void))  {return false;} 
    AJA_VIRTUAL inline NTV2_DEPRECATED_f(bool CompleteMemoryForDMA(ULWord * pHostBuffer))   {(void)pHostBuffer; return false;}  
    AJA_VIRTUAL inline NTV2_DEPRECATED_f(bool PrepareMemoryForDMA(ULWord * pHostBuffer, const ULWord inNumBytes))   {(void)pHostBuffer; (void)inNumBytes; return false;}    
    AJA_VIRTUAL inline NTV2_SHOULD_BE_DEPRECATED(bool GetInterruptCount(const INTERRUPT_ENUMS eInt, ULWord *pCnt))  {return pCnt ? GetInterruptCount(eInt, *pCnt) : false;} 
    AJA_VIRTUAL NTV2_SHOULD_BE_DEPRECATED(bool ReadRegisterMulti(const ULWord numRegs, ULWord * pOutWhichRegFailed, NTV2RegInfo aRegs[]));  
    AJA_VIRTUAL inline NTV2_SHOULD_BE_DEPRECATED(ULWord GetPCISlotNumber(void) const)   {return _pciSlot;}          
    AJA_VIRTUAL NTV2_SHOULD_BE_DEPRECATED(Word SleepMs(const LWord msec));  
    AJA_VIRTUAL inline NTV2_SHOULD_BE_DEPRECATED(ULWord GetAudioFrameBufferNumber(void) const)  {return GetNumFrameBuffers() - 1;}  
#endif  //  !defined(NTV2_DEPRECATE_16_0)
#if !defined(NTV2_DEPRECATE_16_3)
    AJA_VIRTUAL inline NTV2_DEPRECATED_f(bool SetDefaultDeviceForPID(const int32_t procID)) {(void)procID; return false;}   
    AJA_VIRTUAL inline NTV2_DEPRECATED_f(bool IsDefaultDeviceForPID(const int32_t procID))  {(void)procID; return false;}   
#endif  //  !defined(NTV2_DEPRECATE_16_3)
 
#if defined(NTV2_WRITEREG_PROFILING)    //  Register Write Profiling
 
        AJA_VIRTUAL bool    GetRecordedRegisterWrites (NTV2RegisterWrites & outRegWrites) const;    
        AJA_VIRTUAL bool    StartRecordRegisterWrites (const bool inSkipActualWrites = false);  
        AJA_VIRTUAL bool    IsRecordingRegisterWrites (void) const;     
        AJA_VIRTUAL bool    StopRecordRegisterWrites (void);            
        AJA_VIRTUAL bool    PauseRecordRegisterWrites (void);           
        AJA_VIRTUAL bool    ResumeRecordRegisterWrites (void);          
        AJA_VIRTUAL ULWord  GetNumRecordedRegisterWrites (void) const;  
#endif  //  NTV2_WRITEREG_PROFILING     //  Register Write Profiling
 
 
    //  PROTECTED METHODS
    protected:
        AJA_VIRTUAL bool    OpenRemote (const std::string & inURLSpec);
        AJA_VIRTUAL bool    CloseRemote (void); 
        AJA_VIRTUAL bool    OpenLocalPhysical (const UWord inDeviceIndex);  
        AJA_VIRTUAL bool    CloseLocalPhysical (void);  
        AJA_VIRTUAL bool    ParseFlashHeader (BITFILE_INFO_STRUCT & outBitfileInfo);
        AJA_VIRTUAL bool    GetBoolParam (const ULWord inParamID,  ULWord & outValue);  //  New in SDK 17.0
        AJA_VIRTUAL bool    GetNumericParam (const ULWord inParamID,  ULWord & outValue);   //  New in SDK 17.0
 
        AJA_VIRTUAL bool    GetRegInfoForBoolParam (const NTV2BoolParamID inParamID, NTV2RegInfo & outRegInfo);
        AJA_VIRTUAL bool    GetRegInfoForNumericParam (const NTV2NumericParamID inParamID, NTV2RegInfo & outRegInfo);
 
        AJA_VIRTUAL void    BumpEventCount (const INTERRUPT_ENUMS eInterruptType);
 
        AJA_VIRTUAL void    FinishOpen (void);
        AJA_VIRTUAL bool    ReadFlashULWord (const ULWord inAddress, ULWord & outValue, const ULWord inRetryCount = 1000);
 
 
    //  PRIVATE TYPES
    protected:
        typedef std::vector<ULWord>     _EventCounts;
        typedef std::vector<PULWord>    _EventHandles;
 
 
    //  MEMBER DATA
    protected:
        UWord               _boardNumber;           
        NTV2DeviceID        _boardID;               
        bool                _boardOpened;           
#if defined(NTV2_WRITEREG_PROFILING)
        bool                mRecordRegWrites;       
        bool                mSkipRegWrites;         
#endif  //  NTV2_WRITEREG_PROFILING
        ULWord              _programStatus;
        NTV2RPCAPI *        _pRPCAPI;               
        _EventHandles       mInterruptEventHandles; 
        _EventCounts        mEventCounts;           
#if defined(NTV2_WRITEREG_PROFILING)
        NTV2RegisterWrites  mRegWrites;             
        mutable AJALock     mRegWritesLock;         
#endif  //  NTV2_WRITEREG_PROFILING
#if !defined(NTV2_DEPRECATE_16_0)
        ULWord *            _pFrameBaseAddress;         
        ULWord *            _pRegisterBaseAddress;      
        ULWord              _pRegisterBaseAddressLength;
        ULWord *            _pXena2FlashBaseAddress;    
        ULWord *            _pCh1FrameBaseAddress;      
        ULWord *            _pCh2FrameBaseAddress;      
#endif  //  !defined(NTV2_DEPRECATE_16_0)
        ULWord              _ulNumFrameBuffers;
        ULWord              _ulFrameBufferSize;
        ULWord              _pciSlot;                   //  DEPRECATE!
 
};  //  CNTV2DriverInterface
 
#endif  //  NTV2DRIVERINTERFACE_H