2.4.7 Ancillary Data Functionality

The capture or output of ancillary data is supported by certain DeckLink device models. Ancillary data support is only available for SDI, Optical SDI, Ethernet and Optical Ethernet connections. The lines of ancillary data that are accessible are dependent upon the model of the DeckLink device.

2.4.7.1 Ancillary Data Capture

When capturing ancillary data from the HANC data space, an application should first perform the following additional steps:

• Check that HANC capture is supported by the target by calling IDeckLinkProfileAttributes::GetFlag() with attribute BMDDeckLinkSupportsHANCInput.

• Check whether the target requires DID/SDID filtering of the HANC packets by calling IDeckLinkProfileAttributes::GetFlag() with attribute BMDDeckLinkHANCRequiresInputFilterConfiguration.

• If HANC input filtering is required, the application should configure the filters by specifying up to 4 DID/SDID pairs. The HANC DID/SDID filters can be configured by calling IDeckLinkConfiguration::SetInt() with configuration IDs bmdDeckLinkConfigHANCInputFilter1 through to bmdDeckLinkConfigHANCInputFilter4.

When capturing ancillary data from the VANC data space, an application should first perform the following additional steps:

• Call IDeckLinkProfileAttributes::GetFlag() with attribute BMDDeckLinkVANCRequires10BitYUVVideoFrames to check whether the target supports VANC capture only when the active picture and ancillary data are both 10-bit YUV pixel format.

An application performing either VANC or HANC capture should perform the following steps:

• IDeckLinkInput::EnableVideoInput()

• IDeckLinkInput::SetCallback()

• IDeckLinkInput::StartStreams()

While streams are running:

• Receive calls to IDeckLinkInputCallback::VideoInputFrameArrived()

Inside the callback:

• Call IUnknown::QueryInterface() on the IDeckLinkVideoInputFrame object with IID_IDeckLinkVideoFrameAncillaryPackets. As the IDeckLinkVideoFrameAncillaryPackets object has a reference to the IDeckLinkVideoInputFrame input frame, ensure that it is released in a timely manner, otherwise the capture will run out of available frames.

• If the DID/SDID for the ancillary packet is known, then call IDeckLinkVideoFrameAncillaryPackets::GetFirstPacketByID(). Check that S_OK is returned to confirm an ancillary packet with matching DID/SDID is found.

• Otherwise, enumerate the ancillary packets in the video frame by calling IDeckLinkVideoFrameAncillaryPackets::GetPacketIterator().

• Call IDeckLinkAncillaryPacket::GetBytes(). The output packet payload will be converted to the requested BMDAncillaryPacketFormat.

2.4.7.2 Ancillary Data Output

• When outputting ancillary data to the HANC data space, an application should check that HANC output is supported by the target by calling IDeckLinkProfileAttributes::GetFlag() with attribute BMDDeckLinkSupportsHANCOutput.

• Call IDeckLinkOutput::EnableVideoOutput(). If the application is outputting VANC, then this call should set bmdVideoOutputVANC flag.

• If outputting VANC, call IDeckLinkProfileAttributes::GetFlag() with the BMDDeckLinkVANCRequires10BitYUVVideoFrames flag to check whether the DeckLink hardware supports VANC only when the active picture and ancillary data are both 10-bit YUV pixel format.

• Create an ancillary packet object that subclasses IDeckLinkAncillaryPacket, implementing all methods of the IDeckLinkAncillaryPacket class.

• Implement IDeckLinkAncillaryPacket::GetBytes() to provide a pointer to packet data in playback operation. The packet payload data shall be implemented with at least one BMDAncillaryPacketFormat. The driver will automatically convert to the correct format on output.

• Create a video frame for output with IDeckLinkOutput::CreateVideoFrame() or IDeckLinkOutput::CreateVideoFrameWithBuffer().

• Call IUnknown::QueryInterface() on the IDeckLinkVideoFrame object with IID_IDeckLinkVideoFrameAncillaryPackets. As the IDeckLinkVideoFrameAncillaryPackets object has a reference to the IDeckLinkVideoFrame frame, ensure that it is released in a timely manner, otherwise the playback will run out of available frames.

• Call IDeckLinkVideoFrameAncillaryPackets::AttachPacket() to attach the ancillary packet to video frame for playback.

• IDeckLinkOutput::ScheduleVideoFrame()

• IDeckLinkOutput::StartScheduledPlayback()

Note

For applications outputting custom video frame objects that implement the IDeckLinkVideoFrame interface (for example for 3D playback or HDR metadata output), the class must provide a valid object when its IUnknown::QueryInterface() is called with IID_IDeckLinkVideoFrameAncillaryPackets. The return object interface from IUnknown::QueryInterface() should be obtained with CoCreateInstance with CLSID_CDeckLinkVideoFrameAncillaryPackets (Windows) or CreateVideoFrameAncillaryPacketsInstance (macOS and Linux).