AJA NTV2 SDK  17.0.1.1246
NTV2 SDK 17.0.1.1246
NTV2Buffer Class Reference

A generic user-space buffer object that has an address and a length. Used most often to share an arbitrary-sized chunk of host memory with the NTV2 kernel driver through a CNTV2DriverInterface::NTV2Message call. More...

#include <ntv2publicinterface.h>

Public Member Functions

bool RPCEncode (NTV2_RPC_BLOB_TYPE &outBlob)
 
bool RPCDecode (const NTV2_RPC_BLOB_TYPE &inBlob, size_t &inOutIndex)
 
Construction & Destruction
 NTV2Buffer (const void *pInUserPointer, const size_t inByteCount)
 Constructs me from a client-supplied address and size. More...
 
 NTV2Buffer (const size_t inByteCount=0)
 Constructs me from a client-specified byte count. In this case, I assume full responsibility for automatically freeing the memory I allocate. More...
 
 NTV2Buffer (const NTV2Buffer &inObj)
 Constructs me from another NTV2Buffer instance. More...
 
 ~NTV2Buffer ()
 My destructor. If I'm responsible for the memory, I free it here. More...
 
Inquiry
void * GetHostPointer (void) const
 
ULWord64 GetRawHostPointer (void) const
 
ULWord GetByteCount (void) const
 
bool IsAllocatedBySDK (void) const
 
bool IsProvidedByClient (void) const
 
bool IsPageAligned (void) const
 
bool IsNULL (void) const
 
 operator bool () const
 
 operator size_t () const
 
void * GetHostAddress (const ULWord inByteOffset, const bool inFromEnd=false) const
 
template<typename T >
bool Find (const T &inValue, int &inOutIndex) const
 Searches me for the given scalar value of type T starting at a given index position. More...
 
ULWordSetFindAll (ULWordSet &outOffsets, const NTV2Buffer &inValue) const
 
bool IsContentEqual (const NTV2Buffer &inBuffer, const ULWord inByteOffset=0, const ULWord inByteCount=0xFFFFFFFF) const
 
bool NextDifference (const NTV2Buffer &inBuffer, ULWord &byteOffset) const
 Answers with the byte offset to the first or next difference. More...
 
bool GetRingChangedByteRange (const NTV2Buffer &inBuffer, ULWord &outByteOffsetFirst, ULWord &outByteOffsetLast) const
 Assuming my contents and the contents of the given buffer comprise ring buffers that periodically get overwritten in contiguous variable-length chunks, answers with the contiguous byte range that differs between the two. More...
 
Changing
bool Allocate (const size_t inByteCount, const bool inPageAligned=false)
 Allocates (or re-allocates) my user-space storage using the given byte count. I assume full responsibility for any memory that I allocate. More...
 
bool Deallocate (void)
 Deallocates my user-space storage (if I own it – i.e. from a prior call to Allocate). More...
 
template<typename T >
bool Fill (const T &inValue)
 Fills me with the given scalar value. More...
 
template<typename T >
bool Fill (const T &inValue, const NTV2SegmentedXferInfo &inXferInfo)
 Fills a portion of me with the given scalar value. More...
 
NTV2Bufferoperator= (const NTV2Buffer &inRHS)
 Assigns me from another NTV2Buffer instance. More...
 
bool Set (const void *pInUserPointer, const size_t inByteCount)
 Sets (or resets) me from a client-supplied address and size. More...
 
bool SetAndFill (const void *pInUserPointer, const size_t inByteCount, const UByte inValue)
 Sets (or resets) me from a client-supplied address and size. More...
 
bool SetFrom (const NTV2Buffer &inBuffer)
 Replaces my contents from the given memory buffer without resizing me. More...
 
bool CopyFrom (const void *pInSrcBuffer, const ULWord inByteCount)
 Replaces my contents from the given memory buffer, resizing me to the new byte count. More...
 
bool CopyFrom (const NTV2Buffer &inSrcBuffer, const ULWord inSrcByteOffset, const ULWord inDstByteOffset, const ULWord inByteCount)
 Copies bytes from the given memory buffer into me. More...
 
bool CopyFrom (const NTV2Buffer &inSrcBuffer, const NTV2SegmentedXferInfo &inXferInfo)
 Copies data segments from a given buffer into me. More...
 
bool SwapWith (NTV2Buffer &inBuffer)
 Swaps my underlying buffer with another's. More...
 
bool ByteSwap64 (void)
 Byte-swaps my contents 64-bits at a time. More...
 
bool ByteSwap32 (void)
 Byte-swaps my contents 32-bits at a time. More...
 
bool ByteSwap16 (void)
 Byte-swaps my contents 16-bits at a time. More...
 
Debugging/Printing
std::ostream & Print (std::ostream &inOutStream) const
 Prints a human-readable representation of me into the given output stream. More...
 
std::string AsString (UWord inDumpMaxBytes=0) const
 
std::ostream & Dump (std::ostream &inOutputStream=std::cout, const size_t inStartByteOffset=0, const size_t inByteCount=0, const size_t inRadix=16, const size_t inBytesPerGroup=4, const size_t inGroupsPerLine=8, const size_t inAddressRadix=0, const bool inShowAscii=false, const size_t inAddrOffset=0) const
 Dumps me in hex/octal/decimal, with/without Ascii, to the given output stream. More...
 
std::string & Dump (std::string &inOutputString, const size_t inStartByteOffset=0, const size_t inByteCount=0, const size_t inRadix=16, const size_t inBytesPerGroup=4, const size_t inGroupsPerLine=8, const size_t inAddressRadix=0, const bool inShowAscii=false, const size_t inAddrOffset=0) const
 Dumps me in hex/octal/decimal, with/without Ascii, into the given string. More...
 
Data Access
template<typename T >
 operator const T * () const
 
template<typename T >
 operator T* () const
 
NTV2BufferSegment (NTV2Buffer &outPtr, const ULWord inByteOffset, const ULWord inByteCount) const
 Resets an NTV2Buffer instance to reference a contiguous segment (portion) of my memory buffer. More...
 
uint8_t U8 (const int inIndex) const
 
uint8_t & U8 (const int inIndex)
 
int8_t I8 (const int inIndex) const
 
int8_t & I8 (const int inIndex)
 
uint16_t U16 (const int inIndex) const
 
uint16_t & U16 (const int inIndex)
 
int16_t I16 (const int inIndex) const
 
int16_t & I16 (const int inIndex)
 
uint32_t U32 (const int inIndex) const
 
uint32_t & U32 (const int inIndex)
 
int32_t I32 (const int inIndex) const
 
int32_t & I32 (const int inIndex)
 
uint64_t U64 (const int inIndex) const
 
uint64_t & U64 (const int inIndex)
 
int64_t I64 (const int inIndex) const
 
int64_t & I64 (const int inIndex)
 
float FL (const int inIndex) const
 
float & FL (const int inIndex)
 
double DBL (const int inIndex) const
 
double & DBL (const int inIndex)
 
Vector Conversion
bool GetU64s (ULWord64Sequence &outU64s, const size_t inU64Offset=0, const size_t inMaxSize=16, const bool inByteSwap=false) const
 Answers with my contents as a vector of unsigned 16-bit values. More...
 
ULWord64Sequence GetU64s (const size_t inU64Offset=0, const size_t inMaxSize=16, const bool inByteSwap=false) const
 
bool GetU32s (ULWordSequence &outU32s, const size_t inU32Offset=0, const size_t inMaxSize=32, const bool inByteSwap=false) const
 Answers with my contents as a vector of unsigned 32-bit values. More...
 
ULWordSequence GetU32s (const size_t inU32Offset=0, const size_t inMaxSize=32, const bool inByteSwap=false) const
 
bool GetU16s (UWordSequence &outU16s, const size_t inU16Offset=0, const size_t inMaxSize=64, const bool inByteSwap=false) const
 Answers with my contents as a vector of unsigned 16-bit values. More...
 
UWordSequence GetU16s (const size_t inU16Offset=0, const size_t inMaxSize=64, const bool inByteSwap=false) const
 
bool GetU8s (UByteSequence &outU8s, const size_t inU8Offset=0, const size_t inMaxSize=128) const
 Answers with my contents as a vector of unsigned 8-bit values. More...
 
UByteSequence GetU8s (const size_t inU8Offset=0, const size_t inMaxSize=128) const
 
bool AppendU8s (UByteSequence &outU8s) const
 Appends my contents to an existing UByteSequence. More...
 
bool GetString (std::string &outString, const size_t inU8Offset=0, const size_t inMaxSize=128) const
 Answers with my contents as a character string. More...
 
std::string GetString (const size_t inU8Offset=0, const size_t inMaxSize=128) const
 
bool PutU64s (const ULWord64Sequence &inU64s, const size_t inU64Offset=0, const bool inByteSwap=false)
 Copies a vector of unsigned 64-bit values into me. More...
 
bool PutU32s (const ULWordSequence &inU32s, const size_t inU32Offset=0, const bool inByteSwap=false)
 Copies a vector of unsigned 32-bit values into me. More...
 
bool PutU16s (const UWordSequence &inU16s, const size_t inU16Offset=0, const bool inByteSwap=false)
 Copies a vector of unsigned 16-bit values into me. More...
 
bool PutU8s (const UByteSequence &inU8s, const size_t inU8Offset=0)
 Copies a vector of unsigned 8-bit values into me. More...
 

Static Public Member Functions

Default Page Size
static size_t DefaultPageSize (void)
 
static bool SetDefaultPageSize (const size_t inNewSize)
 Changes the default page size for use in future page-aligned allocations. More...
 
static size_t HostPageSize (void)
 

Detailed Description

A generic user-space buffer object that has an address and a length. Used most often to share an arbitrary-sized chunk of host memory with the NTV2 kernel driver through a CNTV2DriverInterface::NTV2Message call.

  • For a static or global buffer, simply construct from the variable:
    static ULWord pFoo [1000];
    {
    NTV2Buffer foo (pFoo, sizeof (pFoo));
    . . .
    } // When foo goes out of scope, it won't try to free pFoo
  • For stack-based buffers, simply construct from the variable:
    {
    ULWord pFoo [100];
    NTV2Buffer foo (pFoo, sizeof (pFoo));
    . . .
    } // No need to do anything, as both foo and pFoo are automatically freed when they go out of scope
  • For a buffer you allocate and free yourself:
    NTV2Buffer foo (new Bar [1], sizeof (Bar));
    . . .
    delete [] (Bar*) foo.GetHostPointer (); // You must free the memory yourself
  • For a 2K-byte buffer that's allocated and freed automatically by the SDK:
    {
    NTV2Buffer foo (2048);
    ::memset (foo.GetHostPointer(), 0, foo.GetByteCount());
    . . .
    } // The memory is freed automatically when foo goes out of scope
    Note
    This struct uses a constructor to properly initialize itself. Do not use memset or bzero to initialize or "clear" it.

Definition at line 5967 of file ntv2publicinterface.h.

Constructor & Destructor Documentation

◆ NTV2Buffer() [1/3]

NTV2Buffer::NTV2Buffer ( const void *  pInUserPointer,
const size_t  inByteCount 
)
explicit

Constructs me from a client-supplied address and size.

Parameters
[in]pInUserPointerSpecifies the user-space virtual memory address. The client is entirely responsible for it. Ignored if inByteCount is zero.
[in]inByteCountSpecifies the byte count. Ignored if pInUserPointer is NULL.

Definition at line 1430 of file ntv2publicinterface.cpp.

◆ NTV2Buffer() [2/3]

NTV2Buffer::NTV2Buffer ( const size_t  inByteCount = 0)

Constructs me from a client-specified byte count. In this case, I assume full responsibility for automatically freeing the memory I allocate.

Parameters
[in]inByteCountOptionally specifies the size of the allocated buffer, in bytes. Defaults to zero. If non-zero, causes Allocate to be called, and if successful, automatically zeroes the buffer. If zero (the default), I don't allocate anything, and my host pointer will be NULL.

Definition at line 1445 of file ntv2publicinterface.cpp.

◆ NTV2Buffer() [3/3]

NTV2Buffer::NTV2Buffer ( const NTV2Buffer inObj)
explicit

Constructs me from another NTV2Buffer instance.

Parameters
[in]inObjNTV2Buffer instance to "deep" copy into me.

Definition at line 1463 of file ntv2publicinterface.cpp.

◆ ~NTV2Buffer()

NTV2Buffer::~NTV2Buffer ( )

My destructor. If I'm responsible for the memory, I free it here.

Definition at line 1496 of file ntv2publicinterface.cpp.

Member Function Documentation

◆ Allocate()

bool NTV2Buffer::Allocate ( const size_t  inByteCount,
const bool  inPageAligned = false 
)

Allocates (or re-allocates) my user-space storage using the given byte count. I assume full responsibility for any memory that I allocate.

Parameters
[in]inByteCountSpecifies the number of bytes to allocate. Specifying zero is the same as calling Set(NULL, 0).
[in]inPageAlignedOptionally specifies page alignment. If true, allocates a page-aligned block. If false (default), uses operator new.
Returns
True if successful; otherwise false.
Note
Any memory that I was referencing prior to this call that I was responsible for will automatically be freed.

Definition at line 1554 of file ntv2publicinterface.cpp.

◆ AppendU8s()

bool NTV2Buffer::AppendU8s ( UByteSequence outU8s) const

Appends my contents to an existing UByteSequence.

Parameters
[out]outU8sThe vector to be appended to.
Returns
True if successful; otherwise false.

Definition at line 584 of file ntv2publicinterface.cpp.

◆ AsString()

string NTV2Buffer::AsString ( UWord  inDumpMaxBytes = 0) const
Parameters
inDumpMaxBytesIf non-zero, includes a hex dump of my contents up to the number of specified bytes (64 maximum).
Returns
A string containing a human-readable representation of me.

Definition at line 282 of file ntv2publicinterface.cpp.

◆ ByteSwap16()

bool NTV2Buffer::ByteSwap16 ( void  )

Byte-swaps my contents 16-bits at a time.

Returns
True if successful; otherwise false.
Note
If my size (in bytes) is not evenly divisible by 2, the very last byte won't get swapped.

Definition at line 1526 of file ntv2publicinterface.cpp.

◆ ByteSwap32()

bool NTV2Buffer::ByteSwap32 ( void  )

Byte-swaps my contents 32-bits at a time.

Returns
True if successful; otherwise false.
Note
If my size (in bytes) is not evenly divisible by 4, the very last byte(s) won't get swapped.

Definition at line 1514 of file ntv2publicinterface.cpp.

◆ ByteSwap64()

bool NTV2Buffer::ByteSwap64 ( void  )

Byte-swaps my contents 64-bits at a time.

Returns
True if successful; otherwise false.
Note
If my size (in bytes) is not evenly divisible by 8, the very last byte(s) won't get swapped.

Definition at line 1502 of file ntv2publicinterface.cpp.

◆ CopyFrom() [1/3]

bool NTV2Buffer::CopyFrom ( const NTV2Buffer inSrcBuffer,
const NTV2SegmentedXferInfo inXferInfo 
)

Copies data segments from a given buffer into me.

Parameters
[in]inSrcBufferSpecifies the source memory buffer to be copied into me.
[in]inXferInfoThe segmented transfer info.
Returns
True if successful; otherwise false.
Note
Offsets and lengths are checked. The function will return false for any overflow or underflow.

Definition at line 1676 of file ntv2publicinterface.cpp.

◆ CopyFrom() [2/3]

bool NTV2Buffer::CopyFrom ( const NTV2Buffer inSrcBuffer,
const ULWord  inSrcByteOffset,
const ULWord  inDstByteOffset,
const ULWord  inByteCount 
)

Copies bytes from the given memory buffer into me.

Parameters
[in]inSrcBufferSpecifies the source memory buffer to be copied into me.
[in]inSrcByteOffsetSpecifies the offset, in bytes, at which reading will commence in the source buffer.
[in]inDstByteOffsetSpecifies the offset, in bytes, at which writing will commence in me.
[in]inByteCountSpecifies the total number of bytes to copy.
Returns
True if successful; otherwise false.
Note
The offsets and byte counts are checked against the existing sizes of the two buffers. The function will return false for any overflow.

Definition at line 1655 of file ntv2publicinterface.cpp.

◆ CopyFrom() [3/3]

bool NTV2Buffer::CopyFrom ( const void *  pInSrcBuffer,
const ULWord  inByteCount 
)

Replaces my contents from the given memory buffer, resizing me to the new byte count.

Parameters
[in]pInSrcBufferSpecifies the memory buffer whose contents are to be copied into my own.
[in]inByteCountSpecifies the number of bytes to be copied.
Returns
True if successful; otherwise false.

Definition at line 1642 of file ntv2publicinterface.cpp.

◆ DBL() [1/2]

double& NTV2Buffer::DBL ( const int  inIndex)
inline

Definition at line 6478 of file ntv2publicinterface.h.

◆ DBL() [2/2]

double NTV2Buffer::DBL ( const int  inIndex) const
inline

Definition at line 6477 of file ntv2publicinterface.h.

◆ Deallocate()

bool NTV2Buffer::Deallocate ( void  )

Deallocates my user-space storage (if I own it – i.e. from a prior call to Allocate).

Returns
True if successful; otherwise false.

Definition at line 1588 of file ntv2publicinterface.cpp.

◆ DefaultPageSize()

size_t NTV2Buffer::DefaultPageSize ( void  )
static
Returns
Default page size, in bytes.

Definition at line 1905 of file ntv2publicinterface.cpp.

◆ Dump() [1/2]

std::ostream& NTV2Buffer::Dump ( std::ostream &  inOutputStream = std::cout,
const size_t  inStartByteOffset = 0,
const size_t  inByteCount = 0,
const size_t  inRadix = 16,
const size_t  inBytesPerGroup = 4,
const size_t  inGroupsPerLine = 8,
const size_t  inAddressRadix = 0,
const bool  inShowAscii = false,
const size_t  inAddrOffset = 0 
) const

Dumps me in hex/octal/decimal, with/without Ascii, to the given output stream.

Parameters
inOutputStreamOutput stream that will receive the dump. Defaults to std::cout.
inStartByteOffsetThe starting offset, in bytes, where the dump will start.
inByteCountThe number of bytes to be dumped. If zero, all bytes will be dumped.
inRadixSpecifies the radix of the dumped memory values. 16=hex, 10=decimal, 8=octal, 2=binary – all others disallowed.
inBytesPerGroupNumber of bytes to dump per contiguous group of numbers. Defaults to 4.
inGroupsPerLineNumber of contiguous groups of numbers to dump per output line. If zero, no grouping is done, and address & ASCII display is suppressed. Defaults to 8.
inAddressRadixSpecifies the radix of the address column. 0=omit, 2=binary, 8=octal, 10=decimal, 16=hex – all others disallowed. Defaults to 0.
inShowAsciiIf True, show ASCII characters; otherwise no ASCII characters. Overridden to false if inGroupsPerLine is zero. Defaults to false.
inAddrOffsetSpecifies a value to be added to the addresses that appear in the dump. Ignored if inGroupsPerLine is zero.
Returns
A non-constant reference to the output stream that received the dump.

◆ Dump() [2/2]

std::string& NTV2Buffer::Dump ( std::string &  inOutputString,
const size_t  inStartByteOffset = 0,
const size_t  inByteCount = 0,
const size_t  inRadix = 16,
const size_t  inBytesPerGroup = 4,
const size_t  inGroupsPerLine = 8,
const size_t  inAddressRadix = 0,
const bool  inShowAscii = false,
const size_t  inAddrOffset = 0 
) const

Dumps me in hex/octal/decimal, with/without Ascii, into the given string.

Parameters
inOutputStringString that will receive the dump. Appends the dump to the end of whatever is already in the string.
inStartByteOffsetThe starting offset, in bytes, where the dump will start.
inByteCountThe number of bytes to be dumped. If zero, all bytes will be dumped.
inRadixSpecifies the radix of the dumped memory values. 16=hex, 10=decimal, 8=octal, 2=binary – all others disallowed.
inBytesPerGroupNumber of bytes to dump per contiguous group of numbers. Defaults to 4.
inGroupsPerLineNumber of contiguous groups of numbers to dump per output line. If zero, no grouping is done, and address & ASCII display is suppressed. Defaults to 8.
inAddressRadixSpecifies the radix of the address column. 0=omit, 2=binary, 8=octal, 10=decimal, 16=hex – all others disallowed. Defaults to 0.
inShowAsciiIf True, show ASCII characters; otherwise no ASCII characters. Overridden to false if inGroupsPerLine is zero. Defaults to false.
inAddrOffsetSpecifies a value to be added to the addresses that appear in the dump. Ignored if inGroupsPerLine is zero.
Returns
A reference to the output string that received the dump.

◆ Fill() [1/2]

template<typename T >
bool NTV2Buffer::Fill ( const T &  inValue)
inline

Fills me with the given scalar value.

Parameters
[in]inValueThe scalar value to fill me with.
Returns
True if I'm currently allocated; otherwise false.

Definition at line 6192 of file ntv2publicinterface.h.

◆ Fill() [2/2]

template<typename T >
bool NTV2Buffer::Fill ( const T &  inValue,
const NTV2SegmentedXferInfo inXferInfo 
)
inline

Fills a portion of me with the given scalar value.

Parameters
[in]inValueThe scalar value.
[in]inXferInfoDescribes the (destination) portion of me to be filled.
Returns
True if successful; otherwise false.
Note
Offsets and lengths are checked. The function will return false for any overflow or underflow.

Definition at line 6209 of file ntv2publicinterface.h.

◆ Find()

template<typename T >
bool NTV2Buffer::Find ( const T &  inValue,
int &  inOutIndex 
) const
inline

Searches me for the given scalar value of type T starting at a given index position.

Parameters
[in]inValueSpecifies the scalar value to be searched for.
inOutIndexOn entry, specifies where searching begins. On exit, receives the index of the matching value. Negative indexes search backward from the end of the buffer, where -1 is the last T in the buffer (with the highest physical memory address).
Returns
True if successfully found; otherwise false.

Definition at line 6092 of file ntv2publicinterface.h.

◆ FindAll()

set< ULWord > & NTV2Buffer::FindAll ( ULWordSet outOffsets,
const NTV2Buffer inValue 
) const
Returns
A non-const reference to the outOffsets parameter.
Parameters
[out]outOffsetsReceives the byte offsets to every occurrence in my buffer.
[in]inValueSpecifies the data to search for.

Definition at line 1724 of file ntv2publicinterface.cpp.

◆ FL() [1/2]

float& NTV2Buffer::FL ( const int  inIndex)
inline

Definition at line 6476 of file ntv2publicinterface.h.

◆ FL() [2/2]

float NTV2Buffer::FL ( const int  inIndex) const
inline

Definition at line 6475 of file ntv2publicinterface.h.

◆ GetByteCount()

ULWord NTV2Buffer::GetByteCount ( void  ) const
inline
Returns
My size, in bytes.

Definition at line 6040 of file ntv2publicinterface.h.

◆ GetHostAddress()

void * NTV2Buffer::GetHostAddress ( const ULWord  inByteOffset,
const bool  inFromEnd = false 
) const
Parameters
[in]inByteOffsetSpecifies the offset from the start (or end) of my memory buffer. Must be less than my size (see GetByteCount).
[in]inFromEndSpecify 'true' to reference the end of my buffer. Specify 'false' (the default) to reference the start of my buffer.
Returns
The host address of the given byte. Returns NULL upon failure.

Definition at line 1610 of file ntv2publicinterface.cpp.

◆ GetHostPointer()

void* NTV2Buffer::GetHostPointer ( void  ) const
inline
Returns
My user-space host virtual address, as seen by the host process.

Definition at line 6023 of file ntv2publicinterface.h.

◆ GetRawHostPointer()

ULWord64 NTV2Buffer::GetRawHostPointer ( void  ) const
inline
Returns
My "raw" user-space host virtual address.
Note
On 32-bit platforms, the true address is found in the most significant 4 bytes of the ULWord64 value.

Definition at line 6035 of file ntv2publicinterface.h.

◆ GetRingChangedByteRange()

bool NTV2Buffer::GetRingChangedByteRange ( const NTV2Buffer inBuffer,
ULWord outByteOffsetFirst,
ULWord outByteOffsetLast 
) const

Assuming my contents and the contents of the given buffer comprise ring buffers that periodically get overwritten in contiguous variable-length chunks, answers with the contiguous byte range that differs between the two.

Parameters
[in]inBufferSpecifies the memory buffer whose contents are to be compared with mine. Contents are assumed to comprise a ring buffer, where data periodically gets overwritten in chunks.
[out]outByteOffsetFirstReceives the offset, in bytes, from the start of the buffer, of the first byte of the contiguous range that's different. Zero indicates the first byte in the buffer. If equal to NTV2Buffer::GetByteCount(), then both buffers are identical. If greater than 'outByteOffsetLast', then a wrap condition exists (see Note).
[out]outByteOffsetLastReceives the offset, in bytes, from the start of the buffer, of the last byte of the contiguous range that's different. Zero indicates the first byte in the buffer. If equal to NTV2Buffer::GetByteCount(), then both buffers are identical. If less than 'outByteOffsetFirst', a wrap condition exists (see Note).
Note
If a wrap condition exists – i.e., the contiguous byte range that differs starts near the end and wraps around to near the front – then 'outByteOffsetFirst' will be greater than 'outByteOffsetLast'.
Returns
True if successful; otherwise false.

Definition at line 1824 of file ntv2publicinterface.cpp.

◆ GetString() [1/2]

std::string NTV2Buffer::GetString ( const size_t  inU8Offset = 0,
const size_t  inMaxSize = 128 
) const
inline
Returns
My contents as a character string.
Parameters
[in]inU8OffsetThe starting offset, in bytes, where copying will commence.
[in]inMaxSizeSpecifies the maximum number of 8-bit values to be returned. Use zero for unlimited. The actual number of returned 8-bit values may be less than this, depending on my size. Defaults to 128.
Note
This function blindly copies my contents into the outgoing string, without checking for validity.

Definition at line 6626 of file ntv2publicinterface.h.

◆ GetString() [2/2]

bool NTV2Buffer::GetString ( std::string &  outString,
const size_t  inU8Offset = 0,
const size_t  inMaxSize = 128 
) const

Answers with my contents as a character string.

Parameters
[out]outStringReceives the character string copied verbatim from my contents.
[in]inU8OffsetThe starting offset, in bytes, where copying will commence.
[in]inMaxSizeSpecifies the maximum number of 8-bit values to be returned. Use zero for unlimited. The actual number of returned 8-bit values may be less than this, depending on my size. Defaults to 128.
Returns
True if successful; otherwise false.
Note
This function blindly copies my contents into the outgoing string, without checking for validity.

Definition at line 603 of file ntv2publicinterface.cpp.

◆ GetU16s() [1/2]

UWordSequence NTV2Buffer::GetU16s ( const size_t  inU16Offset = 0,
const size_t  inMaxSize = 64,
const bool  inByteSwap = false 
) const
inline
Returns
My contents as a vector of unsigned 16-bit values.
Parameters
[in]inU16OffsetThe starting offset, in 16-bit words, where copying will commence.
[in]inMaxSizeSpecifies the maximum number of 16-bit values to be returned. Use zero for unlimited. The actual number of returned 16-bit values may be less than this, depending on my size. Defaults to 64.
[in]inByteSwapSpecifies if the resulting values will be byte-swapped or not. Specify 'true' to byte-swap; specify 'false' to return the normal, unswapped values. Defaults to 'false'.
Note
If my length is not evenly divisible by 2, my last byte won't appear in the resulting vector.

Definition at line 6573 of file ntv2publicinterface.h.

◆ GetU16s() [2/2]

bool NTV2Buffer::GetU16s ( UWordSequence outU16s,
const size_t  inU16Offset = 0,
const size_t  inMaxSize = 64,
const bool  inByteSwap = false 
) const

Answers with my contents as a vector of unsigned 16-bit values.

Parameters
[out]outU16sReceives my contents as a vector of unsigned 16-bit values.
[in]inU16OffsetThe starting offset, in 16-bit words, where copying will commence.
[in]inMaxSizeSpecifies the maximum number of 16-bit values to be returned. Use zero for unlimited. The actual number of returned 16-bit values may be less than this, depending on my size. Defaults to 64.
[in]inByteSwapSpecifies if the resulting values will be byte-swapped or not. Specify 'true' to byte-swap; specify 'false' to return the normal, unswapped values. Defaults to 'false'.
Returns
True if successful; otherwise false.
Note
If my length is not evenly divisible by 2, my last byte won't appear in the resulting vector.

Definition at line 514 of file ntv2publicinterface.cpp.

◆ GetU32s() [1/2]

ULWordSequence NTV2Buffer::GetU32s ( const size_t  inU32Offset = 0,
const size_t  inMaxSize = 32,
const bool  inByteSwap = false 
) const
inline
Returns
My contents as a vector of unsigned 32-bit values.
Parameters
[in]inU32OffsetThe starting offset, in 32-bit words, where copying will commence.
[in]inMaxSizeSpecifies the maximum number of 32-bit values to be returned. Use zero for unlimited. The actual number of returned 32-bit values may be less than this, depending on my size. Defaults to 32.
[in]inByteSwapSpecifies if the resulting values will be byte-swapped or not. Specify 'true' to byte-swap; specify 'false' to return the normal, unswapped values. Defaults to 'false'.
Note
If my length is not evenly divisible by 4, my last bytes won't appear in the resulting vector.

Definition at line 6543 of file ntv2publicinterface.h.

◆ GetU32s() [2/2]

bool NTV2Buffer::GetU32s ( ULWordSequence outU32s,
const size_t  inU32Offset = 0,
const size_t  inMaxSize = 32,
const bool  inByteSwap = false 
) const

Answers with my contents as a vector of unsigned 32-bit values.

Parameters
[out]outU32sReceives my contents as a vector of unsigned 32-bit values.
[in]inU32OffsetThe starting offset, in 32-bit words, where copying will commence.
[in]inMaxSizeSpecifies the maximum number of 32-bit values to be returned. Use zero for unlimited. The actual number of returned 32-bit values may be less than this, depending on my size. Defaults to 32.
[in]inByteSwapSpecifies if the resulting values will be byte-swapped or not. Specify 'true' to byte-swap; specify 'false' to return the normal, unswapped values. Defaults to 'false'.
Returns
True if successful; otherwise false.
Note
If my length is not evenly divisible by 4, my last bytes won't appear in the resulting vector.

Definition at line 477 of file ntv2publicinterface.cpp.

◆ GetU64s() [1/2]

ULWord64Sequence NTV2Buffer::GetU64s ( const size_t  inU64Offset = 0,
const size_t  inMaxSize = 16,
const bool  inByteSwap = false 
) const
inline
Returns
My contents as a vector of unsigned 64-bit values.
Parameters
[in]inU64OffsetThe starting offset, in 64-bit words, where copying will commence.
[in]inMaxSizeSpecifies the maximum number of 64-bit values to be returned. Use zero for unlimited. The actual number of returned 64-bit values may be less than this, depending on my size. Defaults to 16.
[in]inByteSwapSpecifies if the resulting values will be byte-swapped or not. Specify 'true' to byte-swap; specify 'false' to return the normal, unswapped values. Defaults to 'false'.
Note
If my length is not evenly divisible by 8, my last bytes won't appear in the resulting vector.

Definition at line 6513 of file ntv2publicinterface.h.

◆ GetU64s() [2/2]

bool NTV2Buffer::GetU64s ( ULWord64Sequence outU64s,
const size_t  inU64Offset = 0,
const size_t  inMaxSize = 16,
const bool  inByteSwap = false 
) const

Answers with my contents as a vector of unsigned 16-bit values.

Parameters
[out]outU64sReceives my contents as a vector of unsigned 64-bit values.
[in]inU64OffsetThe starting offset, in 64-bit words, where copying will commence.
[in]inMaxSizeSpecifies the maximum number of 64-bit values to be returned. Use zero for unlimited. The actual number of returned 64-bit values may be less than this, depending on my size. Defaults to 16.
[in]inByteSwapSpecifies if the resulting values will be byte-swapped or not. Specify 'true' to byte-swap; specify 'false' to return the normal, unswapped values. Defaults to 'false'.
Returns
True if successful; otherwise false.
Note
If my length is not evenly divisible by 8, my last bytes won't appear in the resulting vector.

Definition at line 440 of file ntv2publicinterface.cpp.

◆ GetU8s() [1/2]

UByteSequence NTV2Buffer::GetU8s ( const size_t  inU8Offset = 0,
const size_t  inMaxSize = 128 
) const
inline
Returns
My contents as a vector of unsigned 8-bit values.
Parameters
[in]inU8OffsetThe starting offset, in bytes, where copying will commence.
[in]inMaxSizeSpecifies the maximum number of 8-bit values to be returned. Use zero for unlimited. The actual number of returned 8-bit values may be less than this, depending on my size. Defaults to 128.

Definition at line 6595 of file ntv2publicinterface.h.

◆ GetU8s() [2/2]

bool NTV2Buffer::GetU8s ( UByteSequence outU8s,
const size_t  inU8Offset = 0,
const size_t  inMaxSize = 128 
) const

Answers with my contents as a vector of unsigned 8-bit values.

Parameters
[out]outU8sReceives my contents as a vector of unsigned 8-bit values.
[in]inU8OffsetThe starting offset, in bytes, where copying will commence.
[in]inMaxSizeSpecifies the maximum number of 8-bit values to be returned. Use zero for unlimited. The actual number of returned 8-bit values may be less than this, depending on my size. Defaults to 128.
Returns
True if successful; otherwise false.

Definition at line 551 of file ntv2publicinterface.cpp.

◆ HostPageSize()

size_t NTV2Buffer::HostPageSize ( void  )
static
Returns
Host OS/hardware page size, in bytes.

Definition at line 1918 of file ntv2publicinterface.cpp.

◆ I16() [1/2]

int16_t& NTV2Buffer::I16 ( const int  inIndex)
inline

Definition at line 6466 of file ntv2publicinterface.h.

◆ I16() [2/2]

int16_t NTV2Buffer::I16 ( const int  inIndex) const
inline

Definition at line 6465 of file ntv2publicinterface.h.

◆ I32() [1/2]

int32_t& NTV2Buffer::I32 ( const int  inIndex)
inline

Definition at line 6470 of file ntv2publicinterface.h.

◆ I32() [2/2]

int32_t NTV2Buffer::I32 ( const int  inIndex) const
inline

Definition at line 6469 of file ntv2publicinterface.h.

◆ I64() [1/2]

int64_t& NTV2Buffer::I64 ( const int  inIndex)
inline

Definition at line 6474 of file ntv2publicinterface.h.

◆ I64() [2/2]

int64_t NTV2Buffer::I64 ( const int  inIndex) const
inline

Definition at line 6473 of file ntv2publicinterface.h.

◆ I8() [1/2]

int8_t& NTV2Buffer::I8 ( const int  inIndex)
inline

Definition at line 6462 of file ntv2publicinterface.h.

◆ I8() [2/2]

int8_t NTV2Buffer::I8 ( const int  inIndex) const
inline

Definition at line 6461 of file ntv2publicinterface.h.

◆ IsAllocatedBySDK()

bool NTV2Buffer::IsAllocatedBySDK ( void  ) const
inline
Returns
True if my host storage was allocated by my Allocate function; otherwise false if my host storage address and size was provided by the client application.

Definition at line 6046 of file ntv2publicinterface.h.

◆ IsContentEqual()

bool NTV2Buffer::IsContentEqual ( const NTV2Buffer inBuffer,
const ULWord  inByteOffset = 0,
const ULWord  inByteCount = 0xFFFFFFFF 
) const
Returns
True if the given memory buffer's contents are identical to my own.
Parameters
[in]inBufferSpecifies the memory buffer whose contents are to be compared with mine.
[in]inByteOffsetSpecifies the byte offset to start comparing. Defaults to the first byte.
[in]inByteCountSpecifies the maximum number of bytes to compare. Defaults to 0xFFFFFFFF (entire buffer).

Definition at line 1749 of file ntv2publicinterface.cpp.

◆ IsNULL()

bool NTV2Buffer::IsNULL ( void  ) const
inline
Returns
True if my user-space pointer is NULL, or my size is zero.

Definition at line 6062 of file ntv2publicinterface.h.

◆ IsPageAligned()

bool NTV2Buffer::IsPageAligned ( void  ) const
inline
Returns
True if my host storage was page-aligned when Allocated; otherwise false.

Definition at line 6057 of file ntv2publicinterface.h.

◆ IsProvidedByClient()

bool NTV2Buffer::IsProvidedByClient ( void  ) const
inline
Returns
True if my host storage was provided by the client application; otherwise false if it was allocated by my Allocate function.

Definition at line 6052 of file ntv2publicinterface.h.

◆ NextDifference()

bool NTV2Buffer::NextDifference ( const NTV2Buffer inBuffer,
ULWord byteOffset 
) const

Answers with the byte offset to the first or next difference.

Parameters
[in]inBufferSpecifies the memory buffer whose contents are to be compared with mine. The buffer sizes must match.
byteOffsetOn entry, specifies the byte offset where comparing starts (use zero to find the first difference); on exit, receives the byte offset of the next difference found (or 0xFFFFFFFF if identical).
Returns
True if successful; otherwise false.

Definition at line 1795 of file ntv2publicinterface.cpp.

◆ operator bool()

NTV2Buffer::operator bool ( ) const
inline
Returns
True if my host pointer is non-NULL and my byte count is non-zero; otherwise false.

Definition at line 6067 of file ntv2publicinterface.h.

◆ operator const T *()

template<typename T >
NTV2Buffer::operator const T * ( ) const
inline
Returns
My host address casted to a const T pointer.

Definition at line 6426 of file ntv2publicinterface.h.

◆ operator size_t()

NTV2Buffer::operator size_t ( ) const
inline
Returns
My size, in bytes, as a size_t.

Definition at line 6072 of file ntv2publicinterface.h.

◆ operator T*()

template<typename T >
NTV2Buffer::operator T* ( ) const
inline
Returns
My host address casted to a non-const T pointer.

Definition at line 6431 of file ntv2publicinterface.h.

◆ operator=()

NTV2Buffer & NTV2Buffer::operator= ( const NTV2Buffer inRHS)

Assigns me from another NTV2Buffer instance.

Parameters
[in]inRHSSpecifies the NTV2Buffer instance to assign ("deep" copy) to me.

Definition at line 1480 of file ntv2publicinterface.cpp.

◆ Print()

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

Prints a human-readable representation of me into the given output stream.

Parameters
inOutStreamThe output stream to receive my human-readable representation.
Returns
A reference to the given output stream.

Definition at line 275 of file ntv2publicinterface.cpp.

◆ PutU16s()

bool NTV2Buffer::PutU16s ( const UWordSequence inU16s,
const size_t  inU16Offset = 0,
const bool  inByteSwap = false 
)

Copies a vector of unsigned 16-bit values into me.

Parameters
[in]inU16sThe vector of unsigned 16-bit values to be copied into me.
[in]inU16OffsetSpecifies my starting offset (of 16-bit values) at which the vector values will be written. Defaults to zero.
[in]inByteSwapSpecifies if the 16-bit values will be byte-swapped or not before being written into me. Specify 'true' to byte-swap; otherwise specify 'false'. Defaults to 'false'.
Returns
True if successful; otherwise false.

Definition at line 693 of file ntv2publicinterface.cpp.

◆ PutU32s()

bool NTV2Buffer::PutU32s ( const ULWordSequence inU32s,
const size_t  inU32Offset = 0,
const bool  inByteSwap = false 
)

Copies a vector of unsigned 32-bit values into me.

Parameters
[in]inU32sThe vector of unsigned 32-bit values to be copied into me.
[in]inU32OffsetSpecifies my starting offset (of 32-bit values) at which the vector values will be written. Defaults to zero.
[in]inByteSwapSpecifies if the 32-bit values will be byte-swapped or not before being written into me. Specify 'true' to byte-swap; otherwise specify 'false'. Defaults to 'false'.
Returns
True if successful; otherwise false.

Definition at line 665 of file ntv2publicinterface.cpp.

◆ PutU64s()

bool NTV2Buffer::PutU64s ( const ULWord64Sequence inU64s,
const size_t  inU64Offset = 0,
const bool  inByteSwap = false 
)

Copies a vector of unsigned 64-bit values into me.

Parameters
[in]inU64sThe vector of unsigned 64-bit values to be copied into me.
[in]inU64OffsetSpecifies my starting offset (of 64-bit values) at which the vector values will be written. Defaults to zero.
[in]inByteSwapSpecifies if the 64-bit values will be byte-swapped or not before being written into me. Specify 'true' to byte-swap; otherwise specify 'false'. Defaults to 'false'.
Returns
True if successful; otherwise false.

Definition at line 637 of file ntv2publicinterface.cpp.

◆ PutU8s()

bool NTV2Buffer::PutU8s ( const UByteSequence inU8s,
const size_t  inU8Offset = 0 
)

Copies a vector of unsigned 8-bit values into me.

Parameters
[in]inU8sThe vector of unsigned 8-bit values to be copied into me.
[in]inU8OffsetSpecifies my starting byte offset at which the vector values will be written. Defaults to zero.
Returns
True if successful; otherwise false.

Definition at line 721 of file ntv2publicinterface.cpp.

◆ RPCDecode()

bool NTV2Buffer::RPCDecode ( const NTV2_RPC_BLOB_TYPE inBlob,
size_t &  inOutIndex 
)

Definition at line 3512 of file ntv2publicinterface.cpp.

◆ RPCEncode()

bool NTV2Buffer::RPCEncode ( NTV2_RPC_BLOB_TYPE outBlob)

Definition at line 3503 of file ntv2publicinterface.cpp.

◆ Segment()

NTV2Buffer & NTV2Buffer::Segment ( NTV2Buffer outPtr,
const ULWord  inByteOffset,
const ULWord  inByteCount 
) const

Resets an NTV2Buffer instance to reference a contiguous segment (portion) of my memory buffer.

Parameters
[out]outPtrThe NTV2Buffer to be reset to my sub-segment. Note this receives a reference my segment, not a copy of it.
[in]inByteOffsetSpecifies the offset, in bytes, where the segment starts.
[in]inByteCountSpecifies the segment length, in bytes.
Returns
The specified NTV2Buffer. It will be set to null/empty upon failure.
Note
The offset and byte count are both checked against my buffer size.
Warning
Using the "outPtr" instance after my destruction will likely cause access violations, heap corruption, etc.

Definition at line 428 of file ntv2publicinterface.cpp.

◆ Set()

bool NTV2Buffer::Set ( const void *  pInUserPointer,
const size_t  inByteCount 
)

Sets (or resets) me from a client-supplied address and size.

Parameters
[in]pInUserPointerSpecifies the user-space virtual memory address. The client is entirely responsible for it. Ignored if inByteCount is zero.
[in]inByteCountSpecifies the byte count. Ignored if pInUserPointer is NULL.
Returns
True if both pInUserPointer and inByteCount agree (i.e. if pInUserPointer and inByteCount are both zero, or if they're both non-zero); otherwise false if they don't agree (i.e. one is non-zero and the other is zero, or vice-versa).
Note
Any memory that I was referencing prior to this call that I was responsible for will automatically be freed.

Definition at line 1538 of file ntv2publicinterface.cpp.

◆ SetAndFill()

bool NTV2Buffer::SetAndFill ( const void *  pInUserPointer,
const size_t  inByteCount,
const UByte  inValue 
)

Sets (or resets) me from a client-supplied address and size.

Parameters
[in]pInUserPointerSpecifies the user-space virtual memory address. The client is entirely responsible for it. Ignored if inByteCount is zero.
[in]inByteCountSpecifies the byte count. Ignored if pInUserPointer is NULL.
[in]inValueSpecifies the value to fill the buffer with.
Returns
True if both pInUserPointer and inByteCount agree (i.e. if pInUserPointer and inByteCount are both zero, or if they're both non-zero); otherwise false if they don't agree (i.e. one is non-zero and the other is zero, or vice-versa).
Note
Any memory that I was referencing prior to this call that I was responsible for will automatically be freed.

Definition at line 1548 of file ntv2publicinterface.cpp.

◆ SetDefaultPageSize()

bool NTV2Buffer::SetDefaultPageSize ( const size_t  inNewSize)
static

Changes the default page size for use in future page-aligned allocations.

Parameters
[in]inNewSizeThe new page size value, in bytes. Must be a power of 2.
Returns
True if successful; otherwise false.

Definition at line 1910 of file ntv2publicinterface.cpp.

◆ SetFrom()

bool NTV2Buffer::SetFrom ( const NTV2Buffer inBuffer)

Replaces my contents from the given memory buffer without resizing me.

Parameters
[in]inBufferSpecifies the memory buffer whose contents are to be copied into my own. If this buffer is larger than I am, I am not resized; instead, only those bytes that fit in me will be copied.
Returns
True if successful; otherwise false.

Definition at line 1625 of file ntv2publicinterface.cpp.

◆ SwapWith()

bool NTV2Buffer::SwapWith ( NTV2Buffer inBuffer)

Swaps my underlying buffer with another's.

Parameters
[in]inBufferSpecifies the NTV2Buffer I'll swap buffers with.
Returns
True if successful; otherwise false.
Note
The buffers must have identical sizes, and must have equal ownership attributes.
AJA recommends not using this function to swap NTV2Buffers that were allocated in different executable modules (e.g., on Windows, an NTV2Buffer that was allocated in a DLL with another that was allocated in an EXE).

Definition at line 1705 of file ntv2publicinterface.cpp.

◆ U16() [1/2]

uint16_t& NTV2Buffer::U16 ( const int  inIndex)
inline

Definition at line 6464 of file ntv2publicinterface.h.

◆ U16() [2/2]

uint16_t NTV2Buffer::U16 ( const int  inIndex) const
inline

Definition at line 6463 of file ntv2publicinterface.h.

◆ U32() [1/2]

uint32_t& NTV2Buffer::U32 ( const int  inIndex)
inline

Definition at line 6468 of file ntv2publicinterface.h.

◆ U32() [2/2]

uint32_t NTV2Buffer::U32 ( const int  inIndex) const
inline

Definition at line 6467 of file ntv2publicinterface.h.

◆ U64() [1/2]

uint64_t& NTV2Buffer::U64 ( const int  inIndex)
inline

Definition at line 6472 of file ntv2publicinterface.h.

◆ U64() [2/2]

uint64_t NTV2Buffer::U64 ( const int  inIndex) const
inline

Definition at line 6471 of file ntv2publicinterface.h.

◆ U8() [1/2]

uint8_t& NTV2Buffer::U8 ( const int  inIndex)
inline
Returns
A writeable (non-const) reference to the value at the given zero-based index position.
Parameters
[in]inIndexSpecifies the zero-based index position (e.g. 0 is first value at start of my memory). If negative, indexes from the end of my memory (e.g. -1 is last value).
Warning
Bad index values will result in access violation exceptions.

Definition at line 6459 of file ntv2publicinterface.h.

◆ U8() [2/2]

uint8_t NTV2Buffer::U8 ( const int  inIndex) const
inline
Returns
A copy of the value at the given zero-based index position.
Parameters
[in]inIndexSpecifies the zero-based index position (e.g. 0 is first value at start of my memory). If negative, indexes from the end of my memory (e.g. -1 is last value).
Warning
Bad index values will result in access violation exceptions.

Definition at line 6451 of file ntv2publicinterface.h.


The documentation for this class was generated from the following files:
NTV2Buffer
A generic user-space buffer object that has an address and a length. Used most often to share an arbi...
Definition: ntv2publicinterface.h:5967
ULWord
uint32_t ULWord
Definition: ajatypes.h:246