I am the principal class that stores a single SMPTE-291 SDI ancillary data packet OR the digitized contents of one "analog" raster line (e.g. line 21 captions or VITC). Since I'm payload-agnostic, I serve as the generic base class for more specific objects that know how to decode/parse specific types of ancillary data. More...

#include <ancillarydata.h>

Inheritance diagram for AJAAncillaryData:

[legend]

Collaboration diagram for AJAAncillaryData:

[legend]

Public Types
typedef UWordSequence	U16Packet
	An ordered sequence of 10-bit packet words stored in uint16_t values. More...

typedef std::vector< U16Packet >	U16Packets
	An ordered sequence of zero or more U16Packet values. More...

Public Member Functions
Construction, Destruction, Copying
	AJAAncillaryData ()
	My default constructor. More...

	AJAAncillaryData (const AJAAncillaryData &inClone)
	My copy constructor (from reference). More...

	AJAAncillaryData (const AJAAncillaryData *pInClone)
	My copy constructor (from pointer). More...

virtual	~AJAAncillaryData ()
	My destructor. More...

virtual void	Clear (void)
	Frees my allocated memory, if any, and resets my members to their default values. More...

virtual AJAAncillaryData *	Clone (void) const

Inquiry
virtual uint16_t	GetStreamInfo (void) const

virtual bool	HasStreamInfo (void) const

virtual uint8_t	Calculate8BitChecksum (void) const
	Generates an 8-bit checksum from the DID + SID + DC + payload data. More...

virtual uint16_t	Calculate9BitChecksum (void) const
	Generates the official SMPTE 291 9-bit checksum from the DID + SID + DC + payload data. More...

virtual bool	ChecksumOK (void) const
	Compares the received 8-bit checksum with a newly calculated 8-bit checksum. Returns 'true' if they match. More...

virtual AJAAncillaryData &	operator= (const AJAAncillaryData &inRHS)

virtual bool	operator== (const AJAAncillaryData &inRHS) const

virtual bool	operator!= (const AJAAncillaryData &inRHS) const

virtual AJAStatus	Compare (const AJAAncillaryData &inRHS, const bool inIgnoreLocation=true, const bool inIgnoreChecksum=true) const
	Compares me with another packet. More...

Modification
virtual AJAStatus	SetDID (const uint8_t inDataID)
	Sets my Data ID (DID). More...

virtual AJAStatus	SetSID (const uint8_t inSID)
	Sets my Secondary Data ID (SID) - (aka the Data Block Number (DBN) for "Type 1" SMPTE-291 packets). More...

virtual AJAStatus	SetDIDSID (const AJAAncDIDSIDPair &inDIDSID)
	Sets both my Data ID (DID) and Secondary Data ID (SID). More...

virtual AJAStatus	SetChecksum (const uint8_t inChecksum8, const bool inValidate=false)
	Sets my 8-bit checksum. Note that it is not usually necessary to generate an 8-bit checksum, since the ANC Insertion hardware ignores this field and (for SMPTE-291 Anc packets) generates and inserts its own "proper" 9-bit SMPTE-291 checksum. More...

virtual AJAStatus	SetDataLocation (const AJAAncDataLoc &inLoc)
	Sets my ancillary data "location" within the video stream. More...

virtual AJAStatus	SetLocationVideoLink (const AJAAncDataLink inLink)
	Sets my ancillary data "location" within the video stream. More...

virtual AJAStatus	SetLocationDataStream (const AJAAncDataStream inStream)
	Sets my ancillary data "location" data stream value (DS1,DS2...). More...

virtual AJAStatus	SetLocationDataChannel (const AJAAncDataChannel inChannel)
	Sets my ancillary data "location" data channel value (Y or C). More...

virtual AJAStatus	SetLocationLineNumber (const uint16_t inLineNum)
	Sets my ancillary data "location" frame line number. More...

virtual AJAStatus	SetLocationHorizOffset (const uint16_t inOffset)
	Sets my ancillary data "location" horizontal offset. More...

virtual AJAStatus	SetDataCoding (const AJAAncDataCoding inCodingType)
	Sets my ancillary data coding type (e.g. digital or analog/raw waveform). More...

virtual AJAAncillaryData &	SetFrameID (const uint32_t inFrameID)
	Sets my originating frame identifier. More...

virtual AJAAncillaryData &	SetBufferFormat (const AJAAncBufferFormat inFmt)
	Sets my originating buffer format. More...

Payload Data Access
virtual uint8_t	GetPayloadByteAtIndex (const uint32_t inIndex0) const

virtual const uint8_t *	GetPayloadData (void) const

virtual AJAStatus	GetPayloadData (uint8_t *pBuffer, const uint32_t inByteCapacity) const
	Copies my payload data into an external buffer. More...

virtual AJAStatus	GetPayloadData (UWordSequence &outUDWs, const bool inAddParity=true) const
	Appends my payload data onto the given UDW vector as 10-bit User Data Words (UDWs), adding parity as needed. More...

Payload Data Modification
virtual AJAStatus	SetPayloadByteAtIndex (const uint8_t inDataByte, const uint32_t inIndex0)

virtual AJAStatus	SetPayloadData (const uint8_t *pInData, const uint32_t inByteCount)
	Copy data from external memory into my local payload memory. More...

virtual AJAStatus	AppendPayloadData (const uint8_t *pInBuffer, const uint32_t inByteCount)
	Appends data from an external buffer onto the end of my existing payload. More...

virtual AJAStatus	AppendPayload (const AJAAncillaryData &inAncData)
	Appends payload data from another AJAAncillaryData object to my existing payload. More...

virtual AJAStatus	AppendPayload (const AJAAncillaryData *pInAncData)

virtual AJAStatus	SetFromSMPTE334 (const uint16_t *pInData, const uint32_t inNumWords, const AJAAncDataLoc &inLocInfo)
	Copies payload data from an external 16-bit source into local payload memory. More...

virtual AJAStatus	ParsePayloadData (void)
	Parses (interprets) the "local" ancillary data from my payload data. More...

virtual bool	GotValidReceiveData (void) const

virtual AJAStatus	GeneratePayloadData (void)
	Generates the payload data from the "local" ancillary data. More...

Receive From AJA Hardware
virtual AJAStatus	InitWithReceivedData (const uint8_t *pInData, const size_t inMaxBytes, const AJAAncDataLoc &inLocationInfo, uint32_t &outPacketByteCount)
	Initializes me from "raw" ancillary data received from hardware (ingest) – see SDI Anc Buffer Data Format. More...

virtual AJAStatus	InitWithReceivedData (const std::vector< uint8_t > &inData, const AJAAncDataLoc &inLocationInfo)
	Initializes me from "raw" ancillary data received from hardware (ingest) – see SDI Anc Buffer Data Format. More...

virtual AJAStatus	InitWithReceivedData (const ULWordSequence &inData, uint16_t &inOutStartIndex, const bool inIgnoreChecksum=false)
	Initializes me from the given 32-bit IP packet words received from hardware (ingest). More...

Transmit To AJA Hardware
virtual AJAStatus	GetRawPacketSize (uint32_t &outPacketSize) const
	Returns the number of "raw" ancillary data bytes that will be generated by AJAAncillaryData::GenerateTransmitData (for playback mode). More...

virtual AJAStatus	GenerateTransmitData (uint8_t *pBuffer, const size_t inMaxBytes, uint32_t &outPacketSize)
	Generates "raw" ancillary data from my internal ancillary data (playback) – see SDI Anc Buffer Data Format. More...

virtual AJAStatus	GenerateTransmitData (UWordSequence &outData)
	Generates "raw" 10-bit ancillary packet component data from my internal ancillary data (playback). More...

virtual AJAStatus	GenerateTransmitData (ULWordSequence &outData)
	Generates the 32-bit IP packet words necessary for constructing an outgoing IP/RTP stream. More...

Static Public Member Functions
static uint16_t	AddEvenParity (const uint8_t inDataByte)

static bool	GetAncPacketsFromVANCLine (const UWordSequence &inYUV16Line, const AncChannelSearchSelect inChanSelect, U16Packets &outRawPackets, U16Packet &outWordOffsets)
	Extracts whatever VANC packets are found inside the given 16-bit YUV line buffer. More...

static bool	Unpack8BitYCbCrToU16sVANCLine (const void *pInYUV8Line, U16Packet &outU16YUVLine, const uint32_t inNumPixels)
	Converts a single line of NTV2_FBF_8BIT_YCBCR data from the given source buffer into an ordered sequence of uint16_t values that contain the resulting 10-bit even-parity data. More...

static void	GetInstanceCounts (uint32_t &outConstructed, uint32_t &outDestructed)

static uint32_t	GetNumActiveInstances (void)

static uint32_t	GetNumConstructed (void)

static uint32_t	GetNumDestructed (void)

static void	ResetInstanceCounts (void)

Protected Types
typedef std::vector< uint8_t >	ByteVector

typedef ByteVector::size_type	ByteVectorIndex

typedef ByteVector::const_iterator	ByteVectorConstIter

Protected Member Functions
void	Init (void)

AJAStatus	AllocDataMemory (const uint32_t inNumBytes)

AJAStatus	FreeDataMemory (void)

virtual uint8_t	GetGUMPHeaderByte2 (void) const

virtual uint8_t	GetGUMPHeaderByte3 (void) const

Static Protected Member Functions
static uint8_t	GetGUMPHeaderByte1 (void)

Protected Attributes
uint8_t	m_DID
	Official SMPTE ancillary packet ID (w/o parity) More...

uint8_t	m_SID
	Official SMPTE secondary ID (or DBN - w/o parity) More...

uint8_t	m_checksum
	My 8-bit checksum: DID + SID + DC + payload (w/o parity) [note: NOT the same as the 9-bit checksum in a SMPTE-291 packet!]. More...

AJAAncDataLoc	m_location
	Location of the ancillary data in the video stream (Y or C, HANC or VANC, etc.) More...

AJAAncDataCoding	m_coding
	Analog or digital data. More...

ByteVector	m_payload
	My payload data (DC = size) More...

bool	m_rcvDataValid
	This is set true (or not) by ParsePayloadData() More...

AJAAncDataType	m_ancType
	One of a known set of ancillary data types (or "Custom" if not identified) More...

AJAAncBufferFormat	m_bufferFmt
	My originating buffer format, if known. More...

uint32_t	m_frameID
	ID of my originating frame, if known. More...

uint64_t	m_userData
	User data (for client use) More...

Printing & Debugging
virtual std::ostream &	Print (std::ostream &inOutStream, const bool inDetailed=false) const
	Streams a human-readable representation of me to the given output stream. More...

virtual std::ostream &	DumpPayload (std::ostream &inOutStream) const
	Dumps a human-readable representation of my payload bytes into the given output stream. More...

virtual std::string	CompareWithInfo (const AJAAncillaryData &inRHS, const bool inIgnoreLocation=true, const bool inIgnoreChecksum=true) const
	Compares me with another packet and returns a string that describes what's different. More...

virtual std::string	IDAsString (void) const

virtual std::string	AsString (const uint16_t inDumpMaxBytes=0) const

static std::string	DIDSIDToString (const uint8_t inDID, const uint8_t inSDID)

Detailed Description

I am the principal class that stores a single SMPTE-291 SDI ancillary data packet OR the digitized contents of one "analog" raster line (e.g. line 21 captions or VITC). Since I'm payload-agnostic, I serve as the generic base class for more specific objects that know how to decode/parse specific types of ancillary data.

My AJAAncillaryData::m_payload member stores the User Data Words (UDWs) as an ordered collection of 8-bit data bytes. Because it's an STL vector, it knows how many UDW elements it contains. Thus, it stores the SMPTE "DC" (data count) value.

I also have several member variables for metadata – i.e., information about the packet – including my data ID (DID), secondary data ID (SDID), checksum (CS), location in the video stream, etc.

Transmit – Packet Creation

Use AJAAncillaryDataFactory::Create to instantiate a specific type of data packet.
Or to "Manually" create a packet:
const string myPacketData ("This is a test");

AJAAncillaryData packet; // Defaults to AJAAncDataCoding_Digital, AJAAncDataLink_A, AJAAncDataStream_1, AJAAncDataChannel_Y, AJAAncDataSpace_VANC

packet.SetDID(0xAA); packet.SetSID(0xBB); // Set the DID & SDID

packet.SetLocationLineNumber(10); // Set the SMPTE line number you want the packet inserted at

packet.SetPayloadData(myPacketData.c_str(), myPacketData.length()); // Copy in the packet data
For newer devices with Anc inserters, call AJAAncillaryData::GenerateTransmitData to fill the Anc buffer used in the AUTOCIRCULATE_TRANSFER::SetAncBuffers call (see SDI Anc Buffer Data Format).
For multiple packets, put each AJAAncillaryData instance into an AJAAncillaryList.

Receive – Packet Detection

Use AJAAncillaryDataFactory::GuessAncillaryDataType to detect the Anc packet type.

Warning: Not thread-safe! When any of my non-const methods are called by one thread, do not call any of my methods from any other thread.

Definition at line 550 of file ancillarydata.h.

Member Typedef Documentation

◆ ByteVector

typedef std::vector<uint8_t> AJAAncillaryData::ByteVector

protected

Definition at line 1069 of file ancillarydata.h.

◆ ByteVectorConstIter

typedef ByteVector::const_iterator AJAAncillaryData::ByteVectorConstIter

protected

Definition at line 1071 of file ancillarydata.h.

◆ ByteVectorIndex

typedef ByteVector::size_type AJAAncillaryData::ByteVectorIndex

protected

Definition at line 1070 of file ancillarydata.h.

◆ U16Packet

typedef UWordSequence AJAAncillaryData::U16Packet

An ordered sequence of 10-bit packet words stored in uint16_t values.

Definition at line 1019 of file ancillarydata.h.

◆ U16Packets

typedef std::vector<U16Packet> AJAAncillaryData::U16Packets

An ordered sequence of zero or more U16Packet values.

Definition at line 1020 of file ancillarydata.h.

Constructor & Destructor Documentation

◆ AJAAncillaryData() [1/3]

AJAAncillaryData::AJAAncillaryData ( )

My default constructor.

Definition at line 85 of file ancillarydata.cpp.

◆ AJAAncillaryData() [2/3]

AJAAncillaryData::AJAAncillaryData ( const AJAAncillaryData & inClone )

My copy constructor (from reference).

Parameters

[in] inClone The AJAAncillaryData object to be cloned.

Definition at line 94 of file ancillarydata.cpp.

◆ AJAAncillaryData() [3/3]

AJAAncillaryData::AJAAncillaryData ( const AJAAncillaryData * pInClone )

My copy constructor (from pointer).

Parameters

[in] pInClone A valid pointer to the AJAAncillaryData object to be cloned.

Definition at line 104 of file ancillarydata.cpp.

◆ ~AJAAncillaryData()

AJAAncillaryData::~AJAAncillaryData ( )

virtual

My destructor.

Definition at line 115 of file ancillarydata.cpp.

Member Function Documentation

◆ AddEvenParity()

uint16_t AJAAncillaryData::AddEvenParity ( const uint8_t inDataByte )

static

Returns: The given data byte in bits 7:0, plus even parity in bit 8 and ~bit 8 in bit 9.

Parameters

[in] inDataByte The given data byte to have parity added to it.

Definition at line 1491 of file ancillarydata.cpp.

◆ AllocDataMemory()

AJAStatus AJAAncillaryData::AllocDataMemory ( const uint32_t inNumBytes )

protected

Definition at line 159 of file ancillarydata.cpp.

◆ AppendPayload() [1/2]

AJAStatus AJAAncillaryData::AppendPayload ( const AJAAncillaryData & inAncData )

virtual

Appends payload data from another AJAAncillaryData object to my existing payload.

Parameters

[in] inAncData The AJAAncillaryData object whose payload data is to be appended to my own.

Returns: AJA_STATUS_SUCCESS if successful.

Definition at line 414 of file ancillarydata.cpp.

◆ AppendPayload() [2/2]

virtual AJAStatus AJAAncillaryData::AppendPayload ( const AJAAncillaryData * pInAncData )

inlinevirtual

Deprecated:: Use AppendPayload(const AJAAncillaryData &) instead.

Definition at line 846 of file ancillarydata.h.

◆ AppendPayloadData()

AJAStatus AJAAncillaryData::AppendPayloadData	(	const uint8_t *	pInBuffer,
		const uint32_t	inByteCount
	)

virtual

Appends data from an external buffer onto the end of my existing payload.

Parameters

[in]	pInBuffer	Specifies a valid, non-NULL starting address of the external buffer from which the payload data will be copied.
[in]	inByteCount	Specifies the number of bytes to append.

Returns: AJA_STATUS_SUCCESS if successful.

Definition at line 392 of file ancillarydata.cpp.

◆ AsString()

string AJAAncillaryData::AsString ( const uint16_t inDumpMaxBytes = 0 ) const

virtual

Returns: Converts me into a compact, human-readable string.

Parameters

[in] inDumpMaxBytes Number of payload bytes to dump into the returned string. Defaults to zero (none).

Definition at line 1333 of file ancillarydata.cpp.

◆ Calculate8BitChecksum()

uint8_t AJAAncillaryData::Calculate8BitChecksum ( void ) const

virtual

Generates an 8-bit checksum from the DID + SID + DC + payload data.

Note: This is NOT the same as the official SMPTE-291 checksum, which is 9 bits wide and should be calculated by the hardware embedder.; The calculated checksum is NOT stored in my m_checksum member variable. Call SetChecksum to store it.

Returns: The calculated 8-bit checksum.

Definition at line 221 of file ancillarydata.cpp.

◆ Calculate9BitChecksum()

uint16_t AJAAncillaryData::Calculate9BitChecksum ( void ) const

virtual

Generates the official SMPTE 291 9-bit checksum from the DID + SID + DC + payload data.

Note: This class is only applicable to 8-bit ancillary data applications.

Returns: The calculated 9-bit checksum.

Definition at line 237 of file ancillarydata.cpp.

◆ ChecksumOK()

virtual bool AJAAncillaryData::ChecksumOK ( void ) const

inlinevirtual

Compares the received 8-bit checksum with a newly calculated 8-bit checksum. Returns 'true' if they match.

Note: This is NOT the same as the official SMPTE-291 checksum, which is 9 bits wide and should be calculated by the hardware.

Returns: True if the calculated checksum matches received checksum; otherwise false.

Definition at line 643 of file ancillarydata.h.

◆ Clear()

void AJAAncillaryData::Clear ( void )

virtual

Frees my allocated memory, if any, and resets my members to their default values.

Reimplemented in AJAAncillaryData_Timecode_ATC, AJAAncillaryData_Cea608_Line21, AJAAncillaryData_Cea608_Vanc, AJAAncillaryData_Timecode_VITC, AJAAncillaryData_FrameStatusInfo524D, AJAAncillaryData_Cea708, AJAAncillaryData_FrameStatusInfo5251, AJAAncillaryData_HDR_HDR10, AJAAncillaryData_HDR_HLG, AJAAncillaryData_HDR_SDR, AJAAncillaryData_Timecode, and AJAAncillaryData_Cea608.

Definition at line 147 of file ancillarydata.cpp.

◆ Clone()

AJAAncillaryData * AJAAncillaryData::Clone ( void ) const

virtual

Returns: A clone of myself.

Definition at line 153 of file ancillarydata.cpp.

◆ Compare()

AJAStatus AJAAncillaryData::Compare	(	const AJAAncillaryData &	inRHS,
		const bool	inIgnoreLocation = `true`,
		const bool	inIgnoreChecksum = `true`
	)		const

virtual

Compares me with another packet.

Parameters

[in]	inRHS	The packet I am to be compared with.
[in]	inIgnoreLocation	If true, don't compare each packet's AJAAncDataLoc info. Defaults to true.
[in]	inIgnoreChecksum	If true, don't compare each packet's checksums. Defaults to true.

Returns: AJA_STATUS_SUCCESS if equal; otherwise AJA_STATUS_FAIL.

Definition at line 1399 of file ancillarydata.cpp.

◆ CompareWithInfo()

string AJAAncillaryData::CompareWithInfo	(	const AJAAncillaryData &	inRHS,
		const bool	inIgnoreLocation = `true`,
		const bool	inIgnoreChecksum = `true`
	)		const

virtual

Compares me with another packet and returns a string that describes what's different.

Parameters

[in]	inRHS	The packet I am to be compared with.
[in]	inIgnoreLocation	If true, don't compare each packet's AJAAncDataLoc info. Defaults to true.
[in]	inIgnoreChecksum	If true, don't compare each packet's checksums. Defaults to true.

Returns: Empty string if equal; otherwise a string that contains one or more differences found, delimited by newline characters.

Definition at line 1426 of file ancillarydata.cpp.

◆ DIDSIDToString()

string AJAAncillaryData::DIDSIDToString	(	const uint8_t	inDID,
		const uint8_t	inSDID
	)

static

Returns: A string containing a human-readable representation of the given DID/SDID values, or empty for invalid or unknown values.

Parameters

[in]	inDID	Specifies the Data ID value.
[in]	inSDID	Specifies the Secondary Data ID value.

Definition at line 1811 of file ancillarydata.cpp.

◆ DumpPayload()

ostream & AJAAncillaryData::DumpPayload ( std::ostream & inOutStream ) const

virtual

Dumps a human-readable representation of my payload bytes into the given output stream.

Parameters

inOutStream Specifies the output stream.

Returns: The given output stream.

Definition at line 1370 of file ancillarydata.cpp.

◆ FreeDataMemory()

AJAStatus AJAAncillaryData::FreeDataMemory ( void )

protected

Definition at line 181 of file ancillarydata.cpp.

◆ GeneratePayloadData()

virtual AJAStatus AJAAncillaryData::GeneratePayloadData ( void )

inlinevirtual

Generates the payload data from the "local" ancillary data.

Note: This abstract method is overridden for specific Anc data types.

Returns: AJA_STATUS_SUCCESS if successful.

Reimplemented in AJAAncillaryData_Timecode_ATC, AJAAncillaryData_Cea608_Vanc, AJAAncillaryData_Cea608_Line21, AJAAncillaryData_Timecode_VITC, AJAAncillaryData_Cea708, and AJAAncillaryData_Timecode.

Definition at line 881 of file ancillarydata.h.

◆ GenerateTransmitData() [1/3]

AJAStatus AJAAncillaryData::GenerateTransmitData	(	uint8_t *	pBuffer,
		const size_t	inMaxBytes,
		uint32_t &	outPacketSize
	)

virtual

Generates "raw" ancillary data from my internal ancillary data (playback) – see SDI Anc Buffer Data Format.

Parameters

	pBuffer	Pointer to "raw" packet data buffer to be filled.
[in]	inMaxBytes	Maximum number of bytes left in the given data buffer.
[out]	outPacketSize	Receives the size, in bytes, of the generated packet.

Returns: AJA_STATUS_SUCCESS if successful.

Definition at line 665 of file ancillarydata.cpp.

◆ GenerateTransmitData() [2/3]

AJAStatus AJAAncillaryData::GenerateTransmitData ( ULWordSequence & outData )

virtual

Generates the 32-bit IP packet words necessary for constructing an outgoing IP/RTP stream.

Parameters

outData Specifies the vector into which data will be appended. The data will be in network byte order (big-endian).

Returns: AJA_STATUS_SUCCESS if successful.

Definition at line 831 of file ancillarydata.cpp.

◆ GenerateTransmitData() [3/3]

AJAStatus AJAAncillaryData::GenerateTransmitData ( UWordSequence & outData )

virtual

Generates "raw" 10-bit ancillary packet component data from my internal ancillary data (playback).

Parameters

outData Specifies the vector to which data will be appended.

Returns: AJA_STATUS_SUCCESS if successful.

Definition at line 781 of file ancillarydata.cpp.

◆ GetAncPacketsFromVANCLine()

bool AJAAncillaryData::GetAncPacketsFromVANCLine	(	const UWordSequence &	inYUV16Line,
		const AncChannelSearchSelect	inChanSelect,
		U16Packets &	outRawPackets,
		U16Packet &	outWordOffsets
	)

static

Extracts whatever VANC packets are found inside the given 16-bit YUV line buffer.

Parameters

[in]	inYUV16Line	Specifies the uint16_t sequence containing the 10-bit YUV VANC line data components. (Use UnpackLine_10BitYUVtoUWordSequence to convert a VANC line from an NTV2_FBF_10BIT_YCBCR frame buffer into this format. Use UnpackLine_8BitYUVtoU16s to convert a VANC line from an NTV2_FBF_8BIT_YCBCR frame buffer into this format.)
[in]	inChanSelect	Specifies the ancillary data channel to search. Use AncChannelSearch_Y for luma, AncChannelSearch_C for chroma, or AncChannelSearch_Both for both (SD only).
[out]	outRawPackets	Receives the packet vector, which will contain one vector of uint16_t values per extracted packet. Each packet in the returned list will start with the 0x000/0x3FF/0x3FF/DID/SDID/DC sequence, followed by each 10-bit packet data word, and ending with the checksum word.
[out]	outWordOffsets	Receives the horizontal word offsets into the line, one for each packet found. This should have the same number of elements as "outRawPackets". These offsets can also be used to discern which channel each packet originated in (Y or C).

Returns: True if successful; false if failed.

Note: This function will not finish parsing the line once a parity, checksum, or overrun error is discovered in the line.

Definition at line 1594 of file ancillarydata.cpp.

◆ GetGUMPHeaderByte1()

static uint8_t AJAAncillaryData::GetGUMPHeaderByte1 ( void )

inlinestaticprotected

Definition at line 1078 of file ancillarydata.h.

◆ GetGUMPHeaderByte2()

uint8_t AJAAncillaryData::GetGUMPHeaderByte2 ( void ) const

protectedvirtual

Definition at line 761 of file ancillarydata.cpp.

◆ GetGUMPHeaderByte3()

virtual uint8_t AJAAncillaryData::GetGUMPHeaderByte3 ( void ) const

inlineprotectedvirtual

Definition at line 1080 of file ancillarydata.h.

◆ GetInstanceCounts()

void AJAAncillaryData::GetInstanceCounts	(	uint32_t &	outConstructed,
		uint32_t &	outDestructed
	)

static

Definition at line 1767 of file ancillarydata.cpp.

◆ GetNumActiveInstances()

uint32_t AJAAncillaryData::GetNumActiveInstances ( void )

static

Definition at line 1784 of file ancillarydata.cpp.

◆ GetNumConstructed()

uint32_t AJAAncillaryData::GetNumConstructed ( void )

static

Definition at line 1793 of file ancillarydata.cpp.

◆ GetNumDestructed()

uint32_t AJAAncillaryData::GetNumDestructed ( void )

static

Definition at line 1802 of file ancillarydata.cpp.

◆ GetPayloadByteAtIndex()

uint8_t AJAAncillaryData::GetPayloadByteAtIndex ( const uint32_t inIndex0 ) const

virtual

Parameters

[in] inIndex0 Specifies the zero-based index value. This should be less than GetDC's result.

Returns: The payload data byte at the given zero-based index (or zero if the index value is invalid).

Definition at line 470 of file ancillarydata.cpp.

◆ GetPayloadData() [1/3]

AJAStatus AJAAncillaryData::GetPayloadData	(	uint8_t *	pBuffer,
		const uint32_t	inByteCapacity
	)		const

virtual

Copies my payload data into an external buffer.

Parameters

[in]	pBuffer	Specifies a valid, non-null starting address to where the payload data is to be copied.
[in]	inByteCapacity	Specifies the maximum number of bytes that can be safely copied into the external buffer.

Returns: AJA_STATUS_SUCCESS if successful.

Definition at line 435 of file ancillarydata.cpp.

◆ GetPayloadData() [2/3]

AJAStatus AJAAncillaryData::GetPayloadData	(	UWordSequence &	outUDWs,
		const bool	inAddParity = `true`
	)		const

virtual

Appends my payload data onto the given UDW vector as 10-bit User Data Words (UDWs), adding parity as needed.

Parameters

[out]	outUDWs	The 10-bit UDW vector to be appended to.
[in]	inAddParity	If true, each UDW will have even parity added.

Returns: AJA_STATUS_SUCCESS if successful.

Definition at line 448 of file ancillarydata.cpp.

◆ GetPayloadData() [3/3]

virtual const uint8_t* AJAAncillaryData::GetPayloadData ( void ) const

inlinevirtual

Returns: A const pointer to my payload buffer.

Definition at line 788 of file ancillarydata.h.

◆ GetRawPacketSize()

AJAStatus AJAAncillaryData::GetRawPacketSize ( uint32_t & outPacketSize ) const

virtual

Returns the number of "raw" ancillary data bytes that will be generated by AJAAncillaryData::GenerateTransmitData (for playback mode).

Parameters

[out] outPacketSize Receives the size (in bytes) of the packet I will generate.

Returns: AJA_STATUS_SUCCESS if successful.

Definition at line 624 of file ancillarydata.cpp.

◆ GetStreamInfo()

uint16_t AJAAncillaryData::GetStreamInfo ( void ) const

virtual

Returns: My 7-bit stream info (if relevant)

Definition at line 211 of file ancillarydata.cpp.

◆ GotValidReceiveData()

virtual bool AJAAncillaryData::GotValidReceiveData ( void ) const

inlinevirtual

Returns: True if I think I have valid ancillary data; otherwise false.

This result will only be trustworthy if I'm an AJAAncillaryData subclass (e.g. AJAAncillaryData_Cea708), and my ParsePayloadData method was previously called, to determine whether or not my packet data is legit or not. Typically, AJAAncillaryDataFactory::GuessAncillaryDataType is called to ascertain a packet's AJAAncDataType, then AJAAncillaryDataFactory::Create is used to instantiate the specific AJAAncillaryData subclass instance. This is done automatically by AJAAncillaryList::AddReceivedAncillaryData.

Definition at line 874 of file ancillarydata.h.

◆ HasStreamInfo()

virtual bool AJAAncillaryData::HasStreamInfo ( void ) const

inlinevirtual

Returns: True if I have valid DataLink/DataStream stream information (rather than unknown).

Definition at line 610 of file ancillarydata.h.

◆ IDAsString()

string AJAAncillaryData::IDAsString ( void ) const

virtual

Returns: A string that describes what kind of packet I am.

Definition at line 1323 of file ancillarydata.cpp.

◆ Init()

void AJAAncillaryData::Init ( void )

protected

Definition at line 124 of file ancillarydata.cpp.

◆ InitWithReceivedData() [1/3]

AJAStatus AJAAncillaryData::InitWithReceivedData	(	const std::vector< uint8_t > &	inData,
		const AJAAncDataLoc &	inLocationInfo
	)

virtual

Initializes me from "raw" ancillary data received from hardware (ingest) – see SDI Anc Buffer Data Format.

Parameters

[in]	inData	Specifies the "raw" packet data.
[in]	inLocationInfo	Specifies the default location info.

Returns: AJA_STATUS_SUCCESS if successful.

Definition at line 611 of file ancillarydata.cpp.

◆ InitWithReceivedData() [2/3]

AJAStatus AJAAncillaryData::InitWithReceivedData	(	const uint8_t *	pInData,
		const size_t	inMaxBytes,
		const AJAAncDataLoc &	inLocationInfo,
		uint32_t &	outPacketByteCount
	)

virtual

Initializes me from "raw" ancillary data received from hardware (ingest) – see SDI Anc Buffer Data Format.

Parameters

[in]	pInData	Specifies the starting address of the "raw" packet data that was received from the AJA device.
[in]	inMaxBytes	Specifies the maximum number of bytes left in the source buffer.
[in]	inLocationInfo	Specifies the default location info.
[out]	outPacketByteCount	Receives the size (in bytes) of the parsed packet.

Returns: AJA_STATUS_SUCCESS if successful.

Definition at line 500 of file ancillarydata.cpp.

◆ InitWithReceivedData() [3/3]

AJAStatus AJAAncillaryData::InitWithReceivedData	(	const ULWordSequence &	inData,
		uint16_t &	inOutStartIndex,
		const bool	inIgnoreChecksum = `false`
	)

virtual

Initializes me from the given 32-bit IP packet words received from hardware (ingest).

Parameters

[in]	inData	Specifies the "raw" packet data (in network byte order).
	inOutStartIndex	On entry, specifies the zero-based starting index number of the first 32-bit word associated with this Ancillary data packet. On exit, if successful, receives the zero-based starting index number of the first 32-bit word associated with the NEXT packet that may be in the vector.
[in]	inIgnoreChecksum	If true, ignores checksum failures. Defaults to false (don't ignore).

Returns: AJA_STATUS_SUCCESS if successful.

Definition at line 946 of file ancillarydata.cpp.

◆ operator!=()

virtual bool AJAAncillaryData::operator!= ( const AJAAncillaryData & inRHS ) const

inlinevirtual

Parameters

[in] inRHS The packet I am to be compared with.

Returns: True if I differ from the RHS packet.

Definition at line 657 of file ancillarydata.h.

◆ operator=()

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

virtual

Definition at line 1465 of file ancillarydata.cpp.

◆ operator==()

bool AJAAncillaryData::operator== ( const AJAAncillaryData & inRHS ) const

virtual

Parameters

[in] inRHS The packet I am to be compared with.

Returns: True if I'm identical to the RHS packet.

Definition at line 1484 of file ancillarydata.cpp.

◆ ParsePayloadData()

AJAStatus AJAAncillaryData::ParsePayloadData ( void )

virtual

Parses (interprets) the "local" ancillary data from my payload data.

Note: This method is overridden by specific packet types (e.g. AJAAncillaryData_Cea608_Vanc).

Returns: AJA_STATUS_SUCCESS if successful.

Reimplemented in AJAAncillaryData_Timecode_ATC, AJAAncillaryData_Cea608_Vanc, AJAAncillaryData_Cea608_Line21, AJAAncillaryData_Timecode_VITC, AJAAncillaryData_FrameStatusInfo524D, AJAAncillaryData_FrameStatusInfo5251, AJAAncillaryData_Cea708, AJAAncillaryData_HDR_HDR10, AJAAncillaryData_HDR_HLG, AJAAncillaryData_HDR_SDR, and AJAAncillaryData_Timecode.

Definition at line 489 of file ancillarydata.cpp.

◆ Print()

ostream & AJAAncillaryData::Print	(	std::ostream &	inOutStream,
		const bool	inDetailed = `false`
	)		const

virtual

Streams a human-readable representation of me to the given output stream.

Parameters

	inOutStream	Specifies the output stream.
[in]	inDetailed	Specify 'true' for a detailed representation; otherwise use 'false' for a brief one.

Returns: The given output stream.

Reimplemented in AJAAncillaryData_Timecode, AJAAncillaryData_Timecode_ATC, AJAAncillaryData_Cea608, AJAAncillaryData_Cea608_Vanc, AJAAncillaryData_Timecode_VITC, AJAAncillaryData_Cea708, AJAAncillaryData_FrameStatusInfo524D, AJAAncillaryData_FrameStatusInfo5251, AJAAncillaryData_HDR_HDR10, AJAAncillaryData_HDR_HLG, and AJAAncillaryData_HDR_SDR.

Definition at line 1306 of file ancillarydata.cpp.

◆ ResetInstanceCounts()

void AJAAncillaryData::ResetInstanceCounts ( void )

static

Definition at line 1777 of file ancillarydata.cpp.

◆ SetBufferFormat()

virtual AJAAncillaryData& AJAAncillaryData::SetBufferFormat ( const AJAAncBufferFormat inFmt )

inlinevirtual

Sets my originating buffer format.

Parameters

[in] inFmt Specifies my new buffer format.

Returns: A non-constant reference to myself.

Definition at line 768 of file ancillarydata.h.

◆ SetChecksum()

AJAStatus AJAAncillaryData::SetChecksum	(	const uint8_t	inChecksum8,
		const bool	inValidate = `false`
	)

virtual

Sets my 8-bit checksum. Note that it is not usually necessary to generate an 8-bit checksum, since the ANC Insertion hardware ignores this field and (for SMPTE-291 Anc packets) generates and inserts its own "proper" 9-bit SMPTE-291 checksum.

Parameters

[in]	inChecksum8	Specifies the new 8-bit checksum.
[in]	inValidate	If 'true', fails the function if the given checksum doesn't match the result of the AJAAncillaryData::Calculate8BitChecksum function. If 'false', does not validate the given checksum. Defaults to 'false'.

Returns: AJA_STATUS_SUCCESS if successful.

Definition at line 201 of file ancillarydata.cpp.

◆ SetDataCoding()

AJAStatus AJAAncillaryData::SetDataCoding ( const AJAAncDataCoding inCodingType )

virtual

Sets my ancillary data coding type (e.g. digital or analog/raw waveform).

Parameters

[in] inCodingType AJAAncDataCoding

Returns: AJA_STATUS_SUCCESS if successful.

Definition at line 328 of file ancillarydata.cpp.

◆ SetDataLocation()

AJAStatus AJAAncillaryData::SetDataLocation ( const AJAAncDataLoc & inLoc )

virtual

Sets my ancillary data "location" within the video stream.

Parameters

[in] inLoc Specifies the new AJAAncDataLoc value.

Returns: AJA_STATUS_SUCCESS if successful.

Definition at line 256 of file ancillarydata.cpp.

◆ SetDID()

AJAStatus AJAAncillaryData::SetDID ( const uint8_t inDataID )

virtual

Sets my Data ID (DID).

Parameters

[in] inDataID Specifies my new Data ID (for digital ancillary data, usually the "official" SMPTE packet ID).

Returns: AJA_STATUS_SUCCESS if successful.

Definition at line 188 of file ancillarydata.cpp.

◆ SetDIDSID()

virtual AJAStatus AJAAncillaryData::SetDIDSID ( const AJAAncDIDSIDPair & inDIDSID )

inlinevirtual

Sets both my Data ID (DID) and Secondary Data ID (SID).

Parameters

[in] inDIDSID The AJAAncDIDSIDPair that specifies both a DID and SID value.

Returns: AJA_STATUS_SUCCESS if successful.

Definition at line 694 of file ancillarydata.h.

◆ SetFrameID()

virtual AJAAncillaryData& AJAAncillaryData::SetFrameID ( const uint32_t inFrameID )

inlinevirtual

Sets my originating frame identifier.

Parameters

[in] inFrameID Specifies my new frame identifier.

Returns: A non-constant reference to myself.

Definition at line 761 of file ancillarydata.h.

◆ SetFromSMPTE334()

AJAStatus AJAAncillaryData::SetFromSMPTE334	(	const uint16_t *	pInData,
		const uint32_t	inNumWords,
		const AJAAncDataLoc &	inLocInfo
	)

virtual

Copies payload data from an external 16-bit source into local payload memory.

Parameters

[in]	pInData	A valid, non-NULL pointer to the external payload data to be copied (source). The upper 8 bits of each 16-bit word will be skipped and ignored.
[in]	inNumWords	Specifies the number of 16-bit words of payload data to copy.
[in]	inLocInfo	Specifies the anc data location information.

Returns: AJA_STATUS_SUCCESS if successful.

Definition at line 358 of file ancillarydata.cpp.

◆ SetLocationDataChannel()

AJAStatus AJAAncillaryData::SetLocationDataChannel ( const AJAAncDataChannel inChannel )

virtual

Sets my ancillary data "location" data channel value (Y or C).

Parameters

[in] inChannel Specifies my new data channel (Y or C) value.

Returns: AJA_STATUS_SUCCESS if successful.

Definition at line 297 of file ancillarydata.cpp.

◆ SetLocationDataStream()

AJAStatus AJAAncillaryData::SetLocationDataStream ( const AJAAncDataStream inStream )

virtual

Sets my ancillary data "location" data stream value (DS1,DS2...).

Parameters

[in] inStream Specifies my new data stream (DS1,DS2...) value.

Returns: AJA_STATUS_SUCCESS if successful.

Definition at line 285 of file ancillarydata.cpp.

◆ SetLocationHorizOffset()

AJAStatus AJAAncillaryData::SetLocationHorizOffset ( const uint16_t inOffset )

virtual

Sets my ancillary data "location" horizontal offset.

Parameters

[in] inOffset Specifies the new horizontal offset value.

See also: AJAAncDataLoc::SetHorizontalOffset.

Returns: AJA_STATUS_SUCCESS if successful.

Definition at line 319 of file ancillarydata.cpp.

◆ SetLocationLineNumber()

AJAStatus AJAAncillaryData::SetLocationLineNumber ( const uint16_t inLineNum )

virtual

Sets my ancillary data "location" frame line number.

Parameters

[in] inLineNum Specifies the new frame line number value (SMPTE line numbering).

Returns: AJA_STATUS_SUCCESS if successful.

Definition at line 309 of file ancillarydata.cpp.

◆ SetLocationVideoLink()

AJAStatus AJAAncillaryData::SetLocationVideoLink ( const AJAAncDataLink inLink )

virtual

Sets my ancillary data "location" within the video stream.

Parameters

[in] inLink Specifies the new video link value (A or B).

Returns: AJA_STATUS_SUCCESS if successful.

Definition at line 273 of file ancillarydata.cpp.

◆ SetPayloadByteAtIndex()

AJAStatus AJAAncillaryData::SetPayloadByteAtIndex	(	const uint8_t	inDataByte,
		const uint32_t	inIndex0
	)

virtual

Parameters

[in]	inDataByte	Specifies the data byte to be stored in my payload buffer.
[in]	inIndex0	Specifies the zero-based index value. This should be less than GetDC's result.

Returns: AJA_STATUS_SUCCESS if successful.

Definition at line 479 of file ancillarydata.cpp.

◆ SetPayloadData()

AJAStatus AJAAncillaryData::SetPayloadData	(	const uint8_t *	pInData,
		const uint32_t	inByteCount
	)

virtual

Copy data from external memory into my local payload memory.

Parameters

[in]	pInData	Specifies the address of the first byte of the external payload data to be copied (source).
[in]	inByteCount	Specifies the number of bytes of payload data to be copied.

Returns: AJA_STATUS_SUCCESS if successful.

Definition at line 342 of file ancillarydata.cpp.

◆ SetSID()

AJAStatus AJAAncillaryData::SetSID ( const uint8_t inSID )

virtual

Sets my Secondary Data ID (SID) - (aka the Data Block Number (DBN) for "Type 1" SMPTE-291 packets).

Parameters

[in] inSID Specifies my new secondary Data ID.

Returns: AJA_STATUS_SUCCESS if successful.

Definition at line 195 of file ancillarydata.cpp.

◆ Unpack8BitYCbCrToU16sVANCLine()

bool AJAAncillaryData::Unpack8BitYCbCrToU16sVANCLine	(	const void *	pInYUV8Line,
		U16Packet &	outU16YUVLine,
		const uint32_t	inNumPixels
	)

static

Converts a single line of NTV2_FBF_8BIT_YCBCR data from the given source buffer into an ordered sequence of uint16_t values that contain the resulting 10-bit even-parity data.

Parameters

[in]	pInYUV8Line	A valid, non-NULL pointer to the start of the VANC line in an NTV2_FBF_8BIT_YCBCR video buffer.
[out]	outU16YUVLine	Receives the converted 10-bit-per-component values as an ordered sequence of uint16_t values, which will include even parity and valid checksums.
[in]	inNumPixels	Specifies the length of the line to be converted, in pixels.

Returns: True if successful; otherwise false.

Note: If SMPTE ancillary data is detected in the video, this routine "intelligently" stretches it by copying the 8-bits to the LS 8-bits of the 10-bit output, recalculating parity and checksums as needed. (This emulates what NTV2 device firmware does during playout of NTV2_FBF_8BIT_YCBCR frame buffers with NTV2_VANCDATA_8BITSHIFT_ENABLE.); NTV2 firmware is expected to start the first anc packet at the first pixel position in the VANC line, and place subsequent packets, if any, in immediate succession, without any gaps. Therefore, a line that does not start with the 0x00/0xFF/0xFF packet header is assumed to not contain any packets. This saves a substantial amount of CPU time.

Definition at line 1666 of file ancillarydata.cpp.

Member Data Documentation

◆ m_ancType

AJAAncDataType AJAAncillaryData::m_ancType

protected

One of a known set of ancillary data types (or "Custom" if not identified)

Definition at line 1091 of file ancillarydata.h.

◆ m_bufferFmt

AJAAncBufferFormat AJAAncillaryData::m_bufferFmt

protected

My originating buffer format, if known.

Definition at line 1092 of file ancillarydata.h.

◆ m_checksum

uint8_t AJAAncillaryData::m_checksum

protected

My 8-bit checksum: DID + SID + DC + payload (w/o parity) [note: NOT the same as the 9-bit checksum in a SMPTE-291 packet!].

Definition at line 1086 of file ancillarydata.h.

◆ m_coding

AJAAncDataCoding AJAAncillaryData::m_coding

protected

Analog or digital data.

Definition at line 1088 of file ancillarydata.h.

◆ m_DID

uint8_t AJAAncillaryData::m_DID

protected

Official SMPTE ancillary packet ID (w/o parity)

Definition at line 1084 of file ancillarydata.h.

◆ m_frameID

uint32_t AJAAncillaryData::m_frameID

protected

ID of my originating frame, if known.

Definition at line 1093 of file ancillarydata.h.

◆ m_location

AJAAncDataLoc AJAAncillaryData::m_location

protected

Location of the ancillary data in the video stream (Y or C, HANC or VANC, etc.)

Definition at line 1087 of file ancillarydata.h.

◆ m_payload

ByteVector AJAAncillaryData::m_payload

protected

My payload data (DC = size)

Definition at line 1089 of file ancillarydata.h.

◆ m_rcvDataValid

bool AJAAncillaryData::m_rcvDataValid

protected

This is set true (or not) by ParsePayloadData()

Definition at line 1090 of file ancillarydata.h.

◆ m_SID

uint8_t AJAAncillaryData::m_SID

protected

Official SMPTE secondary ID (or DBN - w/o parity)

Definition at line 1085 of file ancillarydata.h.

◆ m_userData

uint64_t AJAAncillaryData::m_userData

protected

User data (for client use)

Definition at line 1094 of file ancillarydata.h.

The documentation for this class was generated from the following files:

/home/tcbuilder/buildAgent/work/df8e8cce5bebfd58/libajantv2/ajaanc/includes/ancillarydata.h
/home/tcbuilder/buildAgent/work/df8e8cce5bebfd58/libajantv2/ajaanc/src/ancillarydata.cpp

Public Types

Public Member Functions

Static Public Member Functions

Protected Types

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Printing & Debugging

Detailed Description

Member Typedef Documentation

◆ ByteVector

◆ ByteVectorConstIter

◆ ByteVectorIndex

◆ U16Packet

◆ U16Packets

Constructor & Destructor Documentation

◆ AJAAncillaryData() [1/3]

◆ AJAAncillaryData() [2/3]

◆ AJAAncillaryData() [3/3]

◆ ~AJAAncillaryData()

Member Function Documentation

◆ AddEvenParity()

◆ AllocDataMemory()

◆ AppendPayload() [1/2]

◆ AppendPayload() [2/2]

◆ AppendPayloadData()

◆ AsString()

◆ Calculate8BitChecksum()

◆ Calculate9BitChecksum()

◆ ChecksumOK()

◆ Clear()

◆ Clone()

◆ Compare()

◆ CompareWithInfo()

◆ DIDSIDToString()

◆ DumpPayload()

◆ FreeDataMemory()

◆ GeneratePayloadData()

◆ GenerateTransmitData() [1/3]

◆ GenerateTransmitData() [2/3]

◆ GenerateTransmitData() [3/3]

◆ GetAncPacketsFromVANCLine()

◆ GetGUMPHeaderByte1()

◆ GetGUMPHeaderByte2()

◆ GetGUMPHeaderByte3()

◆ GetInstanceCounts()

◆ GetNumActiveInstances()

◆ GetNumConstructed()

◆ GetNumDestructed()

◆ GetPayloadByteAtIndex()

◆ GetPayloadData() [1/3]

◆ GetPayloadData() [2/3]

◆ GetPayloadData() [3/3]

◆ GetRawPacketSize()

◆ GetStreamInfo()

◆ GotValidReceiveData()

◆ HasStreamInfo()

◆ IDAsString()

◆ Init()

◆ InitWithReceivedData() [1/3]

◆ InitWithReceivedData() [2/3]

◆ InitWithReceivedData() [3/3]

◆ operator!=()

◆ operator=()

◆ operator==()

◆ ParsePayloadData()

◆ Print()

◆ ResetInstanceCounts()

◆ SetBufferFormat()

◆ SetChecksum()

◆ SetDataCoding()

◆ SetDataLocation()

◆ SetDID()

◆ SetDIDSID()

◆ SetFrameID()

◆ SetFromSMPTE334()

◆ SetLocationDataChannel()

◆ SetLocationDataStream()

◆ SetLocationHorizOffset()

◆ SetLocationLineNumber()