Blackmagic Design DeckLink DirectShow Documentation

DeckLink DirectShow Documentation

DeckLink DirectShow Documentation

Programmatic access to the Blackmagic Design range of DeckLink cards is available under Windows via the Microsoft DirectShow environment. DirectShow is a high level environment dedicated to media streaming and manipulation that enables your applications perform high-quality video and audio playback or capture.

The Blackmagic Design DeckLink DirectShow library supports a number of filters that provide unrestricted access and control of all the features and technology available on the DeckLink, Multibridge and Intensity range of products. Four filters encapsulate the four operational areas of the card; Video Capture, Audio Capture, Video Render and Audio Render. The two Motion-JPEG filters handling compression and decompression of Motion-JPEG bit streams. Two filters are available for reading and writing sequences of stills and one filter is used for resizing 1440x1080 video to 1920x1080. This filter makes it possible to play HDV on Blackmagic Design hardware. The Blackmagic Design Decoder (DMO) enables various conversions for optimal storage or playback of video clips.

The DeckLink DirectShow documentation is divided into the following sections:

  • Introduction to DeckLink DirectShow library
  • DeckLink FAQ
  • DirectShow Filters
  • Blackmagic Design Decoder
  • Video Formats
  • Interface Reference
  • Samples


Introduction to DeckLink DirectShow Library

The DeckLink DirectShow library exposes all of the functionality of the range of DeckLink cards via a suite of DirectShow filters and a DirectX Media Object (DMO). DirectShow is a high level dedicated video and audio environment that enables the streaming of video and audio samples from a source to a destination via a series of operations (filters).

The nine DeckLink DirectShow filters consist of three source filters; Decklink Video Capture , Decklink Audio Capture and Decklink Still Sequence Source, three render (destination) filters; Decklink Video Render , Decklink Audio Render and Decklink Still Sequence Sink, two filters that implement Motion-JPEG compression and decompression and one filter for resizing 1440x1080 video frames to 1920x1080, the Decklink Upsample. The source filters represent the capture functionality of the DeckLink card, while the render filters encapsulate the playback functionality.

Additionally, a DirectX Media Object (DMO), Blackmagic Design Decoder, is supplied to perform various colorspace and bit-depth transformations. While this object is not strictly a DirectShow filter object, it can be included in DirectShow graphs using the system supplied DMO Wrapper Filter as a proxy.

Developers may be interested in the following books which are useful when developing DirectShow applications:

"Programming Microsoft DirectShow for Digital Video and Television " - Mark D. Pesce - ISBN 0-7356-1821-6
"The COM and COM+ Programming Primer" - Alan Gordon - ISBN 0-13-085032-2

See Also

  • DirectShow Filters


Introduction to DeckLink DirectShow Library

DeckLink DirectShow Documentation

Decklink FAQ

This article contains frequently asked questions about DeckLink and DeckLink DirectShow support.

General Questions

Can I have more than one DeckLink card in a PC?

Yes you can, the Windows drivers were updated recently to support more than one card. There is a software limitation of eight cards as it is not anticipated that more than eight cards will ever be installed in one system.

How can I get the DeckLink SDK?

If you are reading this then you have the DeckLink SDK. The DeckLink SDK describes the DeckLink DirectShow filters, custom interfaces published on these filters and sample code for using these filters.

When I connect the DeckLink video capture filter to the DeckLink video render filter I see black on the output.

A Decklink card is only capable of one mode of operation. Either capturing or rendering, not both.

What video formats are supported by DeckLink cards?

This will be dependant upon the type of card(s) you have, the following is a complete list:

  • NTSC 23.976fps automatic 3:2 pulldown handling, 8-bit and 10-bit YUV.
  • NTSC 8-bit and 10-bit YUV
  • PAL 8-bit and 10-bit YUV
  • HD1080 60i, 59.94i, 50i, 30PsF, 29.97PsF, 25PsF, 24PsF and 23.976PsF, 8-bit and 10-bit YUV, 10-bit RGB (dual stream, 4:4:4)
  • HD720 60p, 59.94p, 50p, 30p, 29.97p, 25p, 24p and 23.976p, 8-bit and 10-bit YUV, 10-bit RGB (dual stream, 4:4:4)

How can I control my DeckLink card from my Microsoft Windows application?

You can use the Microsoft DirectShow API or the Apple QuickTime API for audio and video or the ASIO interface for audio.

Can I get the custom/C API?

Blackmagic opted for writing DirectShow filters instead of providing a custom API due to the following benefits.

i. Developers are not subjected to application rewrites should the custom API change.

ii. DirectShow is a 'standard' interface which provides application developers with a huge toolbox of video and audio processing functions.

iii. DirectShow is a mature technology with a large number of experienced developers, subscribe to DirectXAV mailing list at http://DISCUSS.MICROSOFT.COM/archives/DIRECTXAV.html or alternatively please visit the following DirectShow forum, http://forums.microsoft.com/msdn/default.aspx.

Can the video render filter crop the frame for NTSC DV playback?

Yes. In fact you can connect to the render filter with any frame height less than or equal to the normal height. For example, NTSC DV is 720x480 so the video renderer will black the remaining six lines.

Can I connect with a negative height?

Yes. The video renderer will invert the image if the pixel format of the connection is RGB. If the pixel format is YUV the sign of the height is ignored.

Can I use another programming language other that C++?

Yes but you will rely more on third parties for help as the help provided by Blackmagic Design is currently exclusively in C++. Please search the internet for links related to the following:

  • Java Media Framework API
  • Delphi DirectShow
  • C# DirectShow
  • VB DirectShow

Programming Questions

Using VB (or C# or Java), how do I use the custom DirectShow interfaces provided by Blackmagic, such as IDecklinkKeyer?

First you will have to import the type library DecklinkInterface.tlb which provides information to your development environment regarding the custom DeckLink DirectShow interfaces. Once this information is available you will be interested in any interface that is prepended 'IADecklink...'. For example, to enable internal keying you could use the following:

Dim Keyer as IADecklinkKeyer
:
Set Keyer = New DecklinkRenderFilter
:
Keyer.set_AlphaBlendModeOn False
:
etc.

What media types are supported by DeckLink filters?

Video capture: MEDIASUBTYPE_UYVY, IID_MEDIASUBTYPE_v210*, IID_MEDIASUBTYPE_r210*

Video render: MEDIASUBTYPE_UYVY, IID_MEDIASUBTYPE_v210*, MEDIASUBTYPE_RGB32, MEDIASUBTYPE_ARGB32, IID_MEDIASUBTYPE_r210*

Audio capture: 48kHz, 16-bit, WAVE_FORMAT_PCM, from 1-12 channels.

Audio render: As Audio capture.

* These are custom GUIDs and are available in this SDK from the sample code.

How can I get the DirectShow SDK AMCap sample to change video capture format?

You must turn off preview in order to change the video capture format.

My application generates a bitmap image. How do I play it out on the DeckLink output?

The DirectShow SDK PushSource sample implements this exactly.

What is the pixel organisation of 10-bit YUV (v210)?

Please refer to the page in this help titled "Video Formats" or the Apple website, http://developer.apple.com/quicktime/icefloe/dispatch019.html#v210.

Are the SDK samples available for Visual Studio 6.0?

Not directly, try the following link to convert the available Visual Studio 7.0 projects to 6.0 projects. http://www.codeproject.com/tools/prjconverter.asp.

Can I programmatically control my VideoHub?

Yes, though there is not a DirectShow or any other SDK to speak of you could write your own socket client to interact with the server on TCP port 9990. It uses a simple text based protocol which can be fairly easily worked out by just making a connection to that port and watching the traffic. Upon first connecting the server sends a series of command blocks to the client informing them of the Videohub's state. Whenever another client makes a change to the Videohub it broadcasts this change to all other clients. Client server communication is command block oriented where each command block has the form:-

BLOCKNAME:\n
<value><space><value>\n
...
<value><space><value>\n
\n

(i.e. each command block is terminated by a single newline character). The format of lines in each block varies depending on the block type but generally a line consists of a number (referring to the port number on the device) and a label or routing description. When a client sends command blocks to the server they should expect an ACK or NAK command block in response.


DeckLink DirectShow Filters

The Blackmagic Design DeckLink DirectShow library contains a number of filters for capturing, resizing, compressing, decompressing and rendering audio and video streams. Four filters encapsulate the four operational areas of the card; DeckLink Video Capture, DeckLink Audio Capture, DeckLink Video Render and DeckLink Audio Render. The DeckLink MJPEG Compressor and DeckLink MJPEG Decompressor filters provide compression and decompression of video streams in realtime. The DeckLink Still Sequence Source and DeckLink Still Sequence Sink filters are dedicated to managing sequences of stills. One filter provides resizing of video frames that are 1440 pixels wide to 1920 pixels wide. All these filters are automatically installed during the DeckLink setup and register themselves in the DirectShow category appropriate for their function.

The capture and render filters behave as expected for any DirectShow capture or render filter. The DeckLink Video Render filter is stricter than other video renderers when comparing stream formats before accepting a connection. The stream format, frame size and frame rate must match exactly one of the supported combinations. For full details of the supported formats see the DeckLink Video Render filter documentation.

Two new filters are available provide access to the high quality, real time DeckLink Motion-JPEG codec which makes it possible to compress and decompress video streams in real time.

The DeckLink Still Sequence Source and DeckLink Still Sequence Sink filters extend the native DirectShow file handling so in addition to native AVI, MOV and WMV, sequences of stills can be used with the other DeckLink filters.

HDV is a popular compression format but the frame sizes produced by HDV cameras and codecs is only 1440 pixels wide. As described in the DeckLink Video Render filter documentation this frame size is not supported by this filter so the DeckLink Upsample filter can be used to resize HDV video from 1440 pixels wide to 1920 pixels wide so that it can be rendered by the DeckLink Video render filter.

Filter | Description
DeckLink Video Capture | Captures video samples from configured SDI or analog inputs. Outputs captured video as uncompressed stream.
DeckLink Audio Capture | Captures digital or analog audio samples.
DeckLink Video Render | Transfers digital video stream to DeckLink card for output.
DeckLink Audio Render | Outputs an audio stream to the DeckLink card.
DeckLink Motion-JPEG Encoder | Generates a Motion-JPEG compressed stream.
DeckLink Motion-JPEG Decoder | Decodes a Motion-JPEG compressed stream.
DeckLink Upsample | Increases the horizontal size of a video frame that is 1440 pixels wide to 1920 pixels.
DeckLink Still Sequence Source | Generates video samples from a sequence of still images.
DeckLink Still Sequence Sink | Writes a sequence of still images to disk from a video stream.

The majority of interfaces implemented by all filters are defined as 'standard' DirectShow interfaces. A number of custom interfaces have been defined to access non-standard functionality on the card. For a complete list of implemented interfaces, see Interface Reference.

The two capture filters enable the independent capture of video and audio. While this is the theoretical object of having independent capture filters, a current constraint exists meaning that an audio stream cannot be captured without video (to workaround this limitation, capture video but do not mux it with audio). This limitation applies similarly to the DeckLink Audio Render filter.


DeckLink Video Capture Filter

The DeckLink Video Capture filter is used to inject a video stream into a DirectShow graph. The samples from this stream are a digitized representation of the input received by the installed DeckLink card. The filter acts in 'push' mode.

The actual frame sizes and frame rates offered for the output pin formats varies depending on the capabilities of the installed DeckLink card. All cards offer 720x486/29.97fps (NTSC) and 720x576/25fps (PAL) and other HD formats are available for high definition capable cards.

When the capture filter is connected, the video output signal from the DeckLink card is either coupled to the input signal or shows a stable black signal depending on the "Black Video Output to Deck in Capture" control panel setting. The monitor output, where present, is coupled to the input signal while the capture filter is connected.

NOTE: The DeckLink Video Render filter cannot be connected while the capture filter is connected.

The VANC output pin provides a stream of raw VANC data for applications that have an interest in specific or customised areas of this video data segment. The data is encoded in the same format as the video capture pin, e.g. 8-bit YUV.

The VITC output pin provides a stream of TIMECODE_SAMPLES populated with timecode data decoded from VANC. SMPTE BCD timecode is provided along with the VITC user bits and VITC flags. The flags are packed as per the TIMECODE_SAMPLE structure description with the exception of bits 3-5 which are the VITC binary group flags.

Filter Interfaces | IBaseFilter, IMediaFilter, IAMovieSetup, IAMDroppedFrames, IAMFilterMiscFlags, IAMExtDevice, IAMExtTransport, IAMTimecodeReader, ISpecifyPropertyPages, IAMDroppedFrames, IPersistStream, IPersist, IDecklinkRawDeviceControl, IDecklinkStatus, IDecklinkIOControl
Input Pin Media Types | Not applicable.
Input Pin Interfaces | Not applicable.
Capture Output Pin Media Types | MEDIATYPE_Video, MEDIASUBTYPE_UYVY MEDIATYPE_Video, IID_MEDIASUBTYPE_v210a (10 bit YUV) MEDIATYPE_Video, IID_MEDIASUBTYPE_r210 (10 bit RGB)
Capture Output Pin Interfaces | IPin, IQualityControl, IPinFlowControl, IAMStreamControl, IKsPropertySet, IAMStreamConfig, IAMPushSource, IAMBufferNegotiation, IDecklinkCaptureBanner, IDecklinkMediaSample
VANC Output Pin Media Type | MEDIATYPE_Video, MEDIASUBTYPE_UYVY
VANC Output Pin Interfaces | IPin, IQualityControl, IAMStreamControl, IKsPropertySet, IAMStreamConfig
VITC Output Pin Media Type | MEDIATYPE_Timecode, MEDIASUBTYPE_NULL MEDIATYPE_Text, MEDIASUBTYPE_NULL
VITC Output Pin Interfaces | IPin, IQualityControl, IAMStreamControl, IKsPropertySet, IAMStreamConfig
Filter CLSID | CLSID_DecklinkVideoCaptureFilter
Property Page CLSID | CLSID_DecklinkVideoCaptureProperties
Merit | MERIT_DO_NOT_USE
Filter Category | CLSID_VideoInputDeviceCategory

See Also

Filter Interface Reference


DeckLink Audio Capture Filter

The DeckLink Audio Capture filter is used to inject an audio stream into a DirectShow graph. The samples for this stream are a digitized representation of the input received by the installed DeckLink card. The filter acts in 'push' mode.

Only one audio format is supported; PCMAudio, 48 KHz, 16 bit.

Filter Interfaces | IBaseFilter, IMediaFilter, IAMovieSetup, IAMDroppedFrames, IAMFilterMiscFlags, ISpecifyPropertyPages, IAMDroppedFrames, IPersistStream, IPersist, IDecklinkIOControl
Input Pin Media Types | Not applicable.
Input Pin Interfaces | Not applicable.
Output Pin Media Types | MEDIATYPE_Audio, MEDIASUBTYPE_PCM
Output Pin Interfaces | IPin, IQualityControl, IPinFlowControl, IAMStreamControl, IKsPropertySet, IAMStreamConfig, IAMPushSource, IAMBufferNegotiation
Filter CLSID | CLSID_DecklinkAudioCaptureFilter
Property Page CLSID | CLSID_DecklinkAudioCaptureProperties
Merit | MERIT_DO_NOT_USE
Filter Category | CLSID_VideoInputDeviceCategory

See Also

Filter Interface Reference


DeckLink Video Render Filter

The DeckLink Video Render filter is used to receive a video stream from a DirectShow graph and output via the installed DeckLink card.

The actual frame sizes and frame rates accepted by the input pin varies depending on the capabilities of the installed DeckLink card. All cards offer 720x486/29.97fps (NTSC) and 720x576/25fps (PAL) and other HD formats are available for high definition capable cards.

It should be noted that the Video Render filter strictly enforces connection format, size and rate. If any of these variables on the input stream do not match the supported combination, no connection will be achieved.

DV playback is supported: NTSC DV 720x480 and PAL DV 720x576. It is worth noting that the field order for PAL DV is the opposite of PAL SD. The field reversal is handled by the video render filter by the penalty of this feature is the loss of the first active line of video. In order to display PAL DV correctly connect to this filter using a VIDEOINFOHEADER2 in the connection media type. Specify AMINTERLACE_IsInterlaced ORed with AMINTERLACE_DisplayModeWeaveOnly or AMINTERLACE_DisplayModeBobOrWeave flags in the dwInterlaceFlags member of this structure. Note that this feature has only been tested with the Microsoft DV decoder filter that ships with Microsoft Windows.

Filter Interfaces | IBaseFilter, IMediaFilter, IAMovieSetup, IMediaSeeking, IMediaPosition, IAMFilterMiscFlags, IReferenceClock, IAMExtDevice, IAMExtTransport, IAMTimecodeReader, IPersistStream, IPersist, IQualProp, IQualityControl, IDecklinkRawDeviceControl, IDecklinkKeyer, IDecklinkIOControl, IDecklinkStatus
Input Pin Media Types | MEDIATYPE_Video, MEDIASUBTYPE_UYVY MEDIATYPE_Video, MEDIASUBTYPE_RGB32 MEDIATYPE_Video, MEDIASUBTYPE_ARGB32 MEDIATYPE_Video, IID_MEDIASUBTYPE_v210a (10 bit YUV) MEDIATYPE_Video, IID_MEDIASUBTYPE_r210 (10 bit RGB)
Input Pin Interfaces | IPin, IQualityControl, IMemInputPin
Output Pin Media Types | Not applicable.
Output Pin Interfaces | Not applicable.
Filter CLSID | CLSID_DecklinkVideoRenderFilter
Property Page CLSID | None.
Merit | MERIT_DO_NOT_USE
Filter Category | CLSID_TransmitCategory

See Also

Filter Interface Reference


DeckLink Audio Render Filter

The Decklink Audio Render filter is used to receive an audio stream from a DirectShow graph and output via the installed DeckLink card.

Only a single format is supported; PCMAudio, 48 KHz, 16 bit.

Audio is output via the DeckLink card either embedded in an SDI stream, as SPDIF/AES digital audio or as balanced analog audio.

Due to the design of the DeckLink cards, rendering audio without video does not output anything. Even if no video is required, the DeckLink Video Render filter must be included in the graph to activate the hardware.

Only one audio format is supported; PCMAudio, 48 KHz, 16 bit.

Filter Interfaces | IBaseFilter, IMediaFilter, IAMovieSetup, IMediaSeeking, IMediaPosition, IAMFilterMiscFlags, IReferenceClock, IPersistStream, IPersist, IQualityControl, IDecklinkIOControl
Input Pin Media Types | MEDIATYPE_Audio, MEDIASUBTYPE_PCM
Input Pin Interfaces | IPin, IQualityControl, IMemInputPin
Output Pin Media Types | Not applicable.
Output Pin Interfaces | Not applicable.
Filter CLSID | CLSID_DecklinkAudioRenderFilter
Property Page CLSID | None.
Merit | MERIT_DO_NOT_USE
Filter Category | CLSID_AudioRendererCategory

See Also

Filter Interface Reference


DeckLink Motion-JPEG Compressor Filter

DeckLink DirectShow Documentation

DeckLink Motion-JPEG Encoder Filter

The DeckLink Motion-JPEG (M-JPEG) Encoder filter is used to compress video streams in real time.

Compression is very useful for reducing the data rate of a video stream and for reducing the storage requirements of a system handling video. For example, to capture uncompressed HD requires expensive RAIDs and motherboards. Using the DeckLink M-JPEG codec, HD can be captured to the internal disk of a standard computer.

For M-JPEG compression, each frame is individually compressed using non-lossless ISO JPEG compression and formatted into a stream in accordance with the OpenDML AVI M-JPEG File Format. This type of compression is intraframe compression where each frame is individually compressed without requiring knowledge of previous or following frames†. This type of compression is especially useful in video editing applications as cuts can be made anywhere in the video.

The output stream of the DeckLink M-JPEG Encoder filter is, by default, fully compatible with the native Microsoft Windows M-JPEG codec. This means that DeckLink M-JPEG compressed video can be transferred to ANY computer without requiring the need to install the DeckLink software.

There are also two compatibility settings available to disable normalisation and swap the fields of interlaced video. These settings can be used to compressed the video so that it is compatible with other third party M-JPEG decoders.

†Compare this with interframe compression, e.g. MPEG, HDV and H.264.

Filter Interfaces | IBaseFilter, IMediaFilter, IAMovieSetup, ISpecifyPropertyPages, IAMVideoCompression
Input Pin Media Types | MEDIATYPE_Video, MEDIASUBTYPE_UYVY MEDIATYPE_Video, MEDIASUBTYPE_YUY2 MEDIATYPE_Video, IID_MEDIASUBTYPE_HDYC (8-bit YUV) MEDIATYPE_Video, MEDIASUBTYPE_RGB24 MEDIATYPE_Video, MEDIASUBTYPE_RGB32
Input Pin Interfaces | IPin, IQualityControl, IMemInputPin
Output Pin Media Types | MEDIATYPE_Video, MEDIASUBTYPE_MJPG
Output Pin Interfaces | IPin, IQualityControl
Filter CLSID | CLSID_DecklinkMJPEGEncoderFilter
Property Page CLSID | CLSID_DecklinkMJPEGEncoderProperties
Merit | MERIT_DO_NOT_USE
Filter Category | CLSID_VideoCompressorCategory

See Also

Filter Interface Reference


DeckLink Motion-JPEG Decompressor Filter

DeckLink DirectShow Documentation

DeckLink Motion-JPEG Decoder Filter

The DeckLink Motion-JPEG (MJPEG) Decoder filter is used to decompress bit streams in real time.

Compression is very useful for reducing the data rate of a video stream and for reducing the storage requirements of a system handling video. For example, to capture uncompressed HD requires expensive RAIDs and motherboards. Using the DeckLink M-JPEG codec, HD can be captured to the internal disk of a standard computer.

For M-JPEG decompression, frames are individually decompressed from an OpenDML AVI M-JPEG File Formatted stream using non-lossless ISO JPEG decompression. The M-JPEG bit stream uses intraframe compression where each frame is individually compressed without requiring knowledge of previous or following frames†. This type of compression is especially useful in video editing applications as cuts can be made anywhere in the video.

The DeckLink M-JPEG Decoder filter is, by default, fully compatible with the native Microsoft Windows M-JPEG codec.

There are also two compatibility settings available to disable normalisation and swap the fields of interlaced video. These settings can be used to correctly decompress bit streams compressed with other third party M-JPEG encoders.

†Compare this with interframe compression, e.g. MPEG, HDV and H.264.

Filter Interfaces | IBaseFilter, IMediaFilter, IAMovieSetup, ISpecifyPropertyPages
Input Pin Media Types | MEDIATYPE_Video, MEDIASUBTYPE_MJPG
Input Pin Interfaces | IPin, IQualityControl, IMemInputPin
Output Pin Media Types | MEDIATYPE_Video, MEDIASUBTYPE_UYVY MEDIATYPE_Video, MEDIASUBTYPE_YUY2 MEDIATYPE_Video, IID_MEDIASUBTYPE_HDYC (8-bit YUV) MEDIATYPE_Video, MEDIASUBTYPE_RGB24 MEDIATYPE_Video, MEDIASUBTYPE_RGB32
Output Pin Interfaces | IPin, IQualityControl
Filter CLSID | CLSID_DecklinkMJPEGDecoderFilter
Property Page CLSID | CLSID_DecklinkMJPEGDecoderProperties
Merit | MERIT_PREFERRED
Filter Category | CLSID_LegacyAmFilterCategory

See Also

Filter Interface Reference


DeckLink Upsample Filter

The DeckLink Upsample Filter filter is used to resize a video frame that is 1440 pixels wide to 1920 pixels wide in real time.

HDV is a popular compression format and has video frame dimensions of 1440 pixels wide by 1080 pixels high. This is a cropped version of the 1920x1080 video frame sizes supported by the DeckLink Video Render filter. In order to render HDV video using DeckLink Video Render filter the HDV video frames must be resized by increasing the width from 1440 pixels to 1920 pixels.

Filter Interfaces | IBaseFilter, IMediaFilter, IAMovieSetup
Input Pin Media Types | MEDIATYPE_Video, MEDIASUBTYPE_UYVY MEDIATYPE_Video, MEDIASUBTYPE_RGB32 MEDIATYPE_Video, MEDIASUBTYPE_ARGB32
Input Pin Interfaces | IPin, IQualityControl, IMemInputPin
Output Pin Media Types | MEDIATYPE_Video, MEDIASUBTYPE_UYVY MEDIATYPE_Video, MEDIASUBTYPE_RGB32 MEDIATYPE_Video, MEDIASUBTYPE_ARGB32
Output Pin Interfaces | IPin, IQualityControl
Filter CLSID | CLSID_DecklinkUpsampleFilter
Property Page CLSID | None.
Merit | MERIT_DO_NOT_USE
Filter Category | CLSID_LegacyAmFilterCategory

See Also

Filter Interface Reference


DeckLink Still Sequence Source Filter

The DeckLink Still Sequence Source filter is used to generate a stream of video samples from a sequence of image stills.

This filter extends the native DirectShow file support by making it possible to generate a video stream from a sequence of still images. The file names of the still images usually have a numerical index which specifies the position of the still image in the overall sequence. This filter loads each image in numerical order and produces a stream of video samples which contain the image data. The file name of the first file to be used in the sequence is passed to this filter which then determines the properties of the video stream such as frame dimensions, media subtype and stream duration. It is not necessary to specify all the files to be used by this filter since it uses the first file name as the base file name and assumes that all other images have the same properties as the one specified.

As the HD formats have more than one possible frame rate an application can specify the frame rate of the HD video stream by passing a media type to the filter using the IFileSourceFilter interface. This media type does not need to be fully defined, just the AvgTimePerFrame field, of a VIDEOINFOHEADER or VIDEOINFOHEADER2 structure, is required to specify the frame rate of the video stream.

Filter Interfaces | IBaseFilter, IMediaFilter, IAMovieSetup, IAMFilterMiscFlags, IFileSourceFilter
Input Pin Media Types | Not applicable.
Input Pin Interfaces | Not applicable.
Output Pin Media Types | MEDIATYPE_Video, MEDIASUBTYPE_RGB24 MEDIATYPE_Video, MEDIASUBTYPE_RGB32 MEDIATYPE_Video, MEDIASUBTYPE_ARGB32 MEDIATYPE_Video, IID_MEDIASUBTYPE_r210
Output Pin Interfaces | IPin, IQualityControl, IAMStreamControl, IMediaSeeking
Filter CLSID | CLSID_DecklinkStillSequenceSourceFilter
Property Page CLSID | None.
Merit | MERIT_DO_NOT_USE
Filter Category | CLSID_LegacyAmFilterCategory

See Also

Filter Interface Reference


DeckLink Still Sequence Sink Filter

The DeckLink Still Sequence Sink filter is used to generate a sequence of still images from a stream of video samples.

This filter extends the native DirectShow file support by making it possible to generate a sequence of still images from a stream of video samples. This differs from the native DirectShow support by writing each frame of the video stream as a separate file, as apposed to writing each frame of video into the same file as per AVI, MOV and WMV.

Each file that is written is given a numerical index that uniquely identifies the position of the file within the entire sequence. The file name provided to this filter is used as the base file name for the entire sequence. If any numerical characters are present at the end of the file name but before the '.' for the extension then this value is used as the starting index for the sequence. For example, if "DeckLink Sequence 200.dpx" is provided to the filter this will mean the index starts from 200. If no numerical index is provided then the index starts from zero.

Filter Interfaces | IBaseFilter, IMediaFilter, IAMovieSetup, IAMFilterMiscFlags, IFileSinkFilter
Input Pin Media Types | MEDIATYPE_Video, MEDIASUBTYPE_RGB24 MEDIATYPE_Video, MEDIASUBTYPE_RGB32 MEDIATYPE_Video, MEDIASUBTYPE_ARGB32 MEDIATYPE_Video, IID_MEDIASUBTYPE_r210
Input Pin Interfaces | IPin, IQualityControl, IMemInputPin
Output Pin Media Types | Not applicable.
Output Pin Interfaces | Not applicable.
Filter CLSID | CLSID_DecklinkStillSequenceSinkFilter
Property Page CLSID | None.
Merit | MERIT_DO_NOT_USE
Filter Category | CLSID_LegacyAmFilterCategory

See Also

Filter Interface Reference


Blackmagic Design Decoder (DMO)

The Blackmagic Design Decoder DirectX Media Object (DMO) enables the transformation of various video formats to other formats in different colorspaces and bit depths. The object implements the required interfaces for a DMO, namely IMediaObject. As a DMO, instances of this object can be included in DirectShow graphs automatically by the DMO Wrapper Filter.

All conversions from any source format to any output format are supported. The following tables lists the GUID ids of valid formats. Note that the major type for all formats is MEDIATYPE_Video:

Source Format
IID_MEDIASUBTYPE_V210
IID_MEDIASUBTYPE_v210a
MEDIASUBTYPE_UYVY
MEDIASUBTYPE_YUY2
MEDIASUBTYPE_HDYC
MEDIASUBTYPE_2Vuy
MEDIASUBTYPE_2vuy
MEDIASUBTYPE_RGB32
MEDIASUBTYPE_ARGB32
MEDIASUBTYPE_r210
Output Format
MEDIASUBTYPE_RGB32
MEDIASUBTYPE_UYVY

Additionally, color correction from HD to SD YUV colorspace can be achieved using this object.


Introduction to DeckLink DirectShow Library

DeckLink DirectShow Documentation

Video Formats

This article contains information regarding the organisation of data in video formats supported by Decklink.

'UYVY' 4:2:2 Compression

Four 8-bit unsigned components (CCIR 601) are packed into one 32-bit little-endian word.

Word
Decreasing Address Order
Byte 3 |  |  |  |  |  |  |  | Byte 2 |  |  |  |  |  |  |  | Byte 1 |  |  |  |  |  |  |  | Byte 0
Y' 1 |  |  |  |  |  |  |  | Cr 0 |  |  |  |  |  |  |  | Y' 0 |  |  |  |  |  |  |  | Cb 0
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0

framesize | = | (Width * 16 / 8) * Height | NOTE: This is an INTEGER calculation.
 | = | rowbytes * Height |
E.g. for 720 x 486:
rowbytes | = | (Width * 16 / 8) |
 | = | (720 * 16 / 8) |
 | = | 1440 |
framesize | = | rowbytes * Height |
 | = | 1440 * 486 |
 | = | 699840 |
In this format two pixels pixel fits into 32 bits or 4 bytes, so one pixel fits into 16 bits or 2 bytes. For the row bytes calculation the image width is multiplied by the number of bytes per pixel. For the frame size calculation the rowbytes are simply multiplied by the number of rows in the frame.

'YUY2' 4:2:2 Compression

Four 8-bit unsigned components (CCIR 601) are packed into one 32-bit little-endian word.

Word
Decreasing Address Order
Byte 3 |  |  |  |  |  |  |  | Byte 2 |  |  |  |  |  |  |  | Byte 1 |  |  |  |  |  |  |  | Byte 0
Cr 0 |  |  |  |  |  |  |  | Y' 1 |  |  |  |  |  |  |  | Cb 0 |  |  |  |  |  |  |  | Y' 0
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0

framesize | = | (Width * 16 / 8) * Height | NOTE: This is an INTEGER calculation.
 | = | rowbytes * Height |
E.g. for 720 x 576:
rowbytes | = | (Width * 16 / 8) |
 | = | (720 * 16 / 8) |
 | = | 1440 |
framesize | = | rowbytes * Height |
 | = | 1440 * 576 |
 | = | 829440 |
In this format two pixels pixel fits into 32 bits or 4 bytes, so one pixel fits into 16 bits or 2 bytes. For the row bytes calculation the image width is multiplied by the number of bytes per pixel. For the frame size calculation the rowbytes are simply multiplied by the number of rows in the frame.

'HDYC' 4:2:2 Compression

Four 8-bit unsigned components (CCIR 709) are packed into one 32-bit little-endian word.

Word
Decreasing Address Order
Byte 3 |  |  |  |  |  |  |  | Byte 2 |  |  |  |  |  |  |  | Byte 1 |  |  |  |  |  |  |  | Byte 0
Y' 1 |  |  |  |  |  |  |  | Cr 0 |  |  |  |  |  |  |  | Y' 0 |  |  |  |  |  |  |  | Cb 0
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0

framesize | = | (Width * 16 / 8) * Height | NOTE: This is an INTEGER calculation.
 | = | rowbytes * Height |
E.g. for 720 x 576:
rowbytes | = | (Width * 16 / 8) |
 | = | (720 * 16 / 8) |
 | = | 1440 |
framesize | = | rowbytes * Height |
 | = | 1440 * 576 |
 | = | 829440 |
In this format two pixels pixel fits into 32 bits or 4 bytes, so one pixel fits into 16 bits or 2 bytes. For the row bytes calculation the image width is multiplied by the number of bytes per pixel. For the frame size calculation the rowbytes are simply multiplied by the number of rows in the frame.

BI_RGB (or RGB24) 4:4:4 No compression

Three 8-bit unsigned components are packed into three 8-bit little-endian words.

Word
Decreasing Address Order
Byte 2 |  |  |  |  |  |  |  | Byte 1 |  |  |  |  |  |  |  | Byte 0
R |  |  |  |  |  |  |  | G |  |  |  |  |  |  |  | B
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0

framesize | = | (Width * 24 / 8) * Height | NOTE: This is an INTEGER calculation.
 | = | rowbytes * Height |
E.g. for 1920 x 1080:
rowbytes | = | (Width * 24 / 8) |
 | = | (1920 * 24 / 8) |
 | = | 5760 |
framesize | = | rowbytes * Height |
 | = | 5760 * 1080 |
 | = | 6220800 |
In this format each pixel fits into 24 bits or 3 bytes. For the row bytes calculation the image width is multiplied by the number of bytes per pixel. For the frame size calculation the rowbytes are simply multiplied by the number of rows in the frame.

BI_RGB (or RGB32) 4:4:4:x No compression

Four 8-bit unsigned components are packed into one 32-bit little-endian word. Alpha channel may be valid.

Word
Decreasing Address Order
Byte 3 |  |  |  |  |  |  |  | Byte 2 |  |  |  |  |  |  |  | Byte 1 |  |  |  |  |  |  |  | Byte 0
X |  |  |  |  |  |  |  | R |  |  |  |  |  |  |  | G |  |  |  |  |  |  |  | B
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0

framesize | = | (Width * 32 / 8) * Height | NOTE: This is an INTEGER calculation.
 | = | rowbytes * Height |
E.g. for 1920 x 1080:
rowbytes | = | (Width * 32 / 8) |
 | = | (1920 * 32 / 8) |
 | = | 7680 |
framesize | = | rowbytes * Height |
 | = | 7680 * 1080 |
 | = | 8294400 |
In this format each pixel fits into 32 bits or 4 bytes. For the row bytes calculation the image width is multiplied by the number of bytes per pixel. For the frame size calculation the rowbytes are simply multiplied by the number of rows in the frame.

BI_RGB (or ARGB32) 4:4:4:4 No compression

Four 8-bit unsigned components are packed into one 32-bit little-endian word. Alpha channel is valid.

Word
Decreasing Address Order
Byte 3 |  |  |  |  |  |  |  | Byte 2 |  |  |  |  |  |  |  | Byte 1 |  |  |  |  |  |  |  | Byte 0
A |  |  |  |  |  |  |  | R |  |  |  |  |  |  |  | G |  |  |  |  |  |  |  | B
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0

framesize | = | (Width * 32 / 8) * Height | NOTE: This is an INTEGER calculation.
 | = | rowbytes * Height |
E.g. for 1920 x 1080:
rowbytes | = | (Width * 32 / 8) |
 | = | (1920 * 32 / 8) |
 | = | 7680 |
framesize | = | rowbytes * Height |
 | = | 7680 * 1080 |
 | = | 8294400 |
In this format each pixel fits into 32 bits or 4 bytes. For the row bytes calculation the image width is multiplied by the number of bytes per pixel. For the frame size calculation the rowbytes are simply multiplied by the number of rows in the frame.

'v210' 4:2:2 Compression

Twelve 10-bit unsigned components are packed into four 32-bit little-endian words.

Word 0
Decreasing Address Order
Byte 3 |  |  |  |  |  |  |  | Byte 2 |  |  |  |  |  |  |  | Byte 1 |  |  |  |  |  |  |  | Byte 0
X | X | Cr 0 |  |  |  |  |  |  |  |  |  | Y' 0 |  |  |  |  |  |  |  |  |  | Cb 0
 |  | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0

Word 1
Decreasing Address Order
Byte 3 |  |  |  |  |  |  |  | Byte 2 |  |  |  |  |  |  |  | Byte 1 |  |  |  |  |  |  |  | Byte 0
X | X | Y' 2 |  |  |  |  |  |  |  |  |  | Cb 2 |  |  |  |  |  |  |  |  |  | Y' 1
 |  | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0

Word 2
Decreasing Address Order
Byte 3 |  |  |  |  |  |  |  | Byte 2 |  |  |  |  |  |  |  | Byte 1 |  |  |  |  |  |  |  | Byte 0
X | X | Cb 4 |  |  |  |  |  |  |  |  |  | Y' 3 |  |  |  |  |  |  |  |  |  | Cr 2
 |  | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0

Word 3
Decreasing Address Order
Byte 3 |  |  |  |  |  |  |  | Byte 2 |  |  |  |  |  |  |  | Byte 1 |  |  |  |  |  |  |  | Byte 0
X | X | Y' 5 |  |  |  |  |  |  |  |  |  | Cr 4 |  |  |  |  |  |  |  |  |  | Y' 4
 |  | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0

framesize | = | ((Width + 47) / 48) * 128 * Height | NOTE: This is an INTEGER calculation.
 | = | rowbytes * Height |
E.g. for 1920 x 1080:
rowbytes | = | ((Width + 47) / 48) * 128 |
 | = | ((1920 + 47) / 48) * 128 |
 | = | 40 * 128 |
 | = | 5120 |
framesize | = | rowbytes * Height |
 | = | 5120 * 1080 |
 | = | 5529600 |
In this format each line of video must be aligned on 128 byte boundaries. Six pixels fit into 16 bytes so 48 pixels fit in 128 bytes. For the row bytes calculation the image width is rounded to the nearest 48 pixel boundary and multiplied by 128. For the frame size calculation the rowbytes are simply multiplied by the number of rows in the frame.

'r210' 4:4:4 No compression

Three 10-bit unsigned components are packed into one 32-bit big-endian word.

Word
Decreasing Address Order
Byte 3 |  |  |  |  |  |  |  | Byte 2 |  |  |  |  |  |  |  | Byte 1 |  |  |  |  |  |  |  | Byte 0
B lo |  |  |  |  |  |  |  | G lo |  |  |  |  |  | B hi |  | R lo |  |  |  | G hi |  |  |  | X | X | R hi
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 5 | 4 | 3 | 2 | 1 | 0 | 9 | 8 | 3 | 2 | 1 | 0 | 9 | 8 | 7 | 6 | x | x | 9 | 8 | 7 | 6 | 5 | 4

framesize | = | ((Width + 63) / 64) * 256 * Height | NOTE: This is an INTEGER calculation.
 | = | rowbytes * Height |
E.g. for 1920 x 1080:
rowbytes | = | ((Width + 63) / 64) * 256 |
 | = | ((1920 + 63) / 64) * 256 |
 | = | 30 * 256 |
 | = | 7680 |
framesize | = | rowbytes * Height |
 | = | 7680 * 1080 |
 | = | 8294400 |
In this format each line of video must be aligned on 256 byte boundaries. One pixel fits into 4 bytes so 64 pixels fit in 256 bytes. For the row bytes calculation the image width is rounded to the nearest 64 pixel boundary and multiplied by 256. For the frame size calculation the rowbytes are simply multiplied by the number of rows in the frame.


Interface Reference

As previously stated, much of the functionality of DeckLink cards is exposed via standard DirectShow interfaces. There is some functionality, however that cannot be expressed by standard interfaces and require the definition of custom interfaces.

The following table lists all of the interfaces implemented by each filter. For standard DirectShow interfaces, the link will refer to the Microsoft MSDN web site for complete documentation. For custom interfaces, the link will resolve to Blackmagic Design documentation:

Filter | Interface
IDecklinkKeyer Interface | Provides control of internal and/or external keying on DeckLink cards that support keying.
IDecklinkRawDeviceControl Interface | Provides a mechanism for passing raw device control messages via the RS422 port on DeckLink cards.
IDecklinkStatus Interface | Provides video input and genlock status monitoring.
IDecklinkCaptureBanner Interface | Provides customisation of the 'No Input' capture banner.
IDecklinkIOControl Interface | Provides control of all of the I/O options on a DeckLink card, e.g. audio inputs, downconversion, etc.
IDecklinkMediaSample Interface | Provides access to the VANC data of every video frame.

Automation

For applications that are not written in C++ a set of custom interfaces exist that support the IDispatch interface. These interfaces are identical to the above interfaces except that they are derived from IDispatch instead of IUnknown. The interface names are identical to the above except that an 'A', for 'Automation', has been inserted into the interface name after the 'I' so that 'IDecklink...' becomes 'IADecklink...'. Implementing the IDispatch interface places restrictions on the data types of the arguments that are passed into or received from the interface methods and properties. The following table lists the interface methods and properties that differ from the original 'IDecklink...' implementation:

Filter | Interface
IADecklinkRawDeviceControl:SendRawCommandAsync2 | Provides a mechanism for passing raw device control messages via the RS422 port on DeckLink cards.

See Also

  • DeckLink DirectShow Filters


IDecklinkKeyer Interface

The IDecklinkKeyer interface provides access to the alpha keyer function of the DeckLink card.

The DeckLink Video Render filter implements this interface.

In addition to the methods inherited from IUnknown, the IDecklinkKeyer interface exposes the following methods.

Method | Description
set_AlphaBlendModeOn | Turns alpha blending on in the card. Optionally outputs key separately via one of the SDI outputs if external key mode true.
set_AlphaBlendModeOff | Turns off alpha blending mode in the card.
set_AlphaLevel | Sets the alpha blending co-efficient to determine key opacity.
set_AlphaAutoBlendSettings | Setup automatic blending of the key in and out of the output stream.
do_AlphaRampOn | Blends key into output stream over a specified number of frames.
do_AlphaRampOff | Blends key out of output stream over a specified number of frames.
get_DeviceSupportsKeying | Determine if installed DeckLink card supports keying.
get_DeviceSupportsExternalKeying | Determine if installed DeckLink card supports sending key and fill independently to external keyer.


IDecklinkKeyer::set_AlphaBlendModeOn

The set_AlphaBlendModeOn method activates the alpha blending mode in the card. Optionally outputs key separately to fill to be passed to an external keyer device.

Syntax

HRESULT set_AlphaBlendModeOn(
    uint isExternalKey
);

Parameters

isExternalKey

[in] Flag indicating if input should be keyed into card input or output to external keyer. If the get_DeviceSupportsExternalKeying property returns TRUE then this value will select between internal and external keyer. If it is FALSE, then the value of this parameter is ignored.

Return Values

Value | Description
E_PROP_ID_UNSUPPORTED | The installed DeckLink card does not support alpha keying. You must call the get_DeviceSupportsKeying property before calling this method.
E_FAIL | General failure to activate alpha keying mode.
S_OK | Success.
Remarks

Call this method to activate alpha blending. After this method has been called all output sent to the card using any method (within DirectShow or without) will be treated as a key image. This method may only be called after the get_DeviceSupportsKeying property has indicated that the installed card supports alpha keying.

If the isExternalKey argument is FALSE then the internal keyer on the card will be used to blend the card's input with the key image with the resultant image being sent to the card's output. If isExternalKey is TRUE (only for dual SDI output cards) then the key is separated from the image fill and each being output via one of the card's SDI outputs. This mode is useful for sending to an external keyer device.

Note that the set_AlphaBlendModeOff method MUST be called to exit key mode. Even if the process that called the original method terminates, the card will remain in key mode until this method is called.

See Also

IDecklinkKeyer Interface, set_AlphaBlendModeOff Method, get_DeviceSupportsKeying Property, get_DeviceSupportsExternalKeying Property


IDecklinkKeyer::set_AlphaBlendModeOff

The set_AlphaBlendModeOff method deactivates the alpha blending mode in the card. This method should be called after calling set_AlphaBlendModeOn when keying is no longer required.

Syntax

HRESULT set_AlphaBlendModeOff(void);

Return Values

Value | Description
E_PROP_ID_UNSUPPORTED | The installed DeckLink card does not support alpha keying. You must call the get_DeviceSupportsKeying property before calling this method.
E_FAIL | General failure to activate alpha keying mode.
S_OK | Success.
Remarks

Call this method to deactivate alpha keying mode. When activated, alpha keying mode will remain effective until this method is called or the computer is rebooted.

See Also

IDecklinkKeyer Interface, set_AlphaBlendModeOn Method


IDecklinkKeyer::set_AlphaLevel

The set_AlphaLevel method adjusts the opacity level of the alpha channel.

Syntax

HRESULT set_AlphaLevel(
    uint alphaLevel
);

Parameters

alphaLevel

[in] Value in the range 0-255 that specifies the opacity level. A value of 0 indicates that the alpha channel is intepreted as transparent, while a value of 255 indicates that the alpha channel is completely opaque. There is a linear progression between these values.

Return Values

Value | Description
E_FAIL | General failure to set alpha level.
S_OK | Success.
Remarks

Call this method either before or after calling the set_AlphaBlendModeOn method to specify the opacity level of the alpha channel.

See Also

IDecklinkKeyer Interface, set_AlphaBlendModeOn Method


IDecklinkKeyer::set_AlphaAutoBlendSettings

The set_AlphaAutoBlendSettings method is used to configure the auto blending feature.

Syntax

HRESULT set_AlphaAutoBlendSettings(
    uint rampFrames,
    uint onFrames,
    uint offFrames,
    uint blendProcessRepeats
);

Parameters

rampFrames

[in] Number of frames that the blend effect takes to transition from blended to non-blended and vice-versa.

onFrames

[in] A value indicating the number of frames that the blending effect will be retained for.

offFrames

[in] A value indicating the number of frames that the blending effect will off for.

blendProcessRepeats

[in] Flag indicating if the auto blend feature will be turned on or off. Specify TRUE to enable the auto blend mode. Specify FALSE to disable it.

Return Values

Value | Description
E_UNEXPECTED | The decklink driver has not been initialized correctly.
E_FAIL | General failure adjusting auto blend mode.
S_OK | Success.
Remarks

The auto blend mode of the DeckLink card enables a key source to be faded up and down in a cyclic fashion. This is useful for displaying bugs, watermarks and repetitive logos etc.

The blended effect will be held constantly for the number of frames specified by the onFrames argument. Conversely the constant non-blended effect will be held for offFrames frames. The effect will transition on and off in rampFrames frames.

The auto mode will be retained until it is disabled by calling this method again, specifying FALSE for the blendProcessRepeats argument.

See Also

IDecklinkKeyer Interface, do_AlphaRampOn Method, do_AlphaRampOff Method


IDecklinkKeyer::do_AlphaRampOn

The do_AlphaRampOn method gradually ramps the key blend effect on over a specified period of frames.

Syntax

HRESULT do_AlphaRampOn(
    uint framesDuration
);

Parameters

framesDuration

[in] A value being the number of frames that will be taken to gradually ramp the key blending effect on.

Return Values

Value | Description
E_FAIL | General failure to activate alpha keying mode.
S_OK | Success.
Remarks

Call this method to gradually activate alpha blending. After this method has been called, for the next frameDuration frames the key opacity will be increased from 0 to the value specified by the set_AlphaLevel property.

See Also

IDecklinkKeyer Interface, set_AlphaLevel Property, do_AlphaRampOff Method


IDecklinkKeyer::do_AlphaRampOff

The do_AlphaRampOff method gradually ramps the key blend effect off over a specified period of frames.

Syntax

HRESULT do_AlphaRampOff(
    uint framesDuration
);

Parameters

framesDuration

[in] A value being the number of frames that will be taken to gradually ramp the key blending effect off.

Return Values

Value | Description
E_FAIL | General failure to activate alpha keying mode.
S_OK | Success.
Remarks

Call this method to gradually deactivate alpha blending. After this method has been called, for the next frameDuration frames the key opacity will be decreased from the value specified by the set_AlphaLevel property to 0.

See Also

IDecklinkKeyer Interface, set_AlphaLevel Property, do_AlphaRampOn Method


IDecklinkKeyer::get_DeviceSupportsKeying

The get_DeviceSupportsKeying property indicates if the installed DeckLink card supports alpha keying.

Syntax

HRESULT get_DeviceSupportsKeying(void);

Parameters

Return Values

Value | Description
E_FAIL | The installed DeckLink card does NOT support alpha keying.
S_OK | The installed DeckLink card DOES support alpha keying.
Remarks

Call this method before any other method on the IDecklinkKeyer interface to determine if the installed card supports the keying facility.

See Also

IDecklinkKeyer Interface, get_DeviceSupportsExternalKeying Property


IDecklinkKeyer::get_DeviceSupportsExternalKeying

The get_DeviceSupportsExternalKeying property returns a value indicating if the installed DeckLink card can send a key and fill source independently to an external keyer device.

Syntax

HRESULT get_DeviceSupportsExternalKeying(void);

Parameters

Return Values

Value | Description
E_FAIL | The installed DeckLink card does NOT support external keying.
S_OK | The installed DeckLink card DOES support external keying.
Remarks

Call this method before calling the set_AlphaBlendModeOn method with the isExternalKey argument set to TRUE.

See Also

IDecklinkKeyer Interface, get_DeviceSupportsKeying Property, set_AlphaBlendModeOn Method


IDecklinkRawDeviceControl Interface

The IDecklinkRawDeviceControl interface provides direct access to the RS-422 port of the DeckLink card as well as the ability to receive responses from the attached device. The 'Raw' nature of the command interface enables application writers to target features of specific devices. Although this interface is considered 'raw', the structure of the commands must follow that specified by the Sony RS-422 9-Pin protocol (checksum consisting of the lower 8 bits of the sum of all bytes in the command is appended as the final byte of the command).

The DeckLink Video Capture and DeckLink Video Render filters implements this interface.

In addition to the methods inherited from IUnknown, the IDecklinkRawDeviceControl interface exposes the following methods.

Method | Description
SendRawCommandSync | Sends a command to the attached device and returns the device's response in a synchronous manner.
SendRawCommandAsync | Sends a command to the attached device and returns immediately. The response may optionally be obtained in an asynchronous manner.


IDecklinkRawDeviceControl::SendRawCommandSync

The SendRawCommandSync sends a specified raw RS-422 command to the attached device and waits for a response. The response is populated into the supplied buffer.

Syntax

HRESULT SendRawCommandSync(
    const byte* command,
    uint lenCommand,
    byte* response,
    uint* lenResponse
);

Parameters

command

[in] The raw command to be sent to the attached device. This buffer must include the calculated checksum as its final byte.

lenCommand

[in] The length of command in bytes. This length must include the trailing checksum.

response

[in, out] Application supplied buffer that upon return will hold the response from the attached device.

lenResponse

[in, out] On entry, this argument specifies the length, in bytes, of the response buffer. Upon successful return, this value is updated with the actual length of the response.

Return Values

Value | Description
S_OK | Success.
E_FAIL | General failure to send or receive command.
ERROR_TIMEOUT | Operation timed out waiting for a valid response from the attached device.
ERROR_INSUFFICIENT_BUFFER | The response buffer was insufficient to hold the full response from the device. The partial response that can fit into the supplied buffer has been populated.
Remarks

Call this method to send any formatted Sony RS-422 command to the attached device and receive the associated response. Note that although no processing is performed on the dispatched command, the expected response from the device must hold the length as the first byte (as per Sony RS-422 protocol specification).

Note that this method will not return to the caller until either a valid response is received or the operation times out. The timeout value is fixed at 5000 ms and cannot be adjusted. See the SendRawCommandAsync for equivalent functionality in an asynchronous mode.

See Also

IDecklinkRawDeviceControl Interface, SendRawCommandAsync


IDecklinkRawDeviceControl::SendRawCommandAsync

The SendRawCommandAsync sends a specified raw RS-422 command to the attached device and returns immediately to the caller. The response from the command is populated to buffers supplied to this service and notification is signalled via a specified event handle.

Syntax

HRESULT SendRawCommandAsync(
    DecklinkRawCommandAsync* args
);

Parameters

args

[in] A pointer to a DecklinkRawCommandAsync structure containing the command to send and a buffer which is populated with the command's response and an event handle that is signalled when the command has completed. It is the caller's responsibility to ensure that this pointer will be valid and all memory pointed to by members of this structure is valid beyond the lifetime of this call (until the command has been completed).

Return Values

Value | Description
S_OK | Success.
E_FAIL | General failure to send or receive command.
ERROR_TIMEOUT | Operation timed out waiting for a valid response from the attached device.
ERROR_INSUFFICIENT_BUFFER | The response buffer was insufficient to hold the full response from the device. The partial response that can fit into the supplied buffer has been populated.
Remarks

Call this method to send any formatted Sony RS-422 command to the attached device and receive the associated response. Note that although no processing is performed on the dispatched command, the expected response from the device must hold the length as the first byte (as per Sony RS-422 protocol specification).

This service returns to the caller immediately after the command has been queued to be sent to the attached device. Completion of the command is signalled via the .commandComplete member of the args argument. For synchronous command dispatch and reply operation use the SendRawCommandSync service.

See Also

IDecklinkRawDeviceControl Interface, SendRawCommandSync


IDecklinkRawDeviceControl::SendRawCommandAsync

DeckLink DirectShow Documentation

IADecklinkRawDeviceControl::SendRawCommandAsync2

The SendRawCommandAsync2 sends a specified raw RS-422 command to the attached device and returns immediately to the caller. The response from the command is populated to buffers supplied to this service and notification is signalled via a specified event handle. This property has the same function as IDecklinkRawDeviceControl::SendRawCommandAsync except that the DecklinkRawCommandAsync structure is broken into and array of VARIANT structures as described below.

Syntax

HRESULT SendRawCommandAsync2(
    VARIANT* rawCommand,
    UINT cRawCommand
);

Parameters

rawCommand

[in, out] A pointer to an array of six VARIANT structures which are defined as follows:

Element | Variant Type | Description
0 | VT_BYREF | VT_UI1 | See DecklinkRawCommandAsync::command
1 | VT_UINT | See DecklinkRawCommandAsync::lenCommand
2 | VT_I4 | See DecklinkRawCommandAsync::asyncResult
3 | VT_BYREF | VT_UI1 | See DecklinkRawCommandAsync::response
4 | VT_UINT | See DecklinkRawCommandAsync::lenResponse
5 | VT_I4 | See DecklinkRawCommandAsync::commandComplete

cRawCommand

[in] The size of the array.

Return Values

Value | Description
S_OK | Success.
E_POINTER | A NULL pointer was passed in.
E_OUTOFMEMORY | There are not enough elements in the array.
E_FAIL | General failure to send or receive command.
ERROR_TIMEOUT | Operation timed out waiting for a valid response from the attached device.
ERROR_INSUFFICIENT_BUFFER | The response buffer was insufficient to hold the full response from the device. The partial response that can fit into the supplied buffer has been populated.
Remarks

Call this method to send any formatted Sony RS-422 command to the attached device and receive the associated response. Note that although no processing is performed on the dispatched command, the expected response from the device must hold the length as the first byte (as per Sony RS-422 protocol specification).

This service returns to the caller immediately after the command has been queued to be sent to the attached device. Completion of the command is signalled via the .commandComplete member of the args argument. For synchronous command dispatch and reply operation use the SendRawCommandSync service.

See Also

IDecklinkRawDeviceControl Interface, SendRawCommandSync


DecklinkRawCommandAsync Structure

The DecklinkRawCommandAsync structure contains information used by IDecklinkRawDeviceControl::SendRawCommandAsync service to send and receive a raw RS-422 command asynchronously.

Syntax

struct DecklinkRawCommandAsync
{
   byte*   command;
   UINT    lenCommand;
   HRESULT asyncResult;
   byte*   response;
   UINT    lenResponse;
   HANDLE  commandComplete;
};

Members

command

The raw command to be sent to the attached device. This buffer must include the calculated checksum as its final byte.

lenCommand

The size, in bytes, of the command held in the command member. This length must include the final byte checksum.

asyncResult

The result code of the operation. This is only populated upon completion of the command and can contain any of the following values:

Value | Description
S_OK | Command was dispatched and a respone was received successfully.
E_FAIL | General failure to send or receive command.
ERROR_TIMEOUT | Operation timed out waiting for a valid response from the attached device.
ERROR_INSUFFICIENT_BUFFER | The size of the response buffer specified by the lenResponse member was insufficient to hold the full response from the device. The partial response that can fit into the supplied buffer has been populated.

response

A pointer to an application supplied buffer to receive the device's response to the command. Sizing of this buffer is specified by the lenResponse member (see below). If this value is NULL, no response data is returned to the caller.

lenResponse

On entry, this member specifies the size, in bytes, of the buffer pointed by the response member. Upon completion, this value is updated to indicate the size, in bytes, of the data written to the response buffer. If the response member is NULL, this value is ignored.

commandComplete

An optional event handle that will be set into a signalled state by the component when the command has completed either successfully or unsuccessfully. If this value is NULL, the application must poll the asyncResult member to determine when the command has completed.

Remarks

This structure is passed as an argument to the IDecklinkRawDeviceControl::SendRawCommandAsync service. It is the caller's responsibility to manage the memory pointed to by members of this structure.

See Also

IDecklinkRawDeviceControl Interface


IDecklinkStatus Interface

The IDecklinkStatus interface provides information about the video inputs of the DeckLink card.

The DeckLink Video Capture filter is the only filter to implement this interface.

In addition to the methods inherited from IUnknown, the IDecklinkStatus interface exposes the following methods.

Method | Description
GetVideoInputStatus | Returns the status of the video inputs on a DeckLink card.
RegisterVideoStatusChangeEvent | Enables an event to be signalled whenever the status of an input on a DeckLink card changes.


IDecklinkStatus::GetVideoInputStatus

The GetVideoInputStatus returns the status of the video and genlock inputs on a DeckLink card.

Syntax

HRESULT GetVideoInputStatus(
    int* videoStatus,
    int* genlockStatus
);

Parameters

videoStatus

[out] The video status; one of the following DECKLINK_INPUT enumeration values:

Value | Description
DECKLINK_INPUT_NONE | Input is not present.
DECKLINK_INPUT_PRESENT | Input is present.

genlockStatus

[out] The genlock status; one of the following DECKLINK_GENLOCK enumeration values:

Value | Description
DECKLINK_GENLOCK_NOTSUPPORTED | Genlock is not available on the DeckLink card.
DECKLINK_GENLOCK_NOTCONNECTED | Genlock is available but no valid signal is connected.
DECKLINK_GENLOCK_LOCKED | Genlock is available and is locked to the input.
DECKLINK_GENLOCK_NOTLOCKED | Genlock is available but is not locked to the input.

Return Values

Value | Description
S_OK | Success.
E_POINTER | NULL pointer argument(s).
E_FAIL | Failure.
Remarks

Call this method to query the status of the video inputs on a DeckLink card and to confirm if the genlock input matches the video input.

See Also

IDecklinkStatus Interface, RegisterVideoStatusChangeEvent


IDecklinkStatus::RegisterVideoStatusChangeEvent

The RegisterVideoStatusChangeEvent registers a client managed event with the filter. Whenever the status of the video changes the filter calls SetEvent with the handle.

Syntax

HRESULT RegisterVideoStatusChangeEvent(
    unsigned long event
);

Parameters

event

[in] An event handle that is signalled when the video status changes. It is the caller's responsibility to create and close the event handle.

Return Values

Value | Description
S_OK | Success.
Remarks

Provides a signalling mechanism to monitor changes in the status of the video inputs on a DeckLink card.

CComPtr<IBaseFilter> pDecklinkVideoCapture = NULL

/*
 * Create DeckLink capture filter and add it to the graph.
*/

HANDLE hInputStatusChangeEvent = CreateEvent(NULL, FALSE, TRUE, "Application No Input Event");
ASSERT(hInputStatusChangeEvent);

// Query the filter for the IDecklinkStatus interface.
CComQIPtr<IDecklinkStatus, &IID_IDecklinkStatus> pIDS = pDecklinkVideoCapture;
if (pIDS)
{
    // Register our event with the filter.
    hr = m_pIDS->RegisterVideoStatusChangeEvent((unsigned long)hInputStatusChangeEvent);
}

See Also

IDecklinkStatus Interface, GetVideoInputStatus


IDecklinkCaptureBanner Interface

The IDecklinkCaptureBanner interface provides methods to configure the 'No Input' banner presented during capture when there is no valid signal is detected on the input to a DeckLink card. This interface provides direct access to the 'No Input' frame buffer which is only available when the capture pin of the video capture filter is connected.

The DeckLink Video Capture filter is the only filter to implement this interface.

In addition to the methods inherited from IUnknown, the IDecklinkCaptureBanner interface exposes the following methods.

Method | Description
GetNoInputFrame | Returns a pointer to the 'No Input' frame.
BlackFrame | Fills a video frame with black.


IDecklinkCaptureBanner::GetNoInputFrame

The GetNoInputFrame method provides a pointer to the video frame that is used when there is no valid signal detected on the input of a DeckLink card.

Syntax

HRESULT GetNoInputFrame(
    byte** frame
);

Parameters

frame

[out] A pointer to a pointer that receives the address of the 'No Input' frame buffer.

Return Values

Value | Description
S_OK | Success.
E_POINTER | NULL pointer argument.
Remarks

Call this method get a pointer to the 'No Input' video frame which is presented on capture when no valid input is detected. If the filter output pin "Capture" is NOT connected the returned pointer will be NULL. Do NOT attempt to use a returned pointer if the output pin "Capture" is subsequently disconnected as the pointer will more than likely point to an invalid area of memory.

See Also

IDecklinkCaptureBanner Interface, BlackFrame


IDecklinkCaptureBanner::BlackVideo

The BlackVideo method can be used to create a frame of black video.

Syntax

HRESULT BlackVideo(
    byte* bmih,
    byte* frame
);

Parameters

bmih

[in] A pointer to a BITMAPINFOHEADER structure that describes the frame.

frame

[in] A pointer to the frame buffer.

Return Values

Value | Description
S_OK | Success.
E_POINTER | NULL pointer argument(s).
E_INVALIDARG | The biSize field of the BITMAPINFOHEADER structure is invalid.
E_FAIL | Unsupported compression.
Remarks

A utility method to use in conjunction with, or independant of, IDecklinkCaptureBanner::GetNoInputFrame. Call this method to create a frame of black video. The compression field of bmih is inspected to determine the format of the video. The following compression types are supported: UYVY, HDYC, YUY2, v210, BI_RGB (8-bit RGB + Alpha) and r210.

See Also

IDecklinkCaptureBanner Interface, GetNoInputFrame


IDecklinkIOControl Interface

The IDecklinkIOControl interface provides methods to control video and audio I/O on DeckLink cards.

All filters implement this interface.

In addition to the methods inherited from IUnknown, the IDecklinkIOControl interface exposes the following methods.

Method | Description
GetIOFeatures | Get the IO features of a DeckLink card.
SetAnalogueOutput | Sets the analogue video output.
SetVideoInput | Sets the video input.
SetDualLinkOutput | Sets dual link output mode.
SetSingleFieldOutputForSynchronousFrames | Sets single field output mode when playback is paused.
SetHDTVPulldownOnOutput | Sets the 3:2 pulldown output mode operation for HD23.976 video.
SetBlackToDeckInCapture | Sets channel B output when capturing.
SetAFrameReference | Sets the A-frame reference for 3:2 pulldown removal.
SetCaptureVANCLines | Sets the VANC lines which are captured into the active picture.
SetVideoOutputDownconversionMode | Sets the hardware HD downconversion mode.
SetAudioInputSource | Sets the audio input source.
SetGenlockTiming | Adjusts the timing offset of the genlock input.
SetVideoOutputDownconversionMode2 | Sets the hardware HD downconversion mode.
SetCaptureTimecodeSource | Sets the timecode source.
SetVideoInput2 | Sets the video input.
SetAnalogueOutput2 | Sets the analogue video output.


IDecklinkIOControl::GetIOFeatures

The GetIOFeatures returns the IO options available on a DeckLink card.

Syntax

HRESULT GetIOFeatures(
    unsigned long* features
);

Parameters

features

[out] A pointer that receives a set of flags from a DECKLINK_IOFEATURES enumeration.

Value | Description
DECKLINK_IOFEATURES_SUPPORTSRGB10BITCAPTURE | DeckLink card supports 10-bit RGB capture.
DECKLINK_IOFEATURES_SUPPORTSRGB10BITPLAYBACK | DeckLink card supports 10-bit RGB playback.
DECKLINK_IOFEATURES_SUPPORTSINTERNALKEY | DeckLink card supports internal keying.
DECKLINK_IOFEATURES_SUPPORTSEXTERNALKEY | DeckLink card supports external keying.
DECKLINK_IOFEATURES_HASCOMPONENTVIDEOOUTPUT | DeckLink card has component video output.
DECKLINK_IOFEATURES_HASCOMPOSITEVIDEOOUTPUT | DeckLink card has composite video output.
DECKLINK_IOFEATURES_HASDIGITALVIDEOOUTPUT | DeckLink card has digital video output.
DECKLINK_IOFEATURES_HASDVIVIDEOOUTPUT | DeckLink card has DVI video output.
DECKLINK_IOFEATURES_HASCOMPONENTVIDEOINPUT | DeckLink card has component video input.
DECKLINK_IOFEATURES_HASCOMPOSITEVIDEOINPUT | DeckLink card has composite video input.
DECKLINK_IOFEATURES_HASDIGITALVIDEOINPUT | DeckLink card has digital video input.
DECKLINK_IOFEATURES_HASDUALLINKOUTPUT | DeckLink card supports dual link output.
DECKLINK_IOFEATURES_HASDUALLINKINPUT | DeckLink card supports dual link input.
DECKLINK_IOFEATURES_SUPPORTSHD | DeckLink card supports HD.
DECKLINK_IOFEATURES_SUPPORTS2KOUTPUT | DeckLink card supports 2K output.
DECKLINK_IOFEATURES_SUPPORTSHDDOWNCONVERSION | DeckLink card supports HD downconversion.
DECKLINK_IOFEATURES_HASAESAUDIOINPUT | DeckLink card has S/PDIF audio input.
DECKLINK_IOFEATURES_HASANALOGUEAUDIOINPUT | DeckLink card has analogue audio input.
DECKLINK_IOFEATURES_HASSVIDEOINPUT | DeckLink card has S-video input.
DECKLINK_IOFEATURES_HASSVIDEOOUTPUT | DeckLink card has S-video output.
DECKLINK_IOFEATURES_SUPPORTSMULTICAMERAINPUT | DeckLink card supports multicamera video input.

Return Values

Value | Description
S_OK | Success.
E_FAIL | Failure.
E_POINTER | NULL pointer argument.
Remarks

Call this method to determine the IO support available on a DeckLink card.

See Also

IDecklinkIOControl Interface, SetAnalogueOutput, SetVideoInput, SetDualLinkOutput, SetSingleFieldOutputForSynchronousFrames, SetHDTVPulldownOnOutput, SetBlackToDeckInCapture, SetAFrameReference, SetCaptureVANCLines, SetVideoOutputDownconversionMode, SetAudioInputSource, SetGenlockTiming, SetVideoOutputDownconversionMode2, SetCaptureTimecodeSource, SetVideoInput2


IDecklinkIOControl::SetAnalogueOutput

The SetAnalogueOutput method configures the analogue video output of a DeckLink card.

Syntax

HRESULT SetAnalogueOutput(
    BOOL isComponent,
    BOOL setupIs75
);

Parameters

isComponent

[in] A boolean value, TRUE for component video ouput or FALSE for composite video output (on Y).

setupIs75

[in] A boolean value, TRUE for 7.5 IRE or FALSE for 0.0 IRE.

Return Values

Value | Description
S_OK | Success.
E_FAIL | Failure.
Remarks

The second parameter is only applicable to NTSC video and sets the black level to 7.5 IRE which is used in the USA or 0.0 IRE which is used in Japan.

See Also

IDecklinkIOControl Interface, GetIOFeatures, SetVideoInput, SetDualLinkOutput, SetSingleFieldOutputForSynchronousFrames, SetHDTVPulldownOnOutput, SetBlackToDeckInCapture, SetAFrameReference, SetCaptureVANCLines, SetVideoOutputDownconversionMode, SetAudioInputSource, SetGenlockTiming, SetVideoOutputDownconversionMode2, SetCaptureTimecodeSource, SetVideoInput2, SetAnalogueOutput2


IDecklinkIOControl::SetVideoInput

The SetVideoInput method selects the video input of a DeckLink card. This method has been deprecated, please use SetVideoInput2.

Syntax

HRESULT SetVideoInput(
    BOOL inputIsDigital,
    BOOL isComponent,
    BOOL setupIs75
);

Parameters

inputIsDigital

[in] A boolean value, TRUE for digital video input or FALSE for analogue video input.

isComponent

[in] A boolean value, TRUE for component video input or FALSE for composite video input (on Y).

setupIs75

[in] A boolean value, TRUE for 7.5 IRE or FALSE for 0.0 IRE.

Return Values

Value | Description
S_OK | Success.
E_FAIL | Failure.
Remarks

The third parameter is only applicable to NTSC video and sets the black level to 7.5 IRE which is used in the USA or 0.0 IRE which is used in Japan.

See Also

IDecklinkIOControl Interface, GetIOFeatures, SetAnalogueOutput, SetDualLinkOutput, SetSingleFieldOutputForSynchronousFrames, SetHDTVPulldownOnOutput, SetBlackToDeckInCapture, SetAFrameReference, SetCaptureVANCLines, SetVideoOutputDownconversionMode, SetAudioInputSource, SetGenlockTiming, SetVideoOutputDownconversionMode2, SetCaptureTimecodeSource, SetVideoInput2, SetAnalogueOutput2


IDecklinkIOControl::SetDualLinkOutput

The SetDualLinkOutput method is used to configure the dual link video output mode on cards that support dual link, e.g. DeckLink HD Pro.

Syntax

HRESULT SetDualLinkOutput(
    BOOL enableDualLinkOutput
);

Parameters

enableDualLinkOutput

[in] A boolean value to enable dual link output (TRUE) or disable dual link output (FALSE).

Return Values

Value | Description
S_OK | Success.
E_FAIL | Failure.
Remarks

Call this method to set the hardware dual link video output mode.

See Also

IDecklinkIOControl Interface, GetIOFeatures, SetAnalogueOutput, SetVideoInput, SetSingleFieldOutputForSynchronousFrames, SetHDTVPulldownOnOutput, SetBlackToDeckInCapture, SetAFrameReference, SetCaptureVANCLines, SetVideoOutputDownconversionMode, SetAudioInputSource, SetGenlockTiming, SetVideoOutputDownconversionMode2, SetCaptureTimecodeSource, SetVideoInput2, SetAnalogueOutput2


IDecklinkIOControl::SetSingleFieldOutputForSynchronousFrames

The SetSingleFieldOutputForSynchronousFrames method sets the video output to a single field when playback is paused.

Syntax

HRESULT SetSingleFieldOutputForSynchronousFrames(
    BOOL singleFieldOutput
);

Parameters

singleFieldOutput

[in] A boolean value to enable single field output (TRUE) or disable single field output (FALSE).

Return Values

Value | Description
S_OK | Success.
E_FAIL | Failure.
Remarks

When editing frame based material the flicker introduced by interlacing can be removed using this method. This will only happen when playback is paused and does NOT affect the video output during normal playback, e.g. when printing to tape.

See Also

IDecklinkIOControl Interface, GetIOFeatures, SetAnalogueOutput, SetVideoInput, SetDualLinkOutput, SetHDTVPulldownOnOutput, SetBlackToDeckInCapture, SetAFrameReference, SetCaptureVANCLines, SetVideoOutputDownconversionMode, SetAudioInputSource, SetGenlockTiming, SetVideoOutputDownconversionMode2, SetCaptureTimecodeSource, SetVideoInput2, SetAnalogueOutput2


IDecklinkIOControl::SetHDTVPulldownOnOutput

The SetHDTVPulldownOnOutput method controls the 3:2 pulldown output mode on DeckLink cards that support HD.

Syntax

HRESULT SetHDTVPulldownOnOutput(
    BOOL enableHDTV32PulldownOnOutput
);

Parameters

enableHDTV32PulldownOnOutput

[in] A boolean value to enable (TRUE) or disable (FALSE) 3:2 pulldown operation for HD23.976 video modes.

Return Values

Value | Description
S_OK | Success.
E_FAIL | Failure.
Remarks

DeckLink cards that support HD video modes can automatically insert the extra video fields to convert HD23.976 video to HD29.97 video.

See Also

IDecklinkIOControl Interface, GetIOFeatures, SetAnalogueOutput, SetVideoInput, SetDualLinkOutput, SetSingleFieldOutputForSynchronousFrames, SetBlackToDeckInCapture, SetAFrameReference, SetCaptureVANCLines, SetVideoOutputDownconversionMode, SetAudioInputSource, SetGenlockTiming, SetVideoOutputDownconversionMode2, SetCaptureTimecodeSource, SetVideoInput2, SetAnalogueOutput2


IDecklinkIOControl::SetBlackToDeckInCapture

The SetBlackToDeckInCapture method configures the video output of a DeckLink card when capturing.

Syntax

HRESULT SetBlackToDeckInCapture(
    unsigned long blackToDeckSetting
);

Parameters

blackToDeckSetting

[in] One of the following values from DECKLINK_BLACKINCAPTURE enumeration.

Value | Description
DECKLINK_BLACKINCAPTURE_NONE | Disable black output.
DECKLINK_BLACKINCAPTURE_DIGITAL | Output stable black video on SDI video output.
DECKLINK_BLACKINCAPTURE_ANALOGUE | Output stable black video on analogue video output.

Return Values

Value | Description
S_OK | Success.
E_FAIL | Failure.
E_INVALIDARG | Argument is out of range, re. DECKLINK_BLACKINCAPTURE enumeration.
Remarks

The normal operating mode of a DeckLink card during capture is to pass the input signal (from the Deck) directly to the video outputs for monitoring. Some setups may have one of these outputs connected to the deck, which the deck will use as a video reference. In order to provide a stable reference this method is used to set which outputs are black video during capture.

See Also

IDecklinkIOControl Interface, GetIOFeatures, SetAnalogueOutput, SetVideoInput, SetDualLinkOutput, SetSingleFieldOutputForSynchronousFrames, SetHDTVPulldownOnOutput, SetAFrameReference, SetCaptureVANCLines, SetVideoOutputDownconversionMode, SetAudioInputSource, SetGenlockTiming, SetVideoOutputDownconversionMode2, SetCaptureTimecodeSource, SetVideoInput2, SetAnalogueOutput2


IDecklinkIOControl::SetAFrameReference

The SetAFrameReference method specifies the timecode on tape at which the A-frame reference is present for 3:2 pulldown operation.

Syntax

HRESULT Set AFrameReference(
    unsigned long aFrameReference
);

Parameters

aFrameReference

[in] The timecode frame number which corresponds to the A-frame reference.

Return Values

Value | Description
S_OK | Success.
E_FAIL | Failure.
Remarks

With the DeckLink Video Capture filter it is possible to remove 3:2 pulldown thus returning video footage back to its original frame rate. In order to achieve this the hardware needs to know the frame number at which the 3:2 pulldown sequence begins. This method specifies the timecode on tape where the 3:2 pulldown sequence begins, this is known as the A-frame reference.

NOTE

3:2 pulldown is the technique applied to convert film running at 23.976 frames per second to NTSC running at 29.97 frames per second. Four film frames are used to provide 5 NTSC video frames by repeating video fields. Film frames A, B, C and D are converted to video fields A1A2, B1B2, etc. These video fields are then combined in the following 3:2 sequence to produce NTSC video: A1A2 A1B2 B1C2 C1C2 D1D2, A1A2 A1B2 ....

See Also

IDecklinkIOControl Interface, GetIOFeatures, SetAnalogueOutput, SetVideoInput, SetDualLinkOutput, SetSingleFieldOutputForSynchronousFrames, SetHDTVPulldownOnOutput, SetBlackToDeckInCapture, SetCaptureVANCLines, SetVideoOutputDownconversionMode, SetAudioInputSource, SetGenlockTiming, SetVideoOutputDownconversionMode2, SetCaptureTimecodeSource, SetVideoInput2, SetAnalogueOutput2


IDecklinkIOControl::SetCaptureVANCLines

The SetCaptureVANCLines method controls which VANC lines are captured into lines 1, 2 and 3 of active video.

Syntax

HRESULT SetCaptureVANCLines(
    unsigned long vancLine1,
    unsigned long vancLine2,
    unsigned long vancLine3
);

Parameters

vancLine1

[in] The VANC line number or zero to disable.

vancLine2

[in] The VANC line number or zero to disable.

vancLine3

[in] The VANC line number or zero to disable.

Return Values

Value | Description
S_OK | Success.
E_FAIL | Failure.
Remarks

This is one of two methods of accessing VANC data. This technique replaces one of the first three lines of active video with the nominated line from VANC. One possible use for this would be to extract timecode data from VANC. The other method would be to use the VANC pin on the DeckLink Video Capture filter to access all of the VANC lines.

See Also

IDecklinkIOControl Interface, GetIOFeatures, SetAnalogueOutput, SetVideoInput, SetDualLinkOutput, SetSingleFieldOutputForSynchronousFrames, SetHDTVPulldownOnOutput, SetBlackToDeckInCapture, SetAFrameReference, SetVideoOutputDownconversionMode, SetAudioInputSource, SetGenlockTiming, SetVideoOutputDownconversionMode2, SetCaptureTimecodeSource, SetVideoInput2, SetAnalogueOutput2


IDecklinkIOControl::SetVideoOutputDownConversionMode

The SetVideoOutputDownConversionMode method sets the hardware downconversion mode on DeckLink cards that support downconversion.

Syntax

HRESULT SetVideoOutputDownConversionMode(
    unsigned long downconversionMode
);

Parameters

downconversionMode

[in] One of the following values from DECKLINK_HDDOWNCONVERSION enumeration.

Value | Description
DECKLINK_HDDOWNCONVERSION_OFF | Disable hardware downconversion.
DECKLINK_HDDOWNCONVERSION_LB16X9 | Enable hardware downconversion, output will be SD 16:9 letter box.
DECKLINK_HDDOWNCONVERSION_ANA | Enable hardware downconversion, output will be SD anamorphic.
DECKLINK_HDDOWNCONVERSION_CENTER | Enable hardware downconversion, output will be SD center cut (currently supported only on the Multibridge Extreme).

Return Values

Value | Description
S_OK | Success.
E_FAIL | Failure.
E_INVALIDARG | Argument is out of range, re. DECKLINK_HDDOWNCONVERSION enumeration.
Remarks

Call this method to set the hardware HD downconversion mode on DeckLink cards that support this feature. For example, on the DeckLink HD Pro this method modifies the output on channel A and the analogue output. Channel B is unaffected.

See Also

IDecklinkIOControl Interface, GetIOFeatures, SetAnalogueOutput, SetVideoInput, SetDualLinkOutput, SetSingleFieldOutputForSynchronousFrames, SetHDTVPulldownOnOutput, SetBlackToDeckInCapture, SetAFrameReference, SetCaptureVANCLines, SetAudioInputSource, SetGenlockTiming, SetVideoOutputDownconversionMode2, SetCaptureTimecodeSource, SetVideoInput2, SetAnalogueOutput2


IDecklinkIOControl::SetAudioInputSource

The SetAudioInputSource method selects the audio input of a DeckLink card.

Syntax

HRESULT SetAudioInputSource(
    unsigned long audioInputSource
);

Parameters

audioInputSource

[in] One of the following values from DECKLINK_AUDIOINPUTSOURCE enumeration.

Value | Description
DECKLINK_AUDIOINPUTSOURCE_DECKLINK | See remarks.
DECKLINK_AUDIOINPUTSOURCE_AESEBU | The S/PDIF input is used as the source of audio.

Return Values

Value | Description
S_OK | Success.
E_FAIL | Failure.
E_INVALIDARG | Argument is out of range, re. DECKLINK_AUDIOINPUTSOURCE enumeration.
Remarks

Currently, when DECKLINK_AUDIOINPUTSOURCE_DECKLINK is specified the source of audio will depend upon the selected source of video. If the video input is SDI then the embedded audio is the source. If the video input is analogue then the analogue audio is the source.

See Also

IDecklinkIOControl Interface, GetIOFeatures, SetAnalogueOutput, SetVideoInput, SetDualLinkOutput, SetSingleFieldOutputForSynchronousFrames, SetHDTVPulldownOnOutput, SetBlackToDeckInCapture, SetAFrameReference, SetCaptureVANCLines, SetVideoOutputDownconversionMode, SetGenlockTiming, SetVideoOutputDownconversionMode2, SetCaptureTimecodeSource, SetVideoInput2, SetAnalogueOutput2


IDecklinkIOControl::SetGenlockTiming

The SetGenlockTiming method sets adjusts the timing of the genlock input on a DeckLink Extreme card.

Syntax

HRESULT SetGenlockTiming(
    int timingOffset
);

Parameters

timingOffset

[in] An integer value in the range ±9.435µs in steps of 37ns

Return Values

Value | Description
S_OK | Success.
E_FAIL | Failure.
E_INVALIDARG | Argument is out of range.
Remarks

Use this method to adjust the timing offset of the genlock input. This feature will only function on a DeckLink Extreme card.

See Also

IDecklinkIOControl Interface, GetIOFeatures, SetAnalogueOutput, SetVideoInput, SetDualLinkOutput, SetSingleFieldOutputForSynchronousFrames, SetHDTVPulldownOnOutput, SetBlackToDeckInCapture, SetAFrameReference, SetCaptureVANCLines, SetVideoOutputDownconversionMode, SetAudioInputSource, SetVideoOutputDownconversionMode2, SetCaptureTimecodeSource, SetVideoInput2, SetAnalogueOutput2


IDecklinkIOControl::SetVideoOutputDownConversionMode2

The SetVideoOutputDownConversionMode2 method sets the hardware downconversion mode on DeckLink cards that support downconversion.

Syntax

HRESULT SetVideoOutputDownConversionMode2(
    unsigned long downconversionMode,
    unsigned long downconvertToAnalogOutput
);

Parameters

downconversionMode

[in] One of the following values from DECKLINK_HDDOWNCONVERSION enumeration.

Value | Description
DECKLINK_HDDOWNCONVERSION_OFF | Disable hardware downconversion.
DECKLINK_HDDOWNCONVERSION_LB16X9 | Enable hardware downconversion, output will be SD 16:9 letter box.
DECKLINK_HDDOWNCONVERSION_ANA | Enable hardware downconversion, output will be SD anamorphic.
DECKLINK_HDDOWNCONVERSION_CENTER | Enable hardware downconversion, output will be SD center cut (currently supported only on the Multibridge Extreme).

downconvertToAnalogOutput

[in] A boolean value to enable downconversion to the analog outputs (TRUE) or disable downconversion to the analog outputs (FALSE).

Return Values

Value | Description
S_OK | Success.
E_FAIL | Failure.
E_INVALIDARG | Argument is out of range, re. DECKLINK_HDDOWNCONVERSION enumeration.
Remarks

Call this method to set the hardware HD downconversion mode on DeckLink cards that support this feature. For example, on the DeckLink HD Pro this method modifies the output on channel A and, optionally, the analog output. Channel B is unaffected.

See Also

IDecklinkIOControl Interface, GetIOFeatures, SetAnalogueOutput, SetVideoInput, SetDualLinkOutput, SetSingleFieldOutputForSynchronousFrames, SetHDTVPulldownOnOutput, SetBlackToDeckInCapture, SetAFrameReference, SetCaptureVANCLines, SetVideoOutputDownconversionMode, SetAudioInputSource, SetGenlockTiming, SetCaptureTimecodeSource, SetVideoInput2, SetAnalogueOutput2


IDecklinkIOControl::SetCaptureTimecodeSource

The SetCaptureTimecodeSource method sets the timecode source when capturing timecode from a DeckLink card.

Syntax

HRESULT SetCaptureTimecodeSource(
    unsigned long timecodeSource
);

Parameters

timecodeSource

[in] One of the following values from DECKLINK_TIMECODESOURCE enumeration.

Value | Description
DECKLINK_TIMECODESOURCE_VITC | Read timecode from VITC (Vertical Interval Time Code).
DECKLINK_TIMECODESOURCE_HANC | Read timecode from HANC (Horizontal Ancilliary Data).

Return Values

Value | Description
S_OK | Success.
E_INVALIDARG | Argument is out of range, re. DECKLINK_TIMECODESOURCE enumeration.
Remarks

Call this method to specify which part of video will be used to read and decode timecode information. If VITC is to be used as the timecode source, then the signal, if present, will be decoded as per the SMPTE 12M specification. If HANC is to be used as the timecode source, then the signal, if present, will be decoded as per the SMPTE RP188 specification.

See Also

IDecklinkIOControl Interface, GetIOFeatures, SetAnalogueOutput, SetVideoInput, SetDualLinkOutput, SetSingleFieldOutputForSynchronousFrames, SetHDTVPulldownOnOutput, SetBlackToDeckInCapture, SetAFrameReference, SetCaptureVANCLines, SetVideoOutputDownconversionMode, SetAudioInputSource, SetGenlockTiming, SetVideoOutputDownconversionMode2, SetVideoInput2, SetAnalogueOutput2


IDecklinkIOControl::SetVideoInput2

The SetVideoInput2 method selects the video input of a DeckLink card. This interface adds control over cards with an S-video input and should be used in place of the SetVideoInput method.

Syntax

HRESULT SetVideoInput2(
    unsigned long videoSource,
    BOOL setupIs75,
    BOOL componentLevelsSMPTE
);

Parameters

videoSource

[in] One of the following values from a DECKLINK_VIDEOINPUT enumeration.

Value | Description
DECKLINK_VIDEOINPUT_SDI | Video input is taken from the digital input.
DECKLINK_VIDEOINPUT_COMPONENT | Video input is taken from the analogue component inputs.
DECKLINK_VIDEOINPUT_COMPOSITE | Video input is taken from the composite input.
DECKLINK_VIDEOINPUT_SVIDEO | Video input is taken from the S-video input.
DECKLINK_VIDEOINPUT_HDMI | Video input is taken from the HDMI input.

setupIs75

[in] A boolean value, TRUE for 7.5 IRE or FALSE for 0.0 IRE.

componentLevelsSMPTE

[in] A boolean value, TRUE for SMPTE component levels or FALSE for Betacam component levels.

Return Values

Value | Description
S_OK | Success.
E_FAIL | Failure.
E_INVALIDARG | Argument is out of range, re. DECKLINK_VIDEOINPUT enumeration.
Remarks

The second parameter is only applicable to NTSC video and sets the black level to 7.5 IRE which is used in the USA or 0.0 IRE which is used in Japan.

The third parameter is only applicable to the analogue component video levels and sets the levels of the colour difference channels in accordance to the SMPTE standard or boosts them by a factor of 4/3 for the Betacam format.

See Also

IDecklinkIOControl Interface, GetIOFeatures, SetAnalogueOutput, SetVideoInput, SetDualLinkOutput, SetSingleFieldOutputForSynchronousFrames, SetHDTVPulldownOnOutput, SetBlackToDeckInCapture, SetAFrameReference, SetCaptureVANCLines, SetVideoOutputDownconversionMode, SetAudioInputSource, SetGenlockTiming, SetVideoOutputDownconversionMode2, SetCaptureTimecodeSource, SetAnalogueOutput2


IDecklinkIOControl::SetAnalogueOutput2

The SetAnalogueOutput2 method configures the analogue video output of a DeckLink card.

Syntax

HRESULT SetAnalogueOutput2(
    unsigned long videoOutput,
    BOOL setupIs75,
    BOOL componentLevelsSMPTE
);

Parameters

videoOutput

[in] One of the following values from a DECKLINK_VIDEOOUTPUT enumeration.

Value | Description
DECKLINK_VIDEOOUTPUT_COMPONENT | The analogue video output is component video.
DECKLINK_VIDEOOUTPUT_COMPOSITE | The analogue video output is composite video.
DECKLINK_VIDEOOUTPUT_SVIDEO | The analogue video output is S-video.

setupIs75

[in] A boolean value, TRUE for 7.5 IRE or FALSE for 0.0 IRE.

componentLevelsSMPTE

[in] A boolean value, TRUE for SMPTE component levels or FALSE for Betacam component levels.

Return Values

Value | Description
S_OK | Success.
E_FAIL | Failure.
E_INVALIDARG | Argument is out of range, re. DECKLINK_VIDEOOUTPUT enumeration.
Remarks

The second parameter is only applicable to NTSC video and sets the black level to 7.5 IRE which is used in the USA or 0.0 IRE which is used in Japan.

The third parameter is only applicable to the analogue component video levels and sets the levels of the colour difference channels in accordance to the SMPTE standard or boosts them by a factor of 4/3 for the Betacam format.

See Also

IDecklinkIOControl Interface, GetIOFeatures, SetAnalogueOutput, SetVideoInput, SetDualLinkOutput, SetSingleFieldOutputForSynchronousFrames, SetHDTVPulldownOnOutput, SetBlackToDeckInCapture, SetAFrameReference, SetCaptureVANCLines, SetVideoOutputDownconversionMode, SetAudioInputSource, SetGenlockTiming, SetVideoOutputDownconversionMode2, SetCaptureTimecodeSource, SetVideoInput2


IDecklinkMediaSample Interface

The IDecklinkMediaSample interface provides methods to access ancillary data buffers attached to a media sample generated by the DeckLink video capture filter. The interface will be of interest to those who are aiming to achieve frame accurate capture.

The media samples from the DeckLink Video Capture filter implement this interface.

In addition to the methods inherited from IUnknown, the IDecklinkMediaSample interface exposes the following methods.

Method | Description
GetVANCBuffer | Provides a pointer to the VANC data buffer.


IDecklinkMediaSample::GetVANCBuffer

The GetVANCBuffer method can be used to access the VANC data of the video frame that the media sample represents.

Syntax

HRESULT GetVANCBuffer(
    byte** ppBuffer
);

Parameters

ppBuffer

[in] A pointer to a pointer that receives the address of the VANC data buffer.

Return Values

Value | Description
S_OK | Success.
E_POINTER | NULL pointer argument.
Remarks

This method provides access to the VANC data of of the video frame that the media sample represents. By decoding the timecode data, if present in VANC, it is possible to achieve frame accurate capture. No buffer size is provided as it is assumed that knowledge of the video frame that the media sample represents will yield the size of the VANC buffer. For completeness the number of VANC lines are as follows: NTSC, 39; PAL, 49; HD720, 30; HD1080, 45.

See Also

IDecklinkMediaSampleInterface


DeckLink DirectShow Samples

The DirectShow SDK samples provide a good overview of DirectShow and since there are DirectShow filters for DeckLink cards, you will be able to use DeckLink with many of the DirectShow samples. The DeckLink DirectShow SDK provides developers with a means to access all of the capabilities of DeckLink cards which is not available through DirectShow, for example: Keying.

Currently, sample code is only available in C++, but the concepts demonstrated are equally applicable to other languages.

The DeckLink DirectShow samples are:

  • Simple DeckLink Capture
  • Simple DeckLink Export to Tape
  • DeckLink Filter samples
  • DeckLink Render from External Application
  • DeckLink Histogram sample
  • Frame accurate capture
  • Using Internal Alpha Keying Facility
  • Simple DeckLink Playback

Before building any of these samples, you must:

  • Download the DirectX SDK from http://msdn.microsoft.com/directx/ and install it.
  • Download the Platform SDK from http://msdn.microsoft.com/ and install it. This contains the DirectShow SDK.
  • Download the Windows Media Format 9.5 SDK from http://msdn.microsoft.com/windowsmedia and install it. This is required for capturing and encoding using the Windows Media encoder.
  • C++ include and library paths - For your development environment specify the locations of the installed DirectX include and library paths and the installed Windows Media Format SDK include and library paths. This is much simpler than specifying these directories for every sample project and avoids using environment macros. For example, in Microsoft Visual Studio .NET 2002/2003 select Options from the Tools menu. Select VC++ Directories from the Projects option. Specify the include and library paths for all the SDKs in the Include files and Library files selections of the Show directories for: combo box. E.g.


DeckLink Capture Sample

DeckLink DirectShow Documentation

DeckLink Capture Sample

Description

DecklinkCapture is a simple dialog based Microsoft Windows video capture and preview application. It can capture to a file either uncompressed, DV, Window Media encoded video. The encoding options will only be available if the encoders are present on the host computer.

Development Notes

The sample demonstrates how to programmatically build an optimum capture graph for video preview and video capture using a DeckLink card. The input video and audio formats of the DeckLink card can be programmatically changed using the IAMStreamConfig interface.

Capture graph construction is simpler using the ICaptureGraphBuilder interface, however it was found the this does not build an optimum graph and so was not used. For examples of this interface please refer to the DirectShow SDK samples.

The filters common to all graphs (preview, uncompressed and encoded capture) are added to the graph when the application starts and removed when the application exits. These are the two DeckLink capture filters and the video screen renderer. When the video and audio capture formats or encoding options are changed all intermediate filters are removed before the new graph is reconstructed. When the graph is put into capture mode appropriate file writing filters are tacked onto the preview graph. This is done so there is minimum latency between previewing and capturing. It is quite possible to use the IAMStreamControl interface but this is beyond the scope of this sample.

For DV encoding of PAL video a custom filter, DeckLink Field Swap, has been written to field swap the video frames before they are encoded. This is because PAL DV has the opposite field order to PAL SD and DeckLink cards only capture PAL SD. The down side of the field swap is that one line of active video is lost in the process. NTSC DV is unaffected as it has the same field order as NTSC SD. This sample uses the Microsoft DV Video Encoder Filter which can only encode SD video. For HDV encoding a third party codec is required.

For Windows Media encoding the Windows Media SDK is also required in order to fully customise the encoder. This sample only modifies the size of the compressed video of a system profile. This is for demonstration only as many systems may be unable to encode the full frame size in real time. For better encoding performance create and customise your own profiles.

For all encoding the default encoding profile is used as it is not the purpose of this sample to demonstrate encoding. It is left to the reader to fully explore the configuration of the chosen encoder.


DeckLink Export to Tape Sample

DeckLink DirectShow Documentation

DeckLink Export to Tape Sample

Description

DecklinkExportToTape is a simple dialog based Microsoft Windows video export application. It can be used to frame accurately export to tape or, in the absence of a tape deck, as a simple play list application. A variety of video file formats can be supported, for example AVI, MOV and WMV.

Development Notes

The sample demonstrates how to programmatically export video clips to tape, frame accurately using the IAMExtTransport interface. If no deck is present then the sample becomes a very simple play list application.

When the application starts a project video format is specified so that clips added to the play list can be verified. A very basic playback graph constructed using the selected external renderer device so that timecode can be interpreted correctly while using the deck controls.

A customised report style CListCtrl object simplifies the insertion, positioning and removal of clips from this object, while a generic CClip class is used to store details of every clip in the play list.

The IMediaDet interface is used prior to inserting a clip into the play list to extract clip frame rate and clip duration parameters which are used in conjunction with the in and out points of a clip when exporting to tape.

When exporting to tape, the deck is set to insert edit mode. This means the deck controls the points at which the video and audio tracks will be recorded whilst preserving the control track. All the application has to do is output the video at the correct time. Setting up the insert edit is greatly simplified by the DeckLink DirectShow filters . These filters support the IAMExtTransport::GetEditPropertySet, IAMExtTransport::SetEditPropertySet, IAMExtTransport::GetEditProperty and IAMExtTransport::SetEditProperty methods. A few optimisations have been made in order to start the graph as quickly as possible: pausing the graph to get the streams to allocate their resources in advance of streaming and using the IMediaSeeking interface to force the file source filter to cache some frames off disk.

For each clip in the play list, a simple file playback graph is constructed. If there is a deck present then an insert edit mode is setup and the application waits for the inpoint before starting the graph. Otherwise if no deck is present the graph is started immediately. While exporting to tape the application waits for the outpoint, or during playback it waits for the EC_COMPLETE notification from the graph, before proceeding with the next clip.


DeckLink Filter Samples

DeckLink DirectShow Documentation

DeckLink Filter Samples

Description

There are a few sample filters that have been written to support the other DeckLink DirectShow samples.

Development Notes

The DeckLink Field Swap filter has been written to support the DeckLink Capture sample application and is based upon the DirectShow SDK Trans-in-Place filter. When encoding the PAL SD output from the DeckLink capture filter to PAL DV the field order must be swapped in order to correctly preserve motion. The draw back of the field swap is the loss of one active line of video.

The Deckink Frame Source filter is the key filter in the DeckLink Frame Source sample. It is based upon the DirectShow SDK PushSource sample and provides a custom interface to an external application. This interface is used to deliver frames of video from the external application into a DirectShow filter graph so that they can be rendered by a DirectShow renderer filter.

The DeckLink Still Source filter is used in the DeckLink Keyer sample and is also based upon the DirectShow SDK PushSource sample. One of the drawbacks of using the DirectShow Editing Services still source filter is that they do not specify a frame rate. This is problematic for the DeckLink video renderer filter as it needs to know the video frame rate at which the hardware is to run. This filter supports the IFileSourceFilter interface which can be called repeatedly, even while this filter is streaming, in order to update and/or change the source bitmap image. As this filter provides a stream of bitmap images it is also possible to provide some customisation to generate specialized bitmaps. By defining special filenames the still source filter can provide test patterns without the need for the data to reside on disk. Having virtual files in this way makes this filter very flexible. Currently only a checker bitmap pattern is generated by using the 'BMD_Checker' filename. This is used by the Decklink Keyer sample.

The DeckLink Composite filter is a simple transform filter which accepts any size input media and composites the frames onto frames whose dimensions are acceptable to the DeckLink video renderer filter. This simple sample was developed to demonstrate one method for rendering popular video formats onto frames with SD or HD-SDI dimensions. This sample could be extended to examine the source and target rectangles of the connection and even implement a resizing algorithm so that the composited source frame will fit exactly within the destination frame.


DeckLink PushSource Sample

DeckLink DirectShow Documentation

DecklinkFrameSource Sample

Description

DecklinkFrameSource is a dialog based Microsoft Windows application delivering video frames into a DirectShow graph.

User's Guide

This sample application draws a frame number into the frame using GDI+ methods then delivers it to the DirectShow graph which contains a DeckLink Video Render Filter. This filter then displays the frame on an external monitor. The app can deliver frames at a variable rate to simulate too few samples (famine) or too many samples (flood).

Development Notes

The purpose of the sample is to demonstrate how to feed video frames from an application, into a DirectShow graph which has the DeckLink video render filter.

There are three main components; the DirectShow graph, the application and the interface between the graph and the application.

A source filter, based on the SDK PushSource sample code, is connected to the DeckLink video render filter and supplies the render filter with video frames.

This source filter has a custom allocator, a slightly modified version of the SDK CBaseAllocator, to provide a pool of samples to the graph from a delivery queue. The streaming thread of the source filter blocks in the custom allocator if there are no samples in the delivery queue. The delivery queue is fed by the application, via a custom interface on the source filter.

The application requests a frame buffer, or many frame buffers, from the source filter. If none are available this call fails. When ready, the application hands the buffer, or buffers, back to the filter through the custom interface.

The source filter attaches this buffer to a free media sample. This sample is then added to the delivery queue. If no free samples are available, this call will block until downstream filters in the graph have returned a sample to the custom allocator.

Support for the IAMStreamConfig interface has been added so that the application can set the connection format of the source filter's output pin before the output pin has been connected. (Dynamic reconnection is possible by adding DynSource etc. but this is out of the scope of this sample.)

The application can request as many buffers as needed but must deliver them in order. The application can deliver a number of buffers before running the graph, in effect, preroll. The application can deliver at a variable rate. If the application delivers at a rate faster than the average time per frame the source filter will eventually block as there will be no free samples (flood). If the application delivers at a rate slower than the average frame rate the streaming thread will eventually block as there will be no items in the delivery queue (famine).

Once the application has retrieved a buffer then it can render the video frame. In this example a simple frame counter of frames rendered is converted into timecode. To demonstrate a basic ticker (scrolling text) the timecode is scrolled across the frame. This is acheived by first testing to see if the video format is interlaced. This is important in order to make the scrolling as smooth as possible. An interlaced frame consists of two images from two different points in time. Half the lines from each image are combined to produce the completed frame. The odd lines and taken from one frame and the even lines from the other in order to have the correct spatial separation. We also have to be careful with the order of the lines since some formats show the even lines first and others show the odd lines first. If the order is wrong the scrolling will not look smooth. A progressive frame consists of one image from one point in time and is therefore easy to render when compared to an interlaced frame. Once the frame is rendered it is delivered to the DirectShow graph for rendering on the DeckLink hardware.


DeckLink Histogram Sample

DeckLink DirectShow Documentation

DeckLink Histogram Sample

Description

DecklinkHistogram is a simple dialog based Microsoft Windows video capture and preview application. It uses the Sample Grabber Filter and the ISampleGrabber interface to extract samples from a capture graph and into an application for in order to perform a histogram analysis on the video frames.

Development Notes

The purpose of this sample is to demonstrate the retrieval of video samples into an application from a very basic video capture graph. The application then performs, by way of example, a histogram analysis of the video which is then plotted in the application window.

When the application starts up a capture graph is constructed which incorporates the sample grabber filter and the default video renderer is used, but is not required, for a video preview.

In the application a picture control is used to preview the incoming video and a few hooks are in place to process any windows messages received by the application dialog in order to update this control.

The sample grabber filter can be configured in a number of ways, the method chosen for this sample was to use the buffering mode of the filter. A separate thread is used to poll the sample grabber filter for media samples, generate the histogram and update the custom histogram control, a modified version of a static control.

The connection media type for the sample grabber must be specified before the filter is connected. This sample has two choices, YUV or RGB. As the DeckLink capture filter only provided YUV frames and conversion is required if the samples received in the sample grabber callback are to be RGB. The histogram control will plot either individual R, G and B histograms or a luminosity histogram depending upon the connection media type.


DeckLink Ingest Sample

DeckLink DirectShow Documentation

DeckLink Ingest Sample

Description

DecklinkIngest is a simple dialog based Microsoft Windows video capture application. It can be used to frame accurately capture video and audio from an external tape deck. A variety of video file formats are supported, for example AVI, DV, MJPEG and sequences of stills; Cineon, DPX, TGA and BMP.

Development Notes

The sample demonstrates how to programmatically frame accurately capture video clips from tape using the IAMExtTransport and IAMStreamControl interfaces and a set of custom filters collectively known as the GMFBridge†.

One of the probems with capturing with DirectShow is that the graph must be stopped in order to finalise the capture file. When capturing clips, either manually or through a batch capture process, this will cause the preview to stop and restart each time the graph is stopped, the file closed and capture restarted into a new file. The GMFBridge from GDCL Ltd. overcomes this problem by making it possible to capture using two graphs. The first graph is used for previewing the capture stream, the second graph is used for writing the capture stream to disk and the GMFBridge is used as the link between them.

When the sample application starts, the source side graph for capture preview is built. This incorporates a bridge sink filter which is used by the GMFBridge to connect to sink side graphs for file writing. The source side graph also includes two sample grabbers. One, in the video preview, is used to implement the stills capture feature of the sample application. When activated this simply writes the current sample to disk as a bitmap image file.

The second sample grabber is required in order to implement frame accurate capture. This reads timecode from HANC (RP188), VITC (SMPTE 12M) or LTC (via the RS422 serial port). As the timecode from HANC or VITC is derived from a video frame, then the sample timestamps of these samples will match the corresponding video frame. It is vital to have the timecode samples synchronised to the video samples since the IAMStreamControl interface can then be used to implement frame accurate control of the video stream.

The source side graph is always running and is only stopped and rebuilt if the capture device or the capture format is changed. The sink side graph is used for writing the video capture stream to disk. This graph also contains the video compressor if compression has been selected. This graph is rebuilt and run for every new file.

The operation for capturing video to a file involves bridging a source side graph to a sink side graph. In this sample the term to describe this is closing the bridge. When the bridge is closed samples can cross from the source side to the sink side. If a compressor is present the video samples are compressed before being written to disk. To stop the sink side graph in order to finalise the file, the bridge is opened. As there is no connection between the two graphs when the bridge is open, the sink side graph can be stopped and rebuilt without affecting the source side graph and the bridge simply discards source side samples.

For the capture now feature of this sample, the bridge is closed when this feature is activated. The preferences are used to specify the file name template and capture location for files captured in this way. Audio and video samples cross the bridge to the sink side graph until the operation is stopped. The bridge is then opened to complete the capture.

Batch capture is performed in the same manner with the addition of monitoring timecode to determine when to start and when to stop the capture.

Support for the IAMStreamControl interface was added to the GMFBridge sink filter to precisely control which frames cross the bridge. Simply closing the bridge is not enough to ensure only the desired frames cross the bridge so IAMStreamControl is the 'boom gate' which provides per frame control. The timecode sample grabber monitors the timecode and the sample timestamps which are then used to determine the streams times of the capture start. Once capture has started then the source side graph is monitored for events using the IMediaEvent interface. The source side, bridge sink filter issues EC_STREAM_CONTROL_STOPPED when the specified number of frames have been captured. This is the signal that capture is complete for the current clip so the bridge is opened, the file finalised and the next clip queued for capture.

A basic interface is available to enter the data required for batch capturing clips from a tape deck. Each clip has a name, inpoint, outpoint and tape name property. The name is used as the capture file name, the inpoint and outpoint used for frame accurate control of the streams and the tape name monitored to prompt the user to switch tapes in the tape deck for differently named tapes.

†Please read the licensing information in the GMFBridge project or visit GDCL at the following URL: www.gdcl.co.uk.


DeckLink Keyer Sample

DeckLink DirectShow Documentation

DeckLink Alpha Keyer Sample

Description

DecklinkKeyer is a simple dialog based Microsoft Windows video keying and preview application. It can blend either still images, BMPs or AVI movies over the input video of DeckLink cards that support keying.

Development Notes

This sample demonstrates how to construct a DirectShow filter graph that permits the keying of a still image or movie with alpha channel information over the video input of a DeckLink card.

The core filters are added to the graph on application start and removed only when the application closes. Any intermediate filters are removed each time the graph is rebuilt. This happens when the source still image or movie is changed.

A preview of the keying is provided on the desktop by using the VMR to mix a checker still source with the actual keying source.

A custom filter has been written that provides a still source at a given frame rate. The reason for this is that the DirectShow Editing Services still source does not provide frame rate information. This is problematic for the DeckLink video renderer filter as it needs to have frame rate information in order to initialise the underlying hardware. Also the custom still source can be repeatedly called to load a new bitmap image, even while streaming, without the need to reconnect the filters. This prevents any disturbance to the video output on the DeckLink card whilst it is keying. This is only possible in this sample with bitmap stills and not AVI movies. TGA or JPG support is also possible but this is outside the scope of this sample.

The IDecklinkKeyer interface is used to determine the keying capabilities of the DeckLink card and the user interface updated to reflect its abilities. It is also used to control the alpha level of the keying.

A number of source with alpha channels have been provided with this sample and are located in the res directory of the sample's project.


DeckLink Playback Sample

DeckLink DirectShow Documentation

DeckLink Playback Sample

Description

DecklinkPlayback is a simple dialog based Microsoft Windows video playback application using Decklink for output. It can play Windows AVIs and Quicktime MOVs.

Development Notes

This sample demonstrates how to programmatically build a DirectShow playback graph using the DeckLink video and audio renderer filters.

The core filters are added to the graph and depending upon the source file, the graph builder inserts the appropriate intermediate filters. These intermediate filters are removed when a new file is selected for playback as the graph is rebuilt.

The source filter has its seeking capabilites tested in order to determine whether seeking and scrubbing is possible during playback. The IMediaSeeking interface is used for this and is also used to provide feedback of the current playback position.

An infinite-Tee filter is used to provide a video stream to the DeckLink video renderer filter and the VMR so that the stream can be preview on the desktop during playback.

The application also registers interest in events from the filter graph manager, in particular the EC_COMPLETE notification which is sent when all streams have completed streaming. This is used to provide simple looped playback by resetting the stream to the beginning.

NOTE: This sample is currently incomplete. It does have some code aimed at providing playback of Windows Media encoded files, WMVs but has not been completed. This sample has not been fully tested so may have bugs or undesirable behaviour. As it stands it is only meant to demonstrate simple file playback using the DeckLink video and audio renderer filters.