“libajantv2” Class Library

This library contains the principal classes and data types that interface with the NTV2 device driver, plus a number of utility classes that deal with NTV2-specific data formats.

Most NTV2 functions and class methods return a bool value of true for “success” and false for “failure”. NTV2 functions and classes do not intentionally or explicitly throw exceptions. Under unusual and extreme conditions (e.g. memory exhaustion), it's possible for an exception to be thrown (e.g. std::bad_alloc).

Principal Classes

• CNTV2DeviceScanner — enumerates attached devices
• CNTV2Card — queries and/or controls a device
• CNTV2SignalRouter — a collection of signal routes that can be applied to a device
• NTV2FormatDescriptor — describes an NTV2 raster image
• NTV2Buffer — describes memory buffers and perform operations on them
• AUTOCIRCULATE_TRANSFER — Provides information used in CNTV2Card::AutoCirculateTransfer calls

Note

Avoid deriving subclasses from AJA-provided classes. AJA recommends using aggregation techniques to incorporate NTV2 functionality into your own classes.

CNTV2DeviceScanner Class

The CNTV2DeviceScanner class is used to enumerate or find available devices.

Example: Discovering all attached devices

CNTV2Card   device;
ULWord      ndx(0);
while (CNTV2DeviceScanner::GetDeviceAtIndex (ndx, device))
{
    //  The device instance is guaranteed to be open and valid if GetDeviceAtIndex returns true
    std::cout << ndx << ": " << device.GetDisplayName() << std::endl;
    ndx++;
}

• Static Functions
  • CNTV2DeviceScanner::GetDeviceAtIndex – returns an open CNTV2Card instance for the Nth device
  • CNTV2DeviceScanner::GetFirstDeviceWithID – returns an open CNTV2Card instance for the first device having a matching NTV2DeviceID
  • CNTV2DeviceScanner::GetFirstDeviceWithName – returns an open CNTV2Card instance for the first device whose model name contains a given string
  • CNTV2DeviceScanner::GetFirstDeviceWithSerial – returns an open CNTV2Card instance for the first device having a matching serial number

CNTV2Card Class

The CNTV2Card class is used to interrogate and control an NTV2 device. Normally an instance of this class is obtained from one of the CNTV2DeviceScanner class methods.

Note

For multiple, concurrent ingest or playout threads, for better performance, AJA recommends using separate per-thread CNTV2Card instances.

CNTV2Card has a very large number of instance methods that inquire about and/or control different aspects of the hardware, which can be organized into several API groups. Here are some examples (this list is not comprehensive):

• General Inquiry API
  • CNTV2Card::GetDisplayName to get the device display name
  • CNTV2Card::GetModelName to get the device model name
  • CNTV2Card::GetDriverVersionString to get the device driver version string
  • CNTV2Card::GetSerialNumber to get the device serial number
  • CNTV2Card::GetInstalledBitfileInfo to get the installed firmware bitfile info
  • CNTV2Card::GetRunningFirmwareDate to get the running firmware build date & time
• Widget Inquiry & Control
  • FrameStore Control
    • CNTV2Card::GetVideoFormat, CNTV2Card::SetVideoFormat to get or set the FrameStoreʼs video format
    • CNTV2Card::GetMode, CNTV2Card::SetMode to get or set the FrameStoreʼs mode (capture or playback)
    • CNTV2Card::GetFrameBufferFormat, CNTV2Card::SetFrameBufferFormat to get or set the FrameStoreʼs pixel format
    • CNTV2Card::GetOutputFrame, CNTV2Card::SetOutputFrame to get or set the FrameStoreʼs playback frame number
    • CNTV2Card::GetInputFrame, CNTV2Card::SetInputFrame to get or set the FrameStoreʼs capture frame number
    • CNTV2Card::GetVANCMode, CNTV2Card::SetVANCMode to get or set the FrameStoreʼs VANC mode (off, tall or taller)
    • CNTV2Card::GetVideoHOffset, CNTV2Card::SetVideoHOffset to get or set the FrameStoreʼs horizontal timing offset
    • CNTV2Card::GetVideoVOffset, CNTV2Card::SetVideoVOffset to get or set the FrameStoreʼs vertical timing offset
  • Mixer/Keyer API
    • CNTV2Card::GetMixerMode, CNTV2Card::SetMixerMode to get or set Mixer mode (foreground on or off, or mix with background)
    • CNTV2Card::GetMixerCoefficient, CNTV2Card::SetMixerCoefficient to get or set mix coefficient
    • CNTV2Card::GetMixerMatteColor, CNTV2Card::SetMixerMatteColor to get or set the matte color (if used)
  • LUT & Color Correction API
    • CNTV2Card::GetColorSpaceMethod, CNTV2Card::SetColorSpaceMethod gets or sets the CSC conversion method
    • CNTV2Card::GetColorSpaceRGBBlackRange, CNTV2Card::SetColorSpaceRGBBlackRange gets or sets the CSC RGB black range setting
    • CNTV2Card::ReadLUTTables, CNTV2Card::WriteLUTTables reads or writes the LUT tables
  • HDMI
    • HDMI API
      • CNTV2Card::GetHDMIInColorSpace, CNTV2Card::SetHDMIInColorSpace gets or sets the HDMI input colorspace (YCbCr or RGB)
      • CNTV2Card::GetHDMIInputRange, CNTV2Card::SetHDMIInputRange gets or sets the HDMI input range (full or SMPTE)
      • CNTV2Card::GetHDMIInBitDepth, CNTV2Card::SetHDMIInBitDepth gets or sets the HDMI input bit depth (8/10/12 bits)
      • CNTV2Card::GetHDMIOutColorSpace, CNTV2Card::SetHDMIOutColorSpace gets or sets the HDMI output colorspace (YCbCr or RGB)
      • CNTV2Card::GetHDMIOutRange, CNTV2Card::SetHDMIOutRange gets or sets the HDMI output range (full or SMPTE)
      • CNTV2Card::GetHDMIOutBitDepth, CNTV2Card::SetHDMIOutBitDepth gets or sets the HDMI output bit depth (8/10/12 bits)
      • CNTV2Card::GetHDMIOutProtocol, CNTV2Card::SetHDMIOutProtocol gets or sets the HDMI output protocol (HDMI or DVI)
      • CNTV2Card::GetHDMIOutAudioRate, CNTV2Card::SetHDMIOutAudioRate gets or sets the HDMI output audio rate (48/96/192 kHz)
    • HDMI HDR Support API
      • CNTV2Card::EnableHDMIHDR enables or disables HDMI HDR
      • CNTV2Card::GetHDMIHDRConstantLuminance, CNTV2Card::SetHDMIHDRConstantLuminance gets or sets HDMI HDR constant luminance setting
      • CNTV2Card::GetHDMIHDRGreenPrimaryX, CNTV2Card::GetHDMIHDRGreenPrimaryY, CNTV2Card::SetHDMIHDRGreenPrimaryX, CNTV2Card::SetHDMIHDRGreenPrimaryY gets or sets HDMI HDR display mastering data for green primary X and Y, respectively.
      • CNTV2Card::GetHDMIHDRRedPrimaryX, CNTV2Card::GetHDMIHDRRedPrimaryY, CNTV2Card::SetHDMIHDRRedPrimaryX, CNTV2Card::SetHDMIHDRRedPrimaryY gets or sets HDMI HDR display mastering data for red primary X and Y, respectively.
      • CNTV2Card::GetHDMIHDRBluePrimaryX, CNTV2Card::GetHDMIHDRBluePrimaryY, CNTV2Card::SetHDMIHDRBluePrimaryX, CNTV2Card::SetHDMIHDRBluePrimaryY gets or sets HDMI HDR display mastering data for blue primary X and Y, respectively.
  • Up/Down Conversion API
    • CNTV2Card::GetConversionMode, CNTV2Card::SetConversionMode to get or set the UDCʼs conversion mode
    • CNTV2Card::GetConverterInStandard, CNTV2Card::SetConverterInStandard to get or set the UDCʼs input video standard
    • CNTV2Card::GetConverterInRate, CNTV2Card::SetConverterInRate to get or set the UDCʼs input video frame rate
    • CNTV2Card::GetConverterOutStandard, CNTV2Card::SetConverterOutStandard to get or set the UDCʼs output video standard
    • CNTV2Card::GetConverterOutRate, CNTV2Card::SetConverterOutRate to get or set the UDCʼs output video frame rate
• Audio
  • Audio System API
    • CNTV2Card::GetAudioLoopBack, CNTV2Card::SetAudioLoopBack to get or set an audio systemʼs loopback mode
    • CNTV2Card::StartAudioOutput, CNTV2Card::StopAudioOutput to start or stop playback from an audio system
    • CNTV2Card::StartAudioInput, CNTV2Card::StopAudioInput to start or stop an audio system capturing/recording
    • CNTV2Card::GetAudioSystemInputSource, CNTV2Card::SetAudioSystemInputSource to set an audio systemʼs input source
    • CNTV2Card::GetSDIOutputAudioSystem, CNTV2Card::SetSDIOutputAudioSystem to set an SDI outputʼs playback audio system
  • Audio Mixer API
    • CNTV2Card::GetAudioMixerInputAudioSystem, CNTV2Card::SetAudioMixerInputAudioSystem to get or set the audio mixerʼs input/source audio system
    • CNTV2Card::GetAudioMixerInputGain, CNTV2Card::SetAudioMixerInputGain to get or set the audio mixerʼs input gain setting
    • CNTV2Card::GetAudioMixerOutputGain, CNTV2Card::SetAudioMixerOutputGain to get or set the audio mixerʼs output gain setting
• AutoCirculate API
  • CNTV2Card::AutoCirculateGetStatus to inquire about the AUTOCIRCULATE_STATUS of a given channel
  • CNTV2Card::AutoCirculateInitForInput to prepare a given channel for capture/input
  • CNTV2Card::AutoCirculateInitForOutput to prepare a given channel for playback/output
  • CNTV2Card::AutoCirculateStart, CNTV2Card::AutoCirculateStop to start or stop streaming to/from a given channel
  • CNTV2Card::AutoCirculatePause, CNTV2Card::AutoCirculateResume to pause or resume streaming for a given channel
  • CNTV2Card::AutoCirculateTransfer to transfer a captured frame, or transfer a frame for playback
• Signal Routing API
  • CNTV2Card::ClearRouting to disconnect any/all connected routes between widgets on the device
  • CNTV2Card::Connect, CNTV2Card::Disconnect to make or break widget connections
  • CNTV2Card::GetConnections gets the current widget routing connections
  • CNTV2Card::ApplySignalRoute applies a set of widget routing connections
• DMA Transfer API
  • CNTV2Card::DMAReadFrame, CNTV2Card::DMAWriteFrame to read or write a frame of video
  • CNTV2Card::DMAReadAudio, CNTV2Card::DMAWriteAudio to read or write audio samples
  • CNTV2Card::DMAReadAnc, CNTV2Card::DMAAnc to read or write ancillary data
  • CNTV2Card::DMABufferLock, CNTV2Card::DMABufferUnlock to accelerate DMA performance by locking down or unlocking a host buffer into physical memory
• Timecode APIs
  • RP-188
    • CNTV2Card::GetRP188Source, CNTV2Card::SetRP188Source to get or set the timecode source
    • CNTV2Card::GetRP188SourceFilter, CNTV2Card::SetRP188SourceFilter to get or set the timecode source filter
    • CNTV2Card::GetRP188Data, CNTV2Card::SetRP188Data to read or write an incoming or outgoing timecode value
  • Analog LTC
    • CNTV2Card::ReadAnalogLTCInput, CNTV2Card::WriteAnalogLTCOutput to read the analog LTC input timecode or write the output analog LTC timecode
• Interrupts & Events API
  • CNTV2Card::SubscribeInputVerticalEvent, CNTV2Card::UnsubscribeInputVerticalEvent to subscribe or unsubscribe to input vertical blanking interrupts
  • CNTV2Card::SubscribeOutputVerticalEvent, CNTV2Card::UnsubscribeOutputVerticalEvent to subscribe or unsubscribe to output vertical blanking interrupts
  • CNTV2Card::WaitForInputVerticalInterrupt, CNTV2Card::WaitForOutputVerticalInterrupt to sleep until the next input or output frame VBI
  • CNTV2Card::WaitForInputFieldID, CNTV2Card::WaitForOutputFieldID to sleep until the next input or output field VBI
• SDI Bypass Relay API
  • CNTV2Card::GetSDIRelayPosition gets the current position of the connector pair relay
  • CNTV2Card::GetSDIWatchdogEnable, CNTV2Card::SetSDIWatchdogEnable to get or set the connector pair relay watchdog timer control
  • CNTV2Card::GetSDIWatchdogTimeout, CNTV2Card::SetSDIWatchdogTimeout to get or set the connector pair relay watchdog timer timeout value
  • CNTV2Card::KickSDIWatchdog resets the connector pair relay watchdog timer
• RS-422 Serial Port API
  • CNTV2Card::GetRS422BaudRate, CNTV2Card::SetRS422BaudRate gets or sets the serial port baud rate
  • CNTV2Card::GetRS422Parity, CNTV2Card::SetRS422Parity gets or sets the serial port parity
• Ancillary Data API
  • CNTV2Card::AncInsertIsEnabled, CNTV2Card::AncInsertSetEnable queries if the Anc inserter is enabled for anc data playback, or sets it enabled/disabled.
  • CNTV2Card::AncInsertSetComponents enables or disables Anc insertion components
  • CNTV2Card::AncInsertSetReadParams, CNTV2Card::AncInsertSetField2ReadParams configures the Anc inserter to output F1 or F2 anc data into the next outgoing field/frame.
  • CNTV2Card::AncExtractIsEnabled, CNTV2Card::AncExtractSetEnable queries if the Anc extractor is enabled for anc data capture, or sets it enabled/disabled.
  • CNTV2Card::AncExtractSetComponents enables or disables Anc extractor components
  • CNTV2Card::AncExtractSetWriteParams, CNTV2Card::AncExtractSetField2WriteParams configures the Anc extractor to capture F1 or F2 anc data into the next incoming field/frame.

Example: Read FrameStore 1 Control Register

CNTV2Card device;
if (CNTV2DeviceScanner::GetDeviceAtIndex (0, device))
{
    ULWord value(0);
    device.ReadRegister(1, value);
}

Device Features API

The “NTV2Device…” functions describe AJA NTV2 device capabilities. All of the functions accept an NTV2DeviceID parameter that identifies the AJA device model (and in many cases firmware personality) of interest.

Note

Starting in SDK 17.1, this ancient API is slowly starting to be phased out, due to the necessity of supporting plugins and other types of devices, including virtual ones, that cannot always have an NTV2DeviceID. Going forward, device feature inquiries should be directed to the device itself via CNTV2DriverInterface::IsSupported, CNTV2DriverInterface::GetNumSupported and CNTV2DriverInterface::GetSupportedItems. There is also a convenient DeviceCapabilities class, obtained by calling CNTV2Card::features. See Device Features for more information.

A device need not be installed in or attached to the host to use these functions.

See also Determining Firmware Features for more information.

‘CanDo’ Functions

These functions have names starting with “NTV2DeviceCanDo…” and return a bool value that answers Yes or No for a particular device capability. Most of them accept a single NTV2DeviceID parameter, like NTV2DeviceCanDoAnalogAudio, which answers true if the device is capable of working with analog audio. A smaller set of functions accept two parameters: the NTV2DeviceID parameter, and a second enumeration parameter, for determining if a device is capable of working with a particular video format (e.g., NTV2DeviceCanDoVideoFormat) or frame buffer format (NTV2DeviceCanDoFrameBufferFormat), etc.

For example, to find out which Thunderbolt-connected devices support NTV2_FBF_10BIT_RGB, you can code the following:

const NTV2DeviceIDSet  supportedDeviceIDs (::NTV2GetSupportedDevices());
NTV2DeviceIDSet        deviceIDsWithThunderboltAndRGB10;
for (NTV2DeviceIDSetConstIter it(supportedDeviceIDs.begin());  it != supportedDeviceIDs.end();  ++it)
{
    if (::NTV2DeviceCanDoThunderbolt(*it)  &&  ::NTV2DeviceCanDoFrameBufferFormat(*it, NTV2_FBF_10BIT_RGB))
        deviceIDsWithThunderboltAndRGB10.push_back (*it);
}

‘Has’ Functions

These functions are similar to the “Can Do” functions. They also return a bool value that answers Yes or No for a particular device capability. For example, you may want to know if a device has bi-directional SDI connectors:

CNTV2Card   theDevice;
NTV2Channel outputChannel(NTV2_CHANNEL2);
. . .
if (::NTV2DeviceHasBiDirectionalSDI(theDevice.GetDeviceID())
    theDevice.SetSDITransmitEnable(outputChannel, true);

‘GetNum’ Functions

These functions return a count of a particular device feature. For example, to find out which devices have at least one HDMI output:

const NTV2DeviceIDSet  supportedDeviceIDs(::NTV2GetSupportedDevices());
NTV2DeviceIDSet        deviceIDsWithHDMIOut;
for (NTV2DeviceIDSetConstIter it(supportedDeviceIDs.begin());  it != supportedDeviceIDs.end();  ++it)
{
    if (::NTV2DeviceGetNumHDMIVideoOutputs(*it) > 0)
        deviceIDsWithHDMIOut.push_back(*it);
}

CNTV2SignalRouter Class

The CNTV2SignalRouter class is used to help perform Widget Signal Routing.

• Helper Functions – declared in ntv2signalrouter.h
  • Get…InputXpt… Helpers – These return NTV2InputXptID values
    • GetFrameBufferInputXptFromChannel – returns an NTV2InputXptID for a given FrameStore
    • GetCSCInputXptFromChannel – returns an NTV2InputXptID for a given CSC
    • GetLUTInputXptFromChannel – returns an NTV2InputXptID for a given LUT
    • GetDLInInputXptFromChannel – returns an NTV2InputXptID for a given Dual-Link Input
    • GetDLOutInputXptFromChannel – returns an NTV2InputXptID for a given Dual-Link Output
    • ::GetOutputDestInputXptFromChannel – returns an NTV2InputXptID for a given NTV2OutputDestination
    • GetSDIOutputInputXpt – returns an NTV2InputXptID for a given SDI Output
    • GetMixerFGInputXpt – returns an NTV2InputXptID for a given Mixerʼs foreground
    • GetMixerBGInputXpt – returns an NTV2InputXptID for a given Mixerʼs background
    • GetTSIMuxInputXptFromChannel – returns an NTV2InputXptID for a given TSI Mux
  • Get…OutputXpt… Helpers – These return NTV2OutputXptID values
    • GetCSCOutputXptFromChannel – returns an NTV2OutputXptID for a given CSC
    • GetLUTOutputXptFromChannel – returns an NTV2OutputXptID for a given CSC
    • GetFrameBufferOutputXptFromChannel – returns an NTV2OutputXptID for a given FrameStore
    • GetInputSourceOutputXpt – returns an NTV2OutputXptID for a given NTV2InputSource
    • GetSDIInputOutputXptFromChannel – returns an NTV2OutputXptID for a given SDI Input
    • GetDLOutOutputXptFromChannel – returns an NTV2OutputXptID for a given Dual-Link Output
    • GetDLInOutputXptFromChannel – returns an NTV2OutputXptID for a given Dual-Link Input
    • GetMixerOutputXptFromChannel – returns an NTV2OutputXptID for a given Mixer

See Widget Signal Routing for more details.