View source for Project Eideticker/DeckLink Primer

For the first version of [[Project_Eideticker|Project Eideticker]], we are using a [http://www.blackmagic-design.com/products/decklinkhdextreme/ Blackmagic DeckLink HD Extreme 3D] to capture video data.  Here's a quick introduction to the card's capabilities and usage as they pertain to Eideticker.

== Capabilities ==

There are two major limitations in all Blackmagic cards, DeckLink or otherwise:

* They can only capture output at broadcast standards.  This means HDMI 720p and 1080p at standard refresh rates and a handful of other standards.  The important part here is that the output must be at a standard resolution, e.g. 1280x720 or 1920x1080.  Unlike many TVs, the cards will not crop or add border to output that is larger or smaller than the standard; it just won't capture at all.

* Capturing at 1080p50 and up can only be done at YUV 4:2:2, i.e., full 8-bit RGB is not possible. Supposedly capturing at 720p is possible with 10-bit RGB, but not 8-bit RGB, for reasons unknown (perhaps due to the fact that the 10-bit formats use their own codecs).

Unfortunately neither of these limitations were apparent in their marketing materials; we had to contact support to find out.

What this means: it's almost impossible to get a pixel-perfect capture of a device with this card.  The only potentially perfect solution with this card would a device that outputs full RGB at 720p and does not do any scaling (e.g. exactly a 720-pixel high screen, a cropped/bordered output, or the ability to treat the HDMI output as the primary output so Firefox can render at exactly 720p).

How this impacts Project Eideticker is unknown but a function of exactly what analyses we want to perform.

== Installation ==

The manual can be found at the card's [http://www.blackmagicdesign.com/support/detail?os=linux&sid=3945&pid=3985&leg=false support page] (I don't want to post a link directly to the manual in case they issue a new version and the URL changes).

The card has a plethora of adapters for various types of video input.  At the moment we only care about HDMI.  The HDMI inputs are on a separate slot, connected to the card via HDMI cables.  There is an input port and an output port.  They aren't labelled, but the input port is the one closest to the ePCI connector (e.g. closer to the motherboard).  The HDMI slot should be wired to match this.  See the Connection Diagrams on the support page linked above.

The drivers are available at the support page under the not-entirely-obvious name "Desktop Video for Linux".  The current version is 8.0.1.  The archive contains debs, rpms, and tarballs for various distros.  On Ubuntu, the drivers can be installed with <tt>dpkg -i</tt> and the appropriate (32-bit or 64-bit) deb filename.  This will install the kernel module, the shared libraries, a configuration app, and a firmware-updater app.  See the readme in the archive for more details on installation.

Before doing anything with the card, you'll need to run the configuration program <tt>BlackmagicControlPanel</tt>.  This utility is mostly used to activate particular hardware inputs and outputs, since not all can be active at the same time.  You'll need to select the option that includes HDMI input.

== MediaExpress ==

There is also a GUI program in the DesktopVideo package called MediaExpress.  It can be installed from a deb file in the same way.  MediaExpress can be useful to discover the DeckLink's capabilities and supported modes.

To run it from Linux, just enter <tt>MediaExpress</tt> in a terminal.  For best results it requires a 1920x1200-resolution monitor.  It is still usable at lesser resolutions, although some of the UI will be cropped.

I used MediaExpress to verify that I could do a basic capture and playback before I moved onto working directly with the SDK.  To do so, start the program and select Preferences from the Edit menu.  The top two drop downs control the input and output formats.  The DeckLink does ''not'' have automatic source-format detection, so you must select the correct format, or nothing will appear in the capture/playback pane.

For example, to capture from the LG phone, ensure that the phone's HDMI setting is 1080p, then select 1080p 60 from MediaExpress's Preferences.  Your output choices are limited at 1080p60, so just select 8-bit YUV.  After clicking Ok, you should see a mirror of the phone's screen in the top-right pane.  Any changes on the phone's screen should be reflected in the display pane.  You can then use the Start Capture button or menu item to record raw video.  Any video you record can be played back by double clicking on the clip listing in the top-left pane.  You can also grab screenshots, which are saved as TARGA files.

== The SDK ==

The Blackmagic SDK consists of C++ header and source files to build applications using Blackmagic cards along with some samples.  It, and the associated documentation, can be downloaded from http://www.blackmagic-design.com/support/sdks/

'''Important''': The latest version of the SDK (8.5) is ahead of the latest Linux DeckLink drivers (8.0.1).  I couldn't get the new SDK working on Linux.  It might be possible, but it looks like it would involve changing a lot of the SDK files.  Instead I recommend downloading the 8.0 release of the SDK, which works perfectly.

There is no installation procedure for the SDK; just put the .h and .cpp files somewhere and build them into your project.  Since they are free to distribute (via an MIT-like license), I included them in the Eideticker capture-app code.

The SDK has extensive documentation.  I won't go into depth, but the basic architecture is callback-based.  For capturing, the application provides a callback object and starts the capture stream; each frame causes the callback to be fired with the frame data.

Even more useful are several sample applications.  In particular, the Capture app was extremely helpful.  The Eideticker capture app is largely based on the Capture sample, with unnecessary features removed (audio and 3D capture) and a few little things added in.