1 Desktop Video SDK¶
1.1 Scope¶
1.1.1 Supported Products¶
The Desktop Video SDK provides programmatic access to a wide variety of Blackmagic Design products. The term “Desktop Video” is used as a generic term to refer to the supported products.
Playback and Capture support is provided for devices in the DeckLink, Intensity, UltraStudio and Teranex product lines. Capture support is provided for the Cintel Scanner, Cinema Camera and Hyperdeck Studio products.
1.1.2 Supported Operating Systems¶
The Desktop Video SDK is supported on macOS, Windows and Linux operating systems. The release notes supplied with the Desktop Video packages include details of supported operating system versions.
1.1.3 3rd Party Product and Feature Support¶
1.1.3.1 NVIDIA GPUDirect Support¶
NVIDIA GPUDirect is supported on Windows and Linux for x86_64 architecture where those platforms are also supported by NVIDIA. GPUDirect support requires the use of the DVP library supplied by NVIDIA.
See the LoopThroughWithOpenGLCompositing for a detailed example of integrating the DeckLink API and NVIDIA GPUDirect.
1.1.3.2 AMD DirectGMA Support¶
AMD DirectGMA is supported on Windows and Linux for x86_64 architecture where those platforms are also supported by AMD. DirectGMA support requires the use of the GL_AMD_pinned_memory GL extension supported by compatible AMD OpenGL drivers.
See the LoopThroughWithOpenGLCompositing for a detailed example of integrating the DeckLink API and AMD DirectGMA.
1.2 Custom Windows Installations¶
1.2.1 Supported Features¶
On Windows machines, it is possible to selectively install individual components, henceforth referred to as features, of the Desktop Video package from a terminal with the msiexec command. The following is a list of features that can be installed.
Base - The minimum set of drivers for capture and playback.
Plugins - Plugins for Avid Media Composer and Adobe Creative Cloud.
DirectShow - DirectShow and WDM filters.
Utility - Graphical tools for device setup and update.
Applications - Off the shelf applications, such as LiveKey, Media Express and Disk Speed Test.
ASIO - Audio Stream Input Output, providing native Windows audio support.
1.2.2 Examples¶
Install DesktopVideo with only the Desktop Video Setup and Desktop Video Updater tools:
msiexec /i PATH_TO_DESKTOP_VIDEO_MSI ADDLOCAL=Utility
This installs the Utility feature AND the Base feature. Any features which are already installed will be unchanged.
Install multiple features at once:
msiexec /i PATH_TO_DESKTOP_VIDEO_MSI ADDLOCAL=Plugins,Utility
Remove a feature:
msiexec /i PATH_TO_DESKTOP_VIDEO_MSI REMOVE=Plugins
This removes the Plugins feature. The Base feature and any other installed features are retained.
To uninstall all Desktop Video features, including the Base feature:
msiexec /x PATH_TO_DESKTOP_VIDEO_MSI
1.3 API Design¶
1.3.1 Object Interfaces¶
The API provides high-level interfaces to allow capture & playback of audio and video with frame buffering and scheduling as well as low-level interfaces for controlling features available on different capture card models.
Functionality within the API is accessed via “object interfaces”. Each object in the system may inherit from and be accessed via a number of object interfaces. Typically the developer is able to interact with object interfaces and leave the underlying objects to manage themselves.
Each object interface class has a Globally Unique ID (GUID) called an “Interface ID”. On platforms with native COM support, an IID may be used to obtain a handle to an exported interface object from the OS, which is effectively an entry point to an installed API.
Each interface may have related interfaces that are accessed by providing an IID to an existing object interface (see IUnknown::QueryInterface()). This mechanism allows new interfaces to be added to the API without breaking API or ABI compatibility. IUnknown::QueryInterface() should be used for accessing related interfaces, rather than dynamic casting.
1.3.2 Reference Counting¶
The API uses reference counting to manage the life cycle of object interfaces. The developer may need to add or remove references on object interfaces (see IUnknown::AddRef() and IUnknown::Release()) to influence their life cycle as appropriate in the application.
1.3.3 Interface Stability¶
The SDK provides a set of stable interfaces for accessing Blackmagic Design hardware. Whilst the published interfaces will remain stable, developers need to be aware of some issues they may encounter as new products, features and interfaces become available.
1.3.3.1 New Interfaces¶
Major pieces of new functionality may be added to the SDK as a whole new object interface. Already released applications will not be affected by the additional functionality. Developers making use of the new functionality should be sure to check the return of CoCreateInstance and/or QueryInterface as these interfaces will not be available on users systems which are running an older release of the Blackmagic drivers.
Developers can choose to either reduce the functionality of their application when an interface is not available, or to notify the user that they must install a later version of the Blackmagic drivers.
1.3.3.2 Updated Interfaces¶
As new functionality is added to the SDK, some existing interfaces may need to be modified or extended. To maintain compatibility with released software, the original interface will be deprecated but will remain available and maintain its unique identifier (IID). The replacement interface will have a new identifier and remain as similar to the original as possible.
1.3.3.3 Deprecated Interfaces¶
Interfaces which have been replaced with an updated version, or are no longer recommended for use are “deprecated”. Deprecated interfaces are moved out of the main interface description files into an interface description file named according to the release in which the interface was deprecated. Deprecated interfaces are also renamed with a suffix indicating the release prior to the one in which they were deprecated.
It is recommended that developers update their applications to use the most recent SDK interfaces when they release a new version of their applications. As an interim measure, developers may include the deprecated interface descriptions, and updating the names of the interfaces in their application to access the original interface functionality.
1.3.3.4 Removed Interfaces¶
Interfaces that have been deprecated for some time may eventually be removed in a major driver update if they become impractical to support.
1.3.4 IUnknown Interface¶
Each API interface is a subclass of the standard COM base class – IUnknown. The IUnknown object interface provides reference counting and the ability to look up related interfaces by interface ID. The interface ID mechanism allows interfaces to be added to the API without impacting existing applications.
1.3.4.1 IUnknown::QueryInterface method¶
-
HRESULT IUnknown::QueryInterface(REFIID id, void **outputInterface);¶
The QueryInterface method looks up a related interface of an object interface.
- Parameters:
id – Interface ID of interface to look up
outputInterface – New object interface or NULL on failure
- Return values:
E_NOINTERFACE – Interface was not found.
S_OK – Success