ntv2utils.h

Go to the documentation of this file.

/* SPDX-License-Identifier: MIT */
#ifndef NTV2UTILS_H
#define NTV2UTILS_H

#include "ajaexport.h"
#include "ajatypes.h"
#include "ntv2enums.h"
#include "ntv2videodefines.h"
#include "ntv2publicinterface.h"
#include "ntv2formatdescriptor.h"
#include <string>
#include <iostream>
#include <vector>
#if defined (AJALinux)
    #include <stdint.h>
#endif

#define Enum2Str(e)  {e, #e},
//  BEGIN SECTION MOVED FROM 'videoutilities.h'
#define DEFAULT_PATT_GAIN               0.9     //  some patterns pay attention to this...
#define HD_NUMCOMPONENTPIXELS_2K        2048
#define HD_NUMCOMPONENTPIXELS_1080_2K   2048
#define HD_NUMCOMPONENTPIXELS_1080      1920

#define CCIR601_10BIT_BLACK             64      //  0x040
#define CCIR601_10BIT_WHITE             940     //  0x3AC
#define CCIR601_10BIT_CHROMAOFFSET      512     //  0x200

#define CCIR601_8BIT_BLACK              16      //  0x10
#define CCIR601_8BIT_WHITE              235     //  0xEB
#define CCIR601_8BIT_CHROMAOFFSET       128     //  0x80

// line pitch is in bytes.
#define FRAME_0_BASE                            (0x0)
#define FRAME_1080_10BIT_LINEPITCH              (1280*4)
#define FRAME_1080_8BIT_LINEPITCH               (1920*2)
#define FRAME_QUADHD_10BIT_SIZE                 (FRAME_1080_10BIT_LINEPITCH*2160)
#define FRAME_QUADHD_8BIT_SIZE                  (FRAME_1080_8BIT_LINEPITCH*2160)
#define FRAME_BASE(__frameNum__,__frameSize__)  ((__frameNum__)*(__frameSize__))

AJAExport NTV2_SHOULD_BE_DEPRECATED(uint32_t CalcRowBytesForFormat (const NTV2FrameBufferFormat inPF, const uint32_t pixWidth));    
AJAExport void UnPack10BitYCbCrBuffer (uint32_t* packedBuffer, uint16_t* ycbcrBuffer, uint32_t numPixels);
AJAExport void PackTo10BitYCbCrBuffer (const uint16_t *ycbcrBuffer, uint32_t *packedBuffer, const uint32_t numPixels);
AJAExport void MakeUnPacked10BitYCbCrBuffer (uint16_t* buffer, uint16_t Y , uint16_t Cb , uint16_t Cr,uint32_t numPixels);
AJAExport void ConvertLineTo8BitYCbCr (const uint16_t * ycbcr10BitBuffer, uint8_t * ycbcr8BitBuffer,    const uint32_t numPixels);
AJAExport void ConvertUnpacked10BitYCbCrToPixelFormat (uint16_t *unPackedBuffer, uint32_t *packedBuffer, uint32_t numPixels, NTV2FrameBufferFormat pixelFormat,
                                                        bool bUseSmpteRange=false, bool bAlphaFromLuma=false);
AJAExport void MaskUnPacked10BitYCbCrBuffer (uint16_t* ycbcrUnPackedBuffer, uint16_t signalMask , uint32_t numPixels);
AJAExport void StackQuadrants (uint8_t* pSrc, uint32_t srcWidth, uint32_t srcHeight, uint32_t srcRowBytes, uint8_t* pDst);
AJAExport void CopyFromQuadrant (uint8_t* srcBuffer, uint32_t srcHeight, uint32_t srcRowBytes, uint32_t srcQuadrant, uint8_t* dstBuffer,  uint32_t quad13Offset=0);
AJAExport void CopyToQuadrant (uint8_t* srcBuffer, uint32_t srcHeight, uint32_t srcRowBytes, uint32_t dstQuadrant, uint8_t* dstBuffer, uint32_t quad13Offset=0);
//  END SECTION MOVED FROM 'videoutilities.h'

AJAExport bool      UnpackLine_10BitYUVtoUWordSequence (const void * pIn10BitYUVLine, UWordSequence & out16BitYUVLine, ULWord inNumPixels);

AJAExport bool      PackLine_UWordSequenceTo10BitYUV (const UWordSequence & in16BitYUVLine, ULWord * pOut10BitYUVLine, const ULWord inNumPixels);

AJAExport bool YUVComponentsTo10BitYUVPackedBuffer (const std::vector<uint16_t> & inYCbCrLine, NTV2Buffer & inFrameBuffer,
                                                    const NTV2FormatDescriptor & inDescriptor, const UWord inLineOffset);

AJAExport bool UnpackLine_10BitYUVtoU16s (std::vector<uint16_t> & outYCbCrLine, const NTV2Buffer & inFrameBuffer,
                                            const NTV2FormatDescriptor & inDescriptor, const UWord inLineOffset);

AJAExport void UnpackLine_10BitYUVto16BitYUV (const ULWord * pIn10BitYUVLine, UWord * pOut16BitYUVLine, const ULWord inNumPixels);

AJAExport void PackLine_16BitYUVto10BitYUV (const UWord * pIn16BitYUVLine, ULWord * pOut10BitYUVLine, const ULWord inNumPixels);

AJAExport void RePackLineDataForYCbCrDPX (ULWord *packedycbcrLine, ULWord numULWords);
AJAExport void UnPack10BitDPXtoRGBAlpha10BitPixel (RGBAlpha10BitPixel* rgba10BitBuffer, const ULWord * DPXLinebuffer, ULWord numPixels, bool bigEndian);
AJAExport void UnPack10BitDPXtoForRP215withEndianSwap(UWord* rawrp215Buffer,ULWord* DPXLinebuffer ,ULWord numPixels);
AJAExport void UnPack10BitDPXtoForRP215(UWord* rawrp215Buffer,ULWord* DPXLinebuffer ,ULWord numPixels);
AJAExport void MaskYCbCrLine(UWord* ycbcrLine, UWord signalMask , ULWord numPixels);

AJAExport void Make10BitBlackLine (UWord * pOutLineData, const ULWord inNumPixels = 1920);

AJAExport void Make10BitWhiteLine (UWord * pOutLineData, const ULWord inNumPixels = 1920);

AJAExport bool Fill10BitYCbCrVideoFrame (void * pBaseVideoAddress,
                                         const NTV2Standard inStandard,
                                         const NTV2FrameBufferFormat inPixelFormat,
                                         const YCbCr10BitPixel inPixelColor,
                                         const NTV2VANCMode inVancMode = NTV2_VANCMODE_OFF);

AJAExport void Make8BitBlackLine(UByte* lineData,ULWord numPixels=1920,NTV2FrameBufferFormat=NTV2_FBF_8BIT_YCBCR);
AJAExport void Make8BitWhiteLine(UByte* lineData,ULWord numPixels=1920,NTV2FrameBufferFormat=NTV2_FBF_8BIT_YCBCR);
AJAExport void Make10BitLine(UWord* lineData, const UWord Y, const UWord Cb, const UWord Cr, const ULWord numPixels = 1920);
AJAExport void Make8BitLine(UByte* lineData, UByte Y , UByte Cb , UByte Cr,ULWord numPixels=1920,NTV2FrameBufferFormat=NTV2_FBF_8BIT_YCBCR);
AJAExport bool Fill8BitYCbCrVideoFrame (void * pBaseVideoAddress,  const NTV2Standard inStandard,  const NTV2FrameBufferFormat inFBF,
                                        const YCbCrPixel inPixelColor,  const NTV2VANCMode inVancMode = NTV2_VANCMODE_OFF);
AJAExport void Fill4k8BitYCbCrVideoFrame(PULWord _baseVideoAddress,
                                       NTV2FrameBufferFormat frameBufferFormat,
                                       YCbCrPixel color,
                                       bool vancEnabled=false,
                                       bool b4k=false,
                                       bool wideVANC=false);
AJAExport void CopyRGBAImageToFrame(ULWord* pSrcBuffer, ULWord srcHeight, ULWord srcWidth, 
                                    ULWord* pDstBuffer, ULWord dstHeight, ULWord dstWidth);

AJAExport bool  SetRasterLinesBlack (const NTV2PixelFormat  inPixelFormat,
                                        UByte *             pDstBuffer,
                                        const ULWord        inDstBytesPerLine,
                                        const UWord         inDstTotalLines);

AJAExport bool  SetRasterLinesWhite (const NTV2PixelFormat  inPixelFormat,
                                        UByte *             pDstBuffer,
                                        const ULWord        inDstBytesPerLine,
                                        const UWord         inDstTotalLines);

AJAExport bool  CopyRaster (const NTV2PixelFormat   inPixelFormat,
                            UByte *                 pDstBuffer,
                            const ULWord            inDstBytesPerLine,
                            const UWord             inDstTotalLines,
                            const UWord             inDstVertLineOffset,
                            const UWord             inDstHorzPixelOffset,
                            const UByte *           pSrcBuffer,
                            const ULWord            inSrcBytesPerLine,
                            const UWord             inSrcTotalLines,
                            const UWord             inSrcVertLineOffset,
                            const UWord             inSrcVertLinesToCopy,
                            const UWord             inSrcHorzPixelOffset,
                            const UWord             inSrcHorzPixelsToCopy);

AJAExport NTV2Standard GetNTV2StandardFromScanGeometry (const UByte inScanGeometry, const bool inIsProgressiveTransport);

AJAExport NTV2VideoFormat GetSupportedNTV2VideoFormatFromInputVideoFormat (const NTV2VideoFormat inVideoFormat);

AJAExport NTV2Standard GetNTV2StandardFromVideoFormat (const NTV2VideoFormat inVideoFormat);

AJAExport NTV2FrameGeometry GetNTV2FrameGeometryFromVideoFormat (const NTV2VideoFormat inVideoFormat);

#define GetHdmiV2StandardFromVideoFormat(__vf__)    ::GetNTV2StandardFromVideoFormat (__vf__)

AJAExport ULWord GetVideoActiveSize (const NTV2VideoFormat inVideoFormat,
                                    const NTV2FrameBufferFormat inFBFormat,
                                    const NTV2VANCMode inVancMode = NTV2_VANCMODE_OFF);


AJAExport ULWord GetVideoWriteSize (const NTV2VideoFormat inVideoFormat,
                                    const NTV2FrameBufferFormat inFBFormat,
                                    const NTV2VANCMode inVancMode = NTV2_VANCMODE_OFF);

AJAExport NTV2VideoFormat GetQuarterSizedVideoFormat (const NTV2VideoFormat inVideoFormat);
AJAExport NTV2VideoFormat GetQuadSizedVideoFormat (const NTV2VideoFormat inVideoFormat, const bool isSquareDivision = true);
AJAExport NTV2FrameGeometry GetQuarterSizedGeometry (const NTV2FrameGeometry inGeometry);
AJAExport NTV2FrameGeometry Get4xSizedGeometry (const NTV2FrameGeometry inGeometry);
AJAExport NTV2Standard GetQuarterSizedStandard (const NTV2Standard inGeometry);
AJAExport NTV2Standard Get4xSizedStandard (const NTV2Standard inGeometry, const bool bIs4k = false);

AJAExport double GetFramesPerSecond (const NTV2FrameRate inFrameRate);
inline double GetFrameTime (const NTV2FrameRate inFrameRate)    {return double(1.0) / GetFramesPerSecond(inFrameRate);}

AJAExport NTV2VideoFormat   GetFirstMatchingVideoFormat (const NTV2FrameRate inFrameRate,
                                                         const UWord inHeightLines,
                                                         const UWord inWidthPixels,
                                                         const bool inIsInterlaced,
                                                         const bool inIsLevelB,
                                                         const bool inIsPSF);

AJAExport bool GetFramesPerSecond (const NTV2FrameRate inFrameRate, ULWord & outFractionNumerator, ULWord & outFractionDenominator);

AJAExport NTV2_SHOULD_BE_DEPRECATED(bool NTV2DeviceCanDoFormat (const NTV2DeviceID inDevID, const NTV2FrameRate inFR, const NTV2FrameGeometry inFG, const NTV2Standard inStd));

AJAExport ULWord                GetAudioSamplesPerFrame (const NTV2FrameRate inFrameRate, const NTV2AudioRate inAudioRate, ULWord inCadenceFrame = 0, bool inIsSMPTE372Enabled = false);
AJAExport LWord64               GetTotalAudioSamplesFromFrameNbrZeroUpToFrameNbr (NTV2FrameRate frameRate, NTV2AudioRate audioRate, ULWord frameNbrNonInclusive);

AJAExport double                GetAudioSamplesPerSecond (const NTV2AudioRate inAudioRate); //  New in SDK 16.2

AJAExport NTV2_SHOULD_BE_DEPRECATED(ULWord GetVaricamRepeatCount (const NTV2FrameRate inSequenceRate, const NTV2FrameRate inPlayRate, const ULWord inCadenceFrame = 0));
AJAExport ULWord                GetScaleFromFrameRate (const NTV2FrameRate inFrameRate);
AJAExport NTV2FrameRate         GetFrameRateFromScale (long scale, long duration, NTV2FrameRate playFrameRate);
AJAExport NTV2FrameRate         GetNTV2FrameRateFromNumeratorDenominator (const ULWord inNumerator, const ULWord inDenominator);    //  New in SDK 16.0

AJAExport NTV2FrameRate         GetNTV2FrameRateFromVideoFormat (const NTV2VideoFormat inVideoFormat);

AJAExport NTV2FrameGeometry     GetNormalizedFrameGeometry (const NTV2FrameGeometry inFrameGeometry);

AJAExport NTV2FrameGeometry     GetVANCFrameGeometry (const NTV2FrameGeometry inFrameGeometry, const NTV2VANCMode inVancMode);

AJAExport NTV2FrameGeometry     GetGeometryFromFrameDimensions (const NTV2FrameSize & inFD);    //  New in SDK 16.0

AJAExport bool                  HasVANCGeometries (const NTV2FrameGeometry inFrameGeometry);

AJAExport NTV2GeometrySet       GetRelatedGeometries (const NTV2FrameGeometry inFrameGeometry);

AJAExport NTV2VANCMode          GetVANCModeForGeometry (const NTV2FrameGeometry inFrameGeometry);

AJAExport ULWord                GetNTV2FrameGeometryWidth (const NTV2FrameGeometry inFrameGeometry);

AJAExport ULWord                GetNTV2FrameGeometryHeight (const NTV2FrameGeometry inFrameGeometry);

AJAExport NTV2FrameGeometry     GetGeometryFromStandard (const NTV2Standard inStandard);

AJAExport NTV2Standard          GetStandardFromGeometry (const NTV2FrameGeometry inGeometry, const bool inIsProgressive = true);

AJAExport ULWord                GetDisplayWidth (const NTV2VideoFormat videoFormat);
AJAExport ULWord                GetDisplayHeight (const NTV2VideoFormat videoFormat);
AJAExport NTV2ConversionMode    GetConversionMode (const NTV2VideoFormat inFormat, const NTV2VideoFormat outFormat);
AJAExport NTV2VideoFormat       GetInputForConversionMode (const NTV2ConversionMode conversionMode);
AJAExport NTV2VideoFormat       GetOutputForConversionMode (const NTV2ConversionMode conversionMode);

AJAExport NTV2Channel           GetNTV2ChannelForIndex (const ULWord inIndex0);
AJAExport ULWord                GetIndexForNTV2Channel (const NTV2Channel inChannel);

AJAExport NTV2_SHOULD_BE_DEPRECATED(NTV2Crosspoint  GetNTV2CrosspointChannelForIndex (const ULWord inIndex0));
AJAExport NTV2_SHOULD_BE_DEPRECATED(ULWord          GetIndexForNTV2CrosspointChannel (const NTV2Crosspoint inChannel));
AJAExport NTV2_SHOULD_BE_DEPRECATED(NTV2Crosspoint  GetNTV2CrosspointInputForIndex (const ULWord inIndex0));
AJAExport NTV2_SHOULD_BE_DEPRECATED(ULWord          GetIndexForNTV2CrosspointInput (const NTV2Crosspoint inChannel));
AJAExport NTV2_SHOULD_BE_DEPRECATED(NTV2Crosspoint  GetNTV2CrosspointForIndex (const ULWord inIndex0));
AJAExport NTV2_SHOULD_BE_DEPRECATED(ULWord          GetIndexForNTV2Crosspoint (const NTV2Crosspoint inChannel));
AJAExport NTV2_SHOULD_BE_DEPRECATED(bool            IsNTV2CrosspointInput (const NTV2Crosspoint inChannel));
AJAExport NTV2_SHOULD_BE_DEPRECATED(bool            IsNTV2CrosspointOutput (const NTV2Crosspoint inChannel));
AJAExport NTV2_SHOULD_BE_DEPRECATED(std::string     NTV2CrosspointToString (const NTV2Crosspoint inChannel));
AJAExport NTV2_SHOULD_BE_DEPRECATED(NTV2Channel     NTV2CrosspointToNTV2Channel (const NTV2Crosspoint inCrosspointChannel));
AJAExport NTV2_SHOULD_BE_DEPRECATED(NTV2Crosspoint  NTV2ChannelToInputCrosspoint (const NTV2Channel inChannel));
AJAExport NTV2_SHOULD_BE_DEPRECATED(NTV2Crosspoint  NTV2ChannelToOutputCrosspoint (const NTV2Channel inChannel));
AJAExport NTV2_SHOULD_BE_DEPRECATED(NTV2InputSource GetNTV2HDMIInputSourceForIndex (const ULWord inIndex0));

AJAExport NTV2VideoFormat       GetTransportCompatibleFormat (const NTV2VideoFormat inFormat, const NTV2VideoFormat inTargetFormat);
AJAExport bool                  IsTransportCompatibleFormat (const NTV2VideoFormat inFormat1, const NTV2VideoFormat inFormat2);

AJAExport NTV2InputSource       GetNTV2InputSourceForIndex (const ULWord inIndex0, const NTV2IOKinds inKinds = NTV2_IOKINDS_SDI);

AJAExport NTV2IOKinds           GetNTV2InputSourceKind (const NTV2InputSource inSrc);
AJAExport ULWord                GetIndexForNTV2InputSource (const NTV2InputSource inValue);     //  0-based index

AJAExport INTERRUPT_ENUMS       NTV2ChannelToInputInterrupt (const NTV2Channel inChannel);

AJAExport INTERRUPT_ENUMS       NTV2ChannelToOutputInterrupt (const NTV2Channel inChannel);

AJAExport NTV2TCIndex           NTV2ChannelToTimecodeIndex (const NTV2Channel inChannel, const bool inEmbeddedLTC = false, const bool inIsF2 = false);

AJAExport NTV2TCIndexes         GetTCIndexesForSDIConnector (const NTV2Channel inSDIConnector);

AJAExport NTV2Channel           NTV2TimecodeIndexToChannel (const NTV2TCIndex inTCIndex);

AJAExport NTV2InputSource       NTV2TimecodeIndexToInputSource (const NTV2TCIndex inTCIndex);


#define GetTCIndexesForSDIInput         GetTCIndexesForSDIConnector
#define NTV2ChannelToCaptureCrosspoint  NTV2ChannelToInputCrosspoint
#define NTV2ChannelToIngestCrosspoint   NTV2ChannelToInputCrosspoint
#define NTV2ChannelToInputChannelSpec   NTV2ChannelToInputCrosspoint
#define NTV2ChannelToPlayoutCrosspoint  NTV2ChannelToOutputCrosspoint
#define NTV2ChannelToOutputChannelSpec  NTV2ChannelToOutputCrosspoint


AJAExport ULWord    NTV2FramesizeToByteCount (const NTV2Framesize inFrameSize);

AJAExport ULWord    NTV2AudioBufferSizeToByteCount (const NTV2AudioBufferSize inBufferSize);

AJAExport NTV2EmbeddedAudioInput NTV2ChannelToEmbeddedAudioInput (const NTV2Channel inChannel);

AJAExport NTV2EmbeddedAudioInput NTV2InputSourceToEmbeddedAudioInput (const NTV2InputSource inInputSource);

AJAExport NTV2AudioSource NTV2InputSourceToAudioSource (const NTV2InputSource inInputSource);

AJAExport NTV2Crosspoint NTV2InputSourceToChannelSpec (const NTV2InputSource inInputSource);

AJAExport NTV2Channel NTV2InputSourceToChannel (const NTV2InputSource inInputSource);

AJAExport NTV2ReferenceSource NTV2InputSourceToReferenceSource (const NTV2InputSource inInputSource);

AJAExport NTV2AudioSystem NTV2InputSourceToAudioSystem (const NTV2InputSource inInputSource);

AJAExport NTV2TimecodeIndex NTV2InputSourceToTimecodeIndex (const NTV2InputSource inInputSource, const bool inEmbeddedLTC = false);

AJAExport NTV2AudioSystem NTV2ChannelToAudioSystem (const NTV2Channel inChannel);

AJAExport NTV2InputSource NTV2ChannelToInputSource (const NTV2Channel inChannel, const NTV2IOKinds inKinds = NTV2_IOKINDS_SDI);

AJAExport NTV2Channel NTV2OutputDestinationToChannel (const NTV2OutputDestination inOutputDest);

AJAExport NTV2OutputDestination NTV2ChannelToOutputDestination (const NTV2Channel inChannel, const NTV2IOKinds inKinds = NTV2_IOKINDS_SDI);

AJAExport NTV2FrameRate GetFrameRateFamily (const NTV2FrameRate inFrameRate);

AJAExport bool IsMultiFormatCompatible (const NTV2FrameRate inFrameRate1, const NTV2FrameRate inFrameRate2);

AJAExport bool IsMultiFormatCompatible (const NTV2VideoFormat inFormat1, const NTV2VideoFormat inFormat2);

AJAExport bool IsPSF (const NTV2VideoFormat format);
AJAExport bool IsProgressivePicture (const NTV2VideoFormat format);
AJAExport bool IsProgressiveTransport (const NTV2VideoFormat format);
AJAExport bool IsProgressiveTransport (const NTV2Standard format);
AJAExport bool IsRGBFormat (const NTV2FrameBufferFormat format);
AJAExport bool IsYCbCrFormat (const NTV2FrameBufferFormat format);
AJAExport bool IsAlphaChannelFormat (const NTV2FrameBufferFormat format);
AJAExport bool Is2KFormat (const NTV2VideoFormat format);
AJAExport bool Is4KFormat (const NTV2VideoFormat format);
AJAExport bool Is8KFormat (const NTV2VideoFormat format);
AJAExport bool IsRaw (const NTV2FrameBufferFormat format);
AJAExport bool Is8BitFrameBufferFormat (const NTV2FrameBufferFormat fbFormat);
AJAExport bool IsVideoFormatA (const NTV2VideoFormat format);
AJAExport bool IsVideoFormatB (const NTV2VideoFormat format);
AJAExport bool IsVideoFormatJ2KSupported (const NTV2VideoFormat format);


AJAExport int  RecordCopyAudio (PULWord pAja, PULWord pSR, int iStartSample, int iNumBytes, int iChan0,
                               int iNumChans, bool bKeepAudio24Bits);

AJAExport bool AddAudioTone (   ULWord &        outNumBytesWritten,
                                NTV2Buffer &    inAudioBuffer,
                                ULWord &        inOutCurrentSample,
                                const ULWord    inNumSamples,
                                const double    inSampleRate,
                                const double    inAmplitude,
                                const double    inFrequency,
                                const ULWord    inNumBits,
                                const bool      inByteSwap,
                                const ULWord    inNumChannels);

AJAExport ULWord    AddAudioTone (  ULWord *        pAudioBuffer,
                                    ULWord &        inOutCurrentSample,
                                    const ULWord    inNumSamples,
                                    const double    inSampleRate,
                                    const double    inAmplitude,
                                    const double    inFrequency,
                                    const ULWord    inNumBits,
                                    const bool      inByteSwap,
                                    const ULWord    inNumChannels);

AJAExport ULWord    AddAudioTone (  ULWord *        pAudioBuffer,
                                    ULWord &        inOutCurrentSample,
                                    const ULWord    inNumSamples,
                                    const double    inSampleRate,
                                    const double *  pInAmplitudes,
                                    const double *  pInFrequencies,
                                    const ULWord    inNumBits,
                                    const bool      inByteSwap,
                                    const ULWord    inNumChannels);

AJAExport ULWord    AddAudioTone (  UWord *         pAudioBuffer,
                                    ULWord &        inOutCurrentSample,
                                    const ULWord    inNumSamples,
                                    const double    inSampleRate,
                                    const double    inAmplitude,
                                    const double    inFrequency,
                                    const ULWord    inNumBits,
                                    const bool      inByteSwap,
                                    const ULWord    inNumChannels);

AJAExport ULWord    AddAudioTestPattern (ULWord *       pAudioBuffer,
                                         ULWord &       inOutCurrentSample,
                                         const ULWord   inNumSamples,
                                         const ULWord   inModulus,
                                         const bool     inEndianConvert,
                                         const ULWord   inNumChannels);

AJAExport std::ostream & operator << (std::ostream & inOutStream, const NTV2FrameSize & inFrameDimensions);


typedef struct AJAExport NTV2SmpteLineNumber
{
    ULWord          smpteFirstActiveLine;   
    ULWord          smpteSecondActiveLine;  
    bool            firstFieldTop;          
private:
    NTV2Standard    mStandard;              

public:
    explicit        NTV2SmpteLineNumber (const NTV2Standard inStandard = NTV2_STANDARD_INVALID);

    inline bool     IsValid (void) const    {return NTV2_IS_VALID_STANDARD (mStandard) && smpteFirstActiveLine;}

    ULWord          GetFirstActiveLine (const NTV2FieldID inRasterFieldID = NTV2_FIELD0) const;

    ULWord          GetLastLine (const NTV2FieldID inRasterFieldID = NTV2_FIELD0) const;

    bool            operator == (const NTV2SmpteLineNumber & inRHS) const;

    std::ostream &  Print (std::ostream & inOutStream) const;

    std::string     PrintLineNumber (const ULWord inLineOffset = 0, const NTV2FieldID inRasterFieldID = NTV2_FIELD0) const;

private:
    explicit inline NTV2SmpteLineNumber (const ULWord inFirstActiveLine,
                                        const ULWord inSecondActiveLine,
                                        const bool inFirstFieldTop,
                                        const NTV2Standard inStandard)
                    :   smpteFirstActiveLine    (inFirstActiveLine),
                        smpteSecondActiveLine   (inSecondActiveLine),
                        firstFieldTop           (inFirstFieldTop),
                        mStandard               (inStandard)    {   }

} NTV2SmpteLineNumber;


AJAExport std::ostream & operator << (std::ostream & inOutStream, const NTV2SmpteLineNumber & inSmpteLineNumber);


inline NTV2SmpteLineNumber GetSmpteLineNumber (const NTV2Standard inStandard)   {return NTV2SmpteLineNumber (inStandard);}


class AJAExport NTV2ACFrameRange
{
    public:
        explicit inline NTV2ACFrameRange (const UWord inFrameCount = 0)
                        {
                            setCountOnly(inFrameCount);
                        }
        explicit inline NTV2ACFrameRange (const UWord inFirstFrame, const UWord inLastFrame)
                        {
                            setExactRange (inFirstFrame, inLastFrame);
                        }
        inline bool     isCountOnly (void) const    {return mIsCountOnly;}      
        inline bool     isFrameRange (void) const   {return !isCountOnly();}    
        inline UWord    count (void) const          {return isCountOnly() ? mFrameCount : 0;}   
        inline UWord    firstFrame (void) const     {return mFirstFrame;}       
        inline UWord    lastFrame (void) const      {return mLastFrame;}        
        inline          operator bool() const       {return valid();}           
        inline bool     valid (void) const
                        {
                            if (isCountOnly())
                                return count() > 0;
                            return lastFrame() >= firstFrame();
                        }
        inline NTV2ACFrameRange &   makeInvalid (void)
                        {
                            mIsCountOnly = true;
                            mFrameCount = mFirstFrame = mLastFrame = 0;
                            return *this;
                        }
        inline bool     setExactRange (const UWord inFirstFrame, const UWord inLastFrame)
                        {
                            mIsCountOnly = false;
                            mFrameCount = 0;
                            mFirstFrame = inFirstFrame;
                            mLastFrame = inLastFrame;
                            return valid();
                        }
        inline bool     setRangeWithCount (const UWord inCount, const UWord inFirstFrame)
                        {
                            mIsCountOnly = false;
                            mFrameCount = 0;
                            mFirstFrame = inFirstFrame;
                            mLastFrame = mFirstFrame + inCount - 1;
                            return valid();
                        }
        inline bool     setCountOnly (const UWord inCount)
                        {
                            mIsCountOnly    = true;
                            mFrameCount     = inCount;
                            mFirstFrame = mLastFrame = 0;
                            return valid();
                        }
        std::string     setFromString (const std::string & inStr);
        std::string     toString (const bool inNormalized = false) const;

    private:
        bool    mIsCountOnly;   
        UWord   mFrameCount;    
        UWord   mFirstFrame;    
        UWord   mLastFrame;     

};  //  NTV2ACFrameRange

inline std::ostream &   operator << (std::ostream & oss, const NTV2ACFrameRange & inObj)    {return oss << inObj.toString();}   


typedef std::vector <NTV2DeviceID>          NTV2DeviceIDList;           
typedef NTV2DeviceIDList::iterator          NTV2DeviceIDListIter;       
typedef NTV2DeviceIDList::const_iterator    NTV2DeviceIDListConstIter;  

AJAExport std::ostream &    operator << (std::ostream & inOutStr, const NTV2DeviceIDList & inSet);      


typedef std::set <NTV2DeviceID>         NTV2DeviceIDSet;            
typedef NTV2DeviceIDSet::iterator       NTV2DeviceIDSetIter;        
typedef NTV2DeviceIDSet::const_iterator NTV2DeviceIDSetConstIter;   

AJAExport NTV2DeviceIDSet NTV2GetSupportedDevices (const NTV2DeviceKinds inKinds = NTV2_DEVICEKIND_ALL);

AJAExport std::ostream &    operator << (std::ostream & inOutStr, const NTV2DeviceIDSet & inSet);       

AJAExport UWord NTV2GetSDKVersionComponent (const int inVersionComponent = 0);  //  New in SDK 16.1


typedef std::vector <NTV2OutputCrosspointID>        NTV2OutputCrosspointIDs;            
typedef NTV2OutputCrosspointIDs::iterator           NTV2OutputCrosspointIDsIter;        
typedef NTV2OutputCrosspointIDs::const_iterator     NTV2OutputCrosspointIDsConstIter;   

AJAExport std::ostream &    operator << (std::ostream & inOutStr, const NTV2OutputCrosspointIDs & inList);  


typedef std::vector <NTV2InputCrosspointID>         NTV2InputCrosspointIDs;             
typedef NTV2InputCrosspointIDs::iterator            NTV2InputCrosspointIDsIter;         
typedef NTV2InputCrosspointIDs::const_iterator      NTV2InputCrosspointIDsConstIter;    

AJAExport std::ostream &    operator << (std::ostream & inOutStr, const NTV2OutputCrosspointIDs & inList);  


AJAExport std::string NTV2DeviceIDToString              (const NTV2DeviceID             inValue,    const bool inForRetailDisplay = false); //  New in SDK 12.0
AJAExport std::string NTV2VideoFormatToString           (const NTV2VideoFormat          inValue,    const bool inUseFrameRate = false);     //  New in SDK 12.0
AJAExport std::string NTV2StandardToString              (const NTV2Standard             inValue,    const bool inForRetailDisplay = false); //  New in SDK 12.0
AJAExport std::string NTV2FrameBufferFormatToString     (const NTV2FrameBufferFormat    inValue,    const bool inForRetailDisplay = false); //  New in SDK 12.0
AJAExport std::string NTV2FrameGeometryToString         (const NTV2FrameGeometry        inValue,    const bool inForRetailDisplay = false); //  New in SDK 12.0
AJAExport std::string NTV2FrameRateToString             (const NTV2FrameRate            inValue,    const bool inForRetailDisplay = false); //  New in SDK 12.0
AJAExport std::string NTV2InputSourceToString           (const NTV2InputSource          inValue,    const bool inForRetailDisplay = false); //  New in SDK 12.0
AJAExport std::string NTV2OutputDestinationToString     (const NTV2OutputDestination    inValue,    const bool inForRetailDisplay = false); //  New in SDK 12.0
AJAExport std::string NTV2ReferenceSourceToString       (const NTV2ReferenceSource      inValue,    const bool inForRetailDisplay = false); //  New in SDK 12.0
AJAExport std::string NTV2RegisterWriteModeToString     (const NTV2RegisterWriteMode    inValue,    const bool inForRetailDisplay = false); //  New in SDK 12.0
AJAExport std::string NTV2InterruptEnumToString         (const INTERRUPT_ENUMS          inInterruptEnumValue);
AJAExport std::string NTV2IpErrorEnumToString           (const NTV2IpError              inIpErrorEnumValue);
AJAExport std::string NTV2ChannelToString               (const NTV2Channel              inValue,    const bool inForRetailDisplay = false); //  New in SDK 12.0
AJAExport std::string NTV2AudioSystemToString           (const NTV2AudioSystem          inValue,    const bool inCompactDisplay = false);   //  New in SDK 12.0
AJAExport std::string NTV2AudioRateToString             (const NTV2AudioRate            inValue,    const bool inForRetailDisplay = false); //  New in SDK 12.0
AJAExport std::string NTV2AudioBufferSizeToString       (const NTV2AudioBufferSize      inValue,    const bool inForRetailDisplay = false); //  New in SDK 12.0
AJAExport std::string NTV2AudioLoopBackToString         (const NTV2AudioLoopBack        inValue,    const bool inForRetailDisplay = false); //  New in SDK 12.0
AJAExport std::string NTV2EmbeddedAudioClockToString    (const NTV2EmbeddedAudioClock   inValue,    const bool inForRetailDisplay = false); //  New in SDK 12.0
AJAExport std::string NTV2GetBitfileName                (const NTV2DeviceID             inValue);
AJAExport bool        NTV2IsCompatibleBitfileName       (const std::string & inBitfileName, const NTV2DeviceID inDeviceID);
AJAExport NTV2DeviceID NTV2GetDeviceIDFromBitfileName   (const std::string & inBitfileName);
AJAExport std::string NTV2GetFirmwareFolderPath         (const bool inAddTrailingPathDelim = false);
AJAExport std::string NTV2GetPluginsFolderPath          (const bool inAddTrailingPathDelim = false);    //  New in SDK 18.0
AJAExport std::string NTV2GetVDevFolderPath             (const bool inAddTrailingPathDelim = false);    //  New in SDK 18.0
AJAExport std::ostream & operator << (std::ostream & inOutStream, const RP188_STRUCT & inObj);
AJAExport std::string NTV2GetVersionString              (const bool inDetailed = false);
AJAExport std::string NTV2RegisterNumberToString        (const NTV2RegisterNumber       inValue);   //  New in SDK 12.0
AJAExport std::string AutoCircVidProcModeToString       (const AutoCircVidProcMode      inValue,    const bool inCompactDisplay = false);   //  New in SDK 12.0
AJAExport std::string NTV2ColorCorrectionModeToString   (const NTV2ColorCorrectionMode  inValue,    const bool inCompactDisplay = false);   //  New in SDK 12.0
AJAExport std::string NTV2InputCrosspointIDToString     (const NTV2InputCrosspointID    inValue,    const bool inForRetailDisplay = false); //  New in SDK 12.0
AJAExport std::string NTV2OutputCrosspointIDToString    (const NTV2OutputCrosspointID   inValue,    const bool inForRetailDisplay = false); //  New in SDK 12.0
AJAExport std::string NTV2WidgetIDToString              (const NTV2WidgetID             inValue,    const bool inCompactDisplay = false);   //  New in SDK 12.0
AJAExport std::string NTV2WidgetTypeToString            (const NTV2WidgetType           inValue,    const bool inCompactDisplay = false);   //  New in SDK 12.0
AJAExport std::string NTV2TaskModeToString              (const NTV2TaskMode             inValue,    const bool inCompactDisplay = false);   //  New in SDK 12.0
AJAExport std::string NTV2RegNumSetToString             (const NTV2RegisterNumberSet &  inValue);   //  New in SDK 12.0
AJAExport std::string NTV2TCIndexToString               (const NTV2TCIndex              inValue,    const bool inCompactDisplay = false);   //  New in SDK 12.0
AJAExport std::string NTV2AudioChannelPairToString      (const NTV2AudioChannelPair     inValue,    const bool inCompactDisplay = false);   //  New in SDK 12.0
AJAExport std::string NTV2AudioChannelQuadToString      (const NTV2Audio4ChannelSelect  inValue,    const bool inCompactDisplay = false);   //  New in SDK 12.0
AJAExport std::string NTV2AudioChannelOctetToString     (const NTV2Audio8ChannelSelect  inValue,    const bool inCompactDisplay = false);   //  New in SDK 12.0
AJAExport std::string NTV2FramesizeToString             (const NTV2Framesize            inValue,    const bool inCompactDisplay = false);   //  New in SDK 12.0
AJAExport std::string NTV2ModeToString                  (const NTV2Mode                 inValue,    const bool inCompactDisplay = false);   //  New in SDK 12.0
AJAExport std::string NTV2VANCModeToString              (const NTV2VANCMode             inValue,    const bool inCompactDisplay = false);   //  New in SDK 12.0
AJAExport std::string NTV2MixerKeyerModeToString        (const NTV2MixerKeyerMode       inValue,    const bool inCompactDisplay = false);   //  New in SDK 12.0
AJAExport std::string NTV2MixerInputControlToString     (const NTV2MixerKeyerInputControl inValue,  const bool inCompactDisplay = false);   //  New in SDK 12.0
AJAExport std::string NTV2VideoLimitingToString         (const NTV2VideoLimiting        inValue,    const bool inCompactDisplay = false);   //  New in SDK 12.0
AJAExport std::string NTV2EmbeddedAudioInputToString    (const NTV2EmbeddedAudioInput   inValue,    const bool inCompactDisplay = false);   //  New in SDK 13.0
AJAExport std::string NTV2AudioSourceToString           (const NTV2AudioSource          inValue,    const bool inCompactDisplay = false);   //  New in SDK 13.0
AJAExport std::string NTV2BreakoutTypeToString          (const NTV2BreakoutType         inValue,    const bool inCompactDisplay = false);   //  New in SDK 15.5
AJAExport std::string NTV2AncDataRgnToStr               (const NTV2AncDataRgn           inValue,    const bool inCompactDisplay = false);   //  New in SDK 15.5
AJAExport std::string NTV2UpConvertModeToString         (const NTV2UpConvertMode        inValue,    const bool inCompactDisplay = false);   //  New in SDK 16.1
AJAExport std::string NTV2DownConvertModeToString       (const NTV2DownConvertMode      inValue,    const bool inCompactDisplay = false);   //  New in SDK 16.1
AJAExport std::string NTV2IsoConvertModeToString        (const NTV2IsoConvertMode       inValue,    const bool inCompactDisplay = false);   //  New in SDK 16.1
AJAExport std::string NTV2ScanMethodToString            (const NTV2ScanMethod           inValue,    const bool inCompactDisplay = false);   //  New in SDK 17.5

AJAExport std::string NTV2HDMIBitDepthToString          (const NTV2HDMIBitDepth         inValue,    const bool inCompactDisplay = false);   //  New in SDK 16.1
AJAExport std::string NTV2HDMIAudioChannelsToString     (const NTV2HDMIAudioChannels    inValue,    const bool inCompactDisplay = false);   //  New in SDK 16.1
AJAExport std::string NTV2HDMIProtocolToString          (const NTV2HDMIProtocol         inValue,    const bool inCompactDisplay = false);   //  New in SDK 16.1
AJAExport std::string NTV2HDMIRangeToString             (const NTV2HDMIRange            inValue,    const bool inCompactDisplay = false);   //  New in SDK 16.1
AJAExport std::string NTV2HDMIColorSpaceToString        (const NTV2HDMIColorSpace       inValue,    const bool inCompactDisplay = false);   //  New in SDK 16.1
AJAExport std::string NTV2AudioFormatToString           (const NTV2AudioFormat          inValue,    const bool inCompactDisplay = false);   //  New in SDK 16.1

AJAExport std::string NTV2BitfileTypeToString           (const NTV2BitfileType          inValue,    const bool inCompactDisplay = false);   //  New in SDK 16.2
AJAExport std::string NTV2DieTempScaleToString          (const NTV2DieTempScale         inValue,    const bool inUseUTF8 = false);          //  New in SDK 17.6

AJAExport NTV2RegisterReads FromRegNumSet   (const NTV2RegNumSet &      inRegNumSet);
AJAExport NTV2RegNumSet     ToRegNumSet     (const NTV2RegisterReads &  inRegReads);
AJAExport bool              GetRegNumChanges (const NTV2RegNumSet & inBefore, const NTV2RegNumSet & inAfter, NTV2RegNumSet & outGone, NTV2RegNumSet & outSame, NTV2RegNumSet & outAdded);
AJAExport bool              GetChangedRegisters (const NTV2RegisterReads & inBefore, const NTV2RegisterReads & inAfter, NTV2RegNumSet & outChanged);    //  New in SDK 16.0

AJAExport std::string       PercentEncode (const std::string & inStr);  
AJAExport std::string       PercentDecode (const std::string & inStr);  
AJAExport bool              StringToSerialNum64 (const std::string & inSerNumStr, uint64_t & outSerNum);    //  New in SDK 16.3
AJAExport std::string       SerialNum64ToString (const uint64_t & inSerNum);    //  New in SDK 16.3

#if !defined(NTV2_DEPRECATE_16_1)
    inline NTV2_DEPRECATED_16_1(std::string NTV2AudioMonitorSelectToString (const NTV2AudioMonitorSelect v, const bool b = false)) {return NTV2AudioChannelPairToString(v, b);} 
#endif  //  !defined(NTV2_DEPRECATE_16_1)
#if !defined(NTV2_DEPRECATE_17_6)
    #define NTV2M31VideoPresetToString(...)     std::string()   //  deprecated  New in SDK 12.0, removed in SDK 17.6
    AJAExport NTV2_DEPRECATED_17_6(bool convertHDRFloatToRegisterValues (const HDRFloatValues & inFVals, HDRRegValues & outRegVals));       
    AJAExport NTV2_DEPRECATED_17_6(bool convertHDRRegisterToFloatValues (const HDRRegValues & inRegVals, HDRFloatValues & outFloatVals));   
    AJAExport NTV2_DEPRECATED_17_6(void setHDRDefaultsForBT2020 (HDRRegValues & outRegVals));   
    AJAExport NTV2_DEPRECATED_17_6(void setHDRDefaultsForDCIP3 (HDRRegValues & outRegVals));    
    #if defined(AJAMac)
    AJAExport NTV2_DEPRECATED_17_6(bool GetInstalledMacDriverVersion (UWord & outMaj, UWord & outMin, UWord & outPt, UWord & outBld, UWord & outType)); 
    #endif  //  AJAMac
#endif  //  !defined(NTV2_DEPRECATE_17_6)
#if !defined(NTV2_DEPRECATE_18_0)
    #define NTV2CrosspointIDToString    NTV2OutputCrosspointIDToString  
#endif// !defined(NTV2_DEPRECATE_18_0)

#endif  //  NTV2UTILS_H