You are on page 1of 236

SDK DeckLink Software Developers Kit

Mac OS X Windows Linux


July 2010

TABLE OF CONTENTS
1 Introduction
1.1 1.2 1.3 1.3.1 1.3.2 1.3.3 1.3.4 1.3.5 1.3.5.1 1.3.5.2 1.3.5.3 1.3.5.4 1.4 1.4.1 1.4.1.1 1.4.1.2 1.4.1.3 Welcome Overview API Design Overview Object Model Object Interfaces Reference Counting Interface Stability New Interfaces Updated Interfaces Deprecated Interfaces Removed interfaces Interface Reference IUnknown Interface IUnknown::QueryInterface method IUnknown::AddRef method IUnknown::Release method

10
10 10 11 11 11 11 12 12 12 13 13 13 14 14 15 16 16

DeckLink API
2.1 2.2 2.2.1 2.2.2 2.3 2.3.1 2.3.2 2.4 2.4.1 2.4.1.1 2.4.2 2.4.2.1 2.4.3 Using the DeckLink API in a project Accessing DeckLink devices Windows Mac OS X and Linux High level interface Capture Playback Interface Reference IDeckLinkIterator Interface IDeckLinkIterator::Next method IDeckLink Interface IDeckLink::GetModelName method IDeckLinkOutput Interface

17
17 17 18 18 19 19 20 21 21 22 23 25 26

SDK Software Developers Kit

TABLE OF CONTENTS
2.4.3.1 2.4.3.2 2.4.3.3 2.4.3.4 2.4.3.5 2.4.3.6 2.4.3.7 2.4.3.8 2.4.3.9 2.4.3.10 2.4.3.11 2.4.3.12 2.4.3.13 2.4.3.14 2.4.3.15 2.4.3.16 2.4.3.17 2.4.3.18 2.4.3.19 2.4.3.20 2.4.3.21 2.4.3.22 2.4.3.23 2.4.3.24 2.4.3.25 2.4.3.26 2.4.4 2.4.4.1 2.4.4.2 2.4.4.3 2.4.4.4 2.4.4.5 2.4.4.6 2.4.4.7 2.4.4.8 IDeckLinkOutput::DoesSupportVideoMode method IDeckLinkOutput::IsScheduledPlaybackRunning method IDeckLinkOutput::GetDisplayModeIterator method IDeckLinkOutput::SetScreenPreviewCallback method IDeckLinkOutput::EnableVideoOutput method IDeckLinkOutput::DisableVideoOutput method IDeckLinkOutput::SetVideoOutputFrameMemoryAllocator method IDeckLinkOutput::CreateVideoFrame method IDeckLinkOutput::CreateAncillaryData method IDeckLinkOutput::DisplayVideoFrameSync method IDeckLinkOutput::ScheduleVideoFrame method IDeckLinkOutput::SetScheduledFrameCompletionCallback method IDeckLinkOutput::GetBufferedVideoFrameCount method IDeckLinkOutput::EnableAudioOutput method IDeckLinkOutput::DisableAudioOutput method IDeckLinkOutput::WriteAudioSamplesSync method [currently not supported] IDeckLinkOutput::BeginAudioPreroll method IDeckLinkOutput::EndAudioPreroll method IDeckLinkOutput::ScheduleAudioSamples method IDeckLinkOutput::GetBufferedAudioSampleFrameCount IDeckLinkOutput::FlushBufferedAudioSamples method IDeckLinkOutput::SetAudioCallback method IDeckLinkOutput::StartScheduledPlayback method IDeckLinkOutput::StopScheduledPlayback method IDeckLinkOutput::GetScheduledStreamTime method IDeckLinkOutput::GetHardwareReferenceClock method IDeckLinkInput Interface IDeckLinkInput::DoesSupportVideoMode IDeckLinkInput::GetDisplayModeIterator IDeckLinkInput::SetScreenPreviewCallback method IDeckLinkInput::EnableVideoInput method IDeckLinkInput::GetAvailableVideoFrameCount method IDeckLinkInput::DisableVideoInput method IDeckLinkInput::EnableAudioInput method IDeckLinkInput::DisableAudioInput method 29 30 31 32 33 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 56 56 58 59 60 61 62 63

SDK Software Developers Kit

TABLE OF CONTENTS
2.4.4.9 2.4.4.10 2.4.4.11 2.4.4.12 2.4.4.13 2.4.4.14 2.4.4.15 2.4.5 2.4.5.1 2.4.5.2 2.4.5.3 2.4.5.4 2.4.5.5 2.4.5.6 2.4.5.7 2.4.5.8 2.4.6 2.4.6.1 2.4.6.2 2.4.7 2.4.7.1 2.4.7.2 2.4.7.3 2.4.7.4 2.4.8 2.4.8.1 2.4.9 2.4.9.1 2.4.9.2 2.4.10 2.4.10.1 2.4.10.2 2.4.11 2.4.11.1 2.4.11.2 IDeckLinkInput::GetAvailableAudioSampleFrameCount method IDeckLinkInput::StartStreams method IDeckLinkInput::StopStreams method IDeckLinkInput::FlushStreams method IDeckLinkInput::PauseStreams method IDeckLinkInput::SetCallback method IDeckLinkInput::GetHardwareReferenceClock method IDeckLinkVideoFrame Interface IDeckLinkVideoFrame::GetWidth method IDeckLinkVideoFrame::GetHeight method IDeckLinkVideoFrame::GetRowBytes method IDeckLinkVideoFrame::GetPixelFormat method IDeckLinkVideoFrame::GetFlags method IDeckLinkVideoFrame::GetBytes method IDeckLinkVideoFrame::GetTimecode method IDeckLinkVideoFrame::GetAncillaryData method IDeckLinkVideoOutputCallback Interface IDeckLinkVideoOutputCallback::ScheduledFrameCompleted method IDeckLinkVideoOutputCallback::ScheduledPlaybackHasStopped method IDeckLinkMutableVideoFrame Interface IDeckLinkMutableVideoFrame::SetFlags method IDeckLinkMutableVideoFrame::SetTimecode method IDeckLinkMutableVideoFrame::SetTimecodeFromComponents method IDeckLinkMutableVideoFrame::SetAncillaryData method IDeckLinkAudioOutputCallback Interface IDeckLinkAudioOutputCallback::RenderAudioSamples method IDeckLinkInputCallback Interface IDeckLinkInputCallback::VideoInputFrameArrived method IDeckLinkInputCallback::VideoInputFormatChanged method IDeckLinkVideoInputFrame Interface IDeckLinkVideoInputFrame::GetStreamTime method IDeckLinkVideoInputFrame::GetHardwareReferenceTimestamp method IDeckLinkAudioInputPacket Interface IDeckLinkAudioInputPacket:: GetSampleFrameCount method IDeckLinkAudioInputPacket::GetBytes method 64 65 65 66 67 68 69 70 72 72 73 73 74 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 90 91 92 93 94 95 95

SDK Software Developers Kit

TABLE OF CONTENTS
2.4.11.3 2.4.12 2.4.12.1 2.4.13 2.4.13.1 2.4.13.2 2.4.13.3 2.4.13.4 2.4.13.5 2.4.13.6 2.4.14 2.4.14.1 2.4.14.2 2.4.14.3 2.4.14.4 2.4.14.5 2.4.14.6 2.4.14.7 2.4.14.8 2.4.14.9 2.4.14.10 2.4.14.11 2.4.14.12 2.4.14.13 2.4.14.14 2.4.14.15 2.4.14.16 2.4.14.17 2.4.14.18 2.4.14.19 2.4.14.20 2.4.14.21 2.4.14.22 2.4.14.23 2.4.14.24 IDeckLinkAudioInputPacket::GetPacketTime method IDeckLinkDisplayModeIterator Interface IDeckLinkDisplayModeIterator::Next method IDeckLinkDisplayMode Interface IDeckLinkDisplayMode::GetWidth method IDeckLinkDisplayMode::GetHeight method IDeckLinkDisplayMode::GetName method IDeckLinkDisplayMode::GetDisplayMode method IDeckLinkDisplayMode::GetFrameRate method IDeckLinkDisplayMode::GetFieldDominance method IDeckLinkConfiguration Interface IDeckLinkConfiguration::GetConfigurationValidator method IDeckLinkConfiguration::WriteConfigurationToPreferences method IDeckLinkConfiguration::SetVideoOutputFormat method IDeckLinkConfiguration::IsVideoOutputActive method IDeckLinkConfiguration::Set444And3GBpsVideoOutput method IDeckLinkConfiguration::Get444And3GBpsVideoOutput method IDeckLinkConfiguration::SetAnalogVideoOutputFlags method IDeckLinkConfiguration::GetAnalogVideoOutputFlags method IDeckLinkConfiguration::EnableFieldFlickerRemovalWhenPaused method IDeckLinkConfiguration::IsEnabledFieldFlickerRemovalWhenPaused method IDeckLinkConfiguration::SetVideoOutputConversionMode method IDeckLinkConfiguration::GetVideoOutputConversionMode method IDeckLinkConfiguration::Set_HD1080p24_to_HD1080i5994_Conversion method IDeckLinkConfiguration::Get_HD1080p24_to_HD1080i5994_Conversion method IDeckLinkConfiguration::SetVideoInputFormat method IDeckLinkConfiguration::GetVideoInputFormat method IDeckLinkConfiguration::SetAnalogVideoInputFlags method IDeckLinkConfiguration::GetAnalogVideoInputFlags method IDeckLinkConfiguration::SetVideoInputConversionMode method IDeckLinkConfiguration::GetVideoInputConversionMode method IDeckLinkConfiguration::SetBlackVideoOutputDuringCapture method IDeckLinkConfiguration::GetBlackVideoOutputDuringCapture method IDeckLinkConfiguration::Set32PulldownSequenceInitialTimecodeFrame method IDeckLinkConfiguration::Get32PulldownSequenceInitialTimecodeFrame method 96 97 98 99 100 100 101 101 102 103 104 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130

SDK Software Developers Kit

TABLE OF CONTENTS
2.4.14.25 2.4.14.26 2.4.14.27 2.4.14.28 2.4.15 2.4.15.1 2.4.15.2 2.4.15.3 2.4.15.4 2.4.16 2.4.16.1 2.4.16.2 2.4.16.3 2.4.16.4 2.4.17 2.4.17.1 2.4.17.2 2.4.17.3 2.4.17.4 2.4.18 2.4.18.1 2.4.18.2 2.4.18.3 2.4.18.4 2.4.18.5 2.4.19 2.4.19.1 2.4.19.2 2.4.19.3 2.4.20 2.4.20.1 2.4.20.2 2.4.20.3 2.4.20.4 2.4.21 IDeckLinkConfiguration::SetVancSourceLineMapping method IDeckLinkConfiguration::GetVancSourceLineMapping method IDeckLinkConfiguration::SetAudioInputFormat method IDeckLinkConfiguration::GetAudioInputFormat method IDeckLinkAPIInformation Interface IDeckLinkAPIInformation::GetFlag method IDeckLinkAPIInformation::GetInt method IDeckLinkAPIInformation::GetFloat method IDeckLinkAPIInformation::GetString method IDeckLinkAttributes Interface IDeckLinkAttributes::GetFlag method IDeckLinkAttributes::GetInt method IDeckLinkAttributes::GetFloat method IDeckLinkAttributes::GetString method IDeckLinkMemoryAllocator Interface IDeckLinkMemoryAllocator::AllocateBuffer method IDeckLinkMemoryAllocator::ReleaseBuffer method IDeckLinkMemoryAllocator::Commit method IDeckLinkMemoryAllocator::Decommit method IDeckLinkKeyer Interface IDeckLinkKeyer::Enable method IDeckLinkKeyer::SetLevel method IDeckLinkKeyer::RampUp method IDeckLinkKeyer::RampDown method IDeckLinkKeyer::Disable method IDeckLinkVideoFrameAncillary Interface IDeckLinkVideoFrameAncillary GetPixelFormat method IDeckLinkVideoFrameAncillary GetDisplayMode method IDeckLinkVideoFrameAncillary GetBufferForVerticalBlankingLine method IDeckLinkTimecode Interface IDeckLinkTimecode::GetBCD method IDeckLinkTimecode::GetComponents method IDeckLinkTimecode::GetString method IDeckLinkTimecode::GetFlags method IDeckLinkScreenPreviewCallback Interface 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 157 158 159 160 161 162 162 163

SDK Software Developers Kit

TABLE OF CONTENTS
2.4.21.1 2.4.22 2.4.22.1 2.4.22.2 2.4.22.3 2.4.23 2.4.24 2.4.24.1 2.4.25 2.4.25.1 2.4.25.2 2.4.25.3 2.4.25.4 2.4.25.5 2.4.25.6 2.4.25.7 2.4.25.8 2.4.25.9 2.4.25.10 2.4.25.11 2.4.25.12 2.4.25.13 2.4.25.14 2.4.25.15 2.4.25.16 2.4.25.17 2.4.25.18 2.4.25.19 2.4.25.20 2.4.25.21 2.4.25.22 2.4.25.23 2.4.25.24 2.4.25.25 2.4.25.26 IDeckLinkScreenPreviewCallback::DrawFrame method IDeckLinkGLScreenPreviewHelper Interface IDeckLinkGLScreenPreviewHelper::InitializeGL method IDeckLinkGLScreenPreviewHelper::PaintGL method IDeckLinkGLScreenPreviewHelper::SetFrame method IDeckLinkCocoaScreenPreviewCallback Interface IDeckLinkVideoConversion Interface IDeckLinkVideoConversion::ConvertFrame method IDeckLinkDeckControl Interface IDeckLinkDeckControl::Open method IDeckLinkDeckControl::Close method IDeckLinkDeckControl::GetCurrentState method IDeckLinkDeckControl::SetStandby method IDeckLinkDeckControl::Play method IDeckLinkDeckControl::Stop method IDeckLinkDeckControl::TogglePlayStop method IDeckLinkDeckControl::Eject method IDeckLinkDeckControl::GoToTimecode method IDeckLinkDeckControl::FastForward method IDeckLinkDeckControl::Rewind method IDeckLinkDeckControl::StepForward method IDeckLinkDeckControl::StepBack method IDeckLinkDeckControl::Jog method IDeckLinkDeckControl::Shuttle method IDeckLinkDeckControl::GetTimecodeString method IDeckLinkDeckControl::GetTimecode method IDeckLinkDeckControl::GetTimecodeBCD method IDeckLinkDeckControl::SetPreroll method IDeckLinkDeckControl::GetPreroll method IDeckLinkDeckControl::SetCaptureOffset method IDeckLinkDeckControl::GetCaptureOffset method IDeckLinkDeckControl::SetExportOffset method IDeckLinkDeckControl::GetExportOffset method IDeckLinkDeckControl::GetManualExportOffset method IDeckLinkDeckControl::StartExport method 164 165 167 167 168 169 170 170 172 175 176 177 177 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200

SDK Software Developers Kit

TABLE OF CONTENTS
2.4.25.27 2.4.25.28 2.4.25.29 2.4.25.30 2.4.25.31 2.4.25.32 2.4.26 2.4.26.1 2.4.26.2 2.4.26.3 2.4.26.4 2.5 2.5.1 2.5.2 2.5.3 2.5.4 2.5.5 2.5.6 2.5.7 2.5.8 2.5.9 2.5.10 2.5.11 2.5.12 2.5.13 2.5.14 2.5.15 2.5.16 2.5.17 2.5.18 2.5.19 2.5.20 2.5.21 2.5.22 2.5.23 IDeckLinkDeckControl::StartCapture method IDeckLinkDeckControl::GetDeviceID method IDeckLinkDeckControl::Abort method IDeckLinkDeckControl::CrashRecordStart method IDeckLinkDeckControl::CrashRecordStop method IDeckLinkDeckControl::SetCallback method IDeckLinkDeckControlStatusCallback Interface IDeckLinkDeckControlStatusCallback::TimecodeUpdate method IDeckLinkDeckControlStatusCallback::VTRControlStateChanged method IDeckLinkDeckControlStatusCallback::DeckControlEventReceived method IDeckLinkDeckControlStatusCallback::DeckControlStatusChanged method Common Data Types Basic Types Time Representation Display Modes Pixel Formats Field Dominance Frame Flags Input Video Mode Flags Video Output Flags Output Frame Completion Results Flags Video Connection Modes Audio Sample Rates Audio Sample Types DeckLink Information ID DeckLink Attribute ID Audio Output Stream Type Analog Video Flags Audio Connection Modes Output Conversion Modes Input Conversion Modes Video Input Format Changed Events Display Mode Support BMDTimecodeFormat BMDTimecodeFlags 202 204 205 206 207 208 209 210 211 212 213 214 214 214 215 217 221 222 222 222 223 224 224 224 225 226 226 227 227 228 229 229 229 230 230

SDK Software Developers Kit

TABLE OF CONTENTS
2.5.24 2.4.25 2.4.26 2.4.27 2.4.28 2.4.29 2.4.30 BMDTimecodeBCD Deck Control Mode Deck Control Event Deck Control VTR Control States Deck Control Status Flags Deck Control Export Mode Ops Flags Deck Control error 231 232 232 233 233 234 235

SDK Software Developers Kit

SECTION

INTRODUCTION
1.1 Welcome
Thanks for downloading the Blackmagic Design DeckLink Software Developers Kit.

1.2 Overview
The DeckLink SDK provides a stable, cross- platform interface to a Blackmagic Design DeckLink product line. The SDK provides both low-level control of hardware and high-level interfaces to allow developers to easily perform common tasks. The SDK consists of a set of interface descriptions & sample applications which demonstrate the use of the basic features of the hardware. The details of the SDK are described in this document. The SDK supports Microsoft Windows XP, Vista, Mac OS X and Linux platforms. You can download the SDK from www.blackmagic-design.com/support

SDK Software Developers Kit

10

SECTION

API DESIGN
The libraries supporting the Blackmagic SDK are shipped as part of the product installers for each supported product line. Applications built against the interfaces shipped in the SDK will dynamically link against the library installed on the end-users system.

1.3.1 Overview

1.3.2 Object Model


The SDK interface is modeled on Microsofts Component Object Model (COM). On Microsoft Windows platforms, it is provided as a native COM interface registered with the operating system. On other platforms application code is provided to allow the same COM style interface to be used. The COM model provides a paradigm for creating flexible and extensible interfaces without imposing much overhead or baggage.

1.3.3 Object Interfaces


The DeckLink API provides programmatic access to all current Blackmagic Design DeckLink, Multibridge and Intensity products. DeckLink is used as a generic term to refer to all supported products and models except where noted. The API provides high-level interfaces to allow capture & playback of audio and video with frame buffering and scheduling as well as low-level interfaces for controlling features available on different capture card models. Functionality within the API is accessed via object interfaces. Each object in the system may inherit from and be accessed via a number of object interfaces. Typically the developer is able to interact with object interfaces and leave the underlying objects to manage themselves.

SDK Software Developers Kit

11

SECTION

API DESIGN
Each object interface class has a Globally Unique ID (GUID) called an Interface ID. On platforms with native COM support, an IID may be used to obtain a handle to an exported interface object from the OS, which is effectively an entry point to an installed API. Each interface may have related interfaces that are accessed by providing an IID to an existing object interface (see IUnknown::QueryInterface). This mechanism allows new interfaces to be added to the API without breaking API or ABI compatibility.

1.3.4 Reference Counting


The API uses reference counting to manage the life cycle of object interfaces. The developer may need to add or remove references on object interfaces (see IUnknown::AddRef and IUnknown::Release) to influence their life cycle as appropriate in the application.

1.3.5 Interface Stability


The SDK provides a set of stable interfaces for accessing Blackmagic Design hardware. Whilst the published interfaces will remain stable, developers need to be aware of some issues they may encounter as new products, features and interfaces become available.

1.3.5.1 New Interfaces


Major pieces of new functionality may be added to the SDK as a whole new object interface. Already released applications will not be affected by the additional functionality. Developers making use of the new functionality should be sure to check the return of CoCreateInstance and/or QueryInterface as these interfaces will not be available on users systems which are running an older release of the Blackmagic drivers. Developers can choose to either reduce the functionality of their application when an interface is not available, or to notify the user that they must install a later version of the Blackmagic drivers.

SDK Software Developers Kit

12

SECTION

API DESIGN
As new functionality is added to the SDK, some existing interfaces may need to be modified or extended. To maintain compatibility with released software, the original interface will be deprecated but will remain available and maintain its unique identifier (IID). The replacement interface will have a new identifier and remain as similar to the original as possible.

1.3.5.2 Updated Interfaces

1.3.5.3 Deprecated Interfaces


Interfaces which have been replaced with an updated version, or are no longer recommended for use are deprecated. Deprecated interfaces are moved out of the main interface description files into an interface description file named according to the release in which the interface was deprecated. Deprecated interfaces are also renamed with a suffix indicating the release prior to the one in which they were deprecated. It is recommended that developers update their applications to use the most recent SDK interfaces when they release a new version of their applications. As an interim measure, developers may include the deprecated interface descriptions, and updating the names of the interfaces in their application to access the original interface functionality.

1.3.5.4 Removed interfaces


Interfaces that have been deprecated for some time may eventually be removed in a major driver update if they become impractical to support.

SDK Software Developers Kit

13

SECTION

API DESIGN
1.4 Interface Reference
Every object interface subclasses the IUnknown interface.

1.4.1 IUnknown Interface


Each API interface is a subclass of the standard COM base class IUnknown. The IUnknown object interface provides reference counting and the ability to look up related interfaces by interface ID. The interface ID mechanism allows interfaces to be added to the API without impacting existing applications. Public Member Functions Method QueryInterface AddRef Release Description Provides access to supported child interfaces of the object. Increments the reference count of the object. Decrements the reference count of the object. When the final reference is removed, the object is freed.

SDK Software Developers Kit

14

SECTION

API DESIGN
The QueryInterface method looks up a related interface of an object interface. Syntax HRESULT Parameters Name id outputInterface Return Values Value E_NOINTERFACE S_OK Description Interface was not found Success Direction Description in out Interface ID of interface to lookup New object interface or NULL on failure.

1.4.1.1 IUnknown::QueryInterface method

QueryInterface(REFIID id, void **outputInterface);

SDK Software Developers Kit

15

SECTION

API DESIGN
The AddRef method increments the reference count for an object interface. Syntax ULONG Parameters none. Return Values Value Count Description New reference count for debug purposes only.

1.4.1.2 IUnknown::AddRef method

AddRef();

1.4.1.3 IUnknown::Release method


The Release method decrements the reference count for an object interface. When the last reference is removed from an object, the object will be destroyed. Syntax ULONG Parameters none. Return Values Value Count Description New reference count for debug purposes only.

Release();

SDK Software Developers Kit

16

SECTION

DeckLink API
2.1 Using the DeckLink API in a project
The supplied sample applications provide examples of how to include the DeckLink API in a project on each supported platform. To use the DeckLink API in your project, one or more files need to be included: Windows Mac OS X Linux DeckLink X.Y\Win\Include\DeckLinkAPI.idl DeckLink X.Y/Mac/Include/DeckLinkAPI.h DeckLink X.Y/Mac/Include/DeckLinkAPIDispatch.cpp DeckLink X.Y/Linux/DeckLinkAPI.h DeckLink X.Y/Linux/DeckLinkAPIDispatch.cpp

2.2 Accessing DeckLink devices


Most DeckLink API object interfaces are accessed via the IDeckLinkIterator object. How a reference to an IDeckLinkIterator is obtained varies between platforms depending on their level of support for COM:

SDK Software Developers Kit

17

SECTION

DeckLink API
The main entry point to the DeckLink API is the IDeckLinkIterator interface. This interface should be obtained from COM using CoCreateInstance: IDeckLinkIterator *deckLinkIterator = NULL; CoCreateInstance(CLSID_CDeckLinkIterator, NULL, CLSCTX_ALL, IID_IDeckLinkIterator, (void**)&deckLinkIterator); On success, CoCreateInstance returns an HRESULT of S_OK and deckLinkIterator points to a new IDeckLinkIterator object interface.

2.2.1 Windows

2.2.2 Mac OS X and Linux


On platforms without native COM support, a C entry point is provided to access an IDeckLinkIterator object: IDeckLinkIterator *deckLinkIterator = CreateDeckLinkIteratorInstance(); On success, deckLinkIterator will point to a new IDeckLinkIterator object interface otherwise it will be set to NULL.

SDK Software Developers Kit

18

SECTION

DeckLink API
2.3 High level interface
The DeckLink API provides a framework for video & audio streaming which greatly simplifies the task of capturing or playing out video and audio streams. This section provides an overview of how to use these interfaces.

2.3.1 Capture
An application performing a standard streaming capture operation should perform the following steps: IDeckLinkInput::EnableVideoInput (display mode, pixel format, flags) IDeckLinkInput::EnableAudioInput (sample rate, sample type, channel count) IDeckLinkInput::SetCallback (input callback) IDeckLinkInput::StartStreams() While streams are running: - receive calls to IDeckLinkInputCallback::VideoInputFrameArrived with video frame and corresponding audio packet IDeckLinkInput::StopStreams() Audio may be pulled from a separate thread if desired. If audio is not required, the call to EnableAudioInput may be omitted and the VideoInputFrameArrived callback will receive NULL audio packets.

SDK Software Developers Kit

19

SECTION

DeckLink API
An application performing a standard streaming playback operation should perform the following steps: IDeckLinkOutput::EnableVideoOutput (display mode, pixel format, flags) IDeckLinkOutput::EnableAudioOutput (sample rate, sample type, channel count) IDeckLinkOutput::SetScheduledFrameCompletionCallback (video callback) IDeckLinkOutput::SetAudioCallback (audio output callback) IDeckLinkOutput::BeginAudioPreroll() While more frames or audio need to be pre-rolled: - IDeckLinkOutput::ScheduleVideoFrame() - Return audio data from IDeckLinkAudioOutputCallback::RenderAudioSamples - When audio preroll is complete, call IDeckLinkOutput::EndAudioPreroll() IDeckLinkOutput::StartScheduledPlayback (start time, time scale, playback speed) While playback is running: - Schedule more video frames from IDeckLinkVideoOutputCallback::ScheduledFrameCompleted - Schedule more audio from IDeckLinkAudioOutputCallback::RenderAudioSamples If audio is not required, the call to EnableAudioOutput, SetAudioCallback and BeginAudioPreroll may be omitted. If pre-roll is not required initial ScheduleVideoFrame calls and the call to BeginAudioPreroll and EndAudio may be omitted

2.3.2 Playback

SDK Software Developers Kit

20

SECTION

DeckLink API

2.4 Interface Reference 2.4.1 IDeckLinkIterator Interface


The IDeckLinkIterator interface is used to enumerate the available DeckLink devices. A reference to an IDeckLinkIterator object interface may be obtained from CoCreateInstance on platforms with native COM support or from CreateDeckLinkIteratorInstance on other platforms. The IDeckLink interface(s) returned may be used to access the related interfaces which provide access to the core API functionality. Related Interfaces Interface IDeckLink Interface ID IID_IDeckLink Description IDeckLinkIterator::Next returns IDeckLink interfaces representing each attached DeckLink device.

Public Member Functions Method Next Description Returns a an IDeckLink object interface corresponding to an individual DeckLink device.

SDK Software Developers Kit

21

SECTION

DeckLink API
The Next method creates an object representing a physical DeckLink device and assigns the address of the IDeckLink interface of the newly created object to the decklinkInstance parameter. Syntax HRESULT Parameters Name decklinkInstance Return Values Value S_FALSE E_FAIL S_OK Description No (more) devices found Failure Success Direction Description out Next IDeckLink object interface

2.4.1.1 IDeckLinkIterator::Next method

Next (IDeckLink **decklinkInstance);

SDK Software Developers Kit

22

SECTION

DeckLink API
The IDeckLink object interface represents a physical DeckLink device attached to the host computer. IDeckLink object interfaces are obtained from IDeckLinkIterator. IDeckLink may be queried to obtain the related IDeckLinkOutput, IDeckLinkInput and IDeckLinkConfiguration interfaces. Related Interfaces Interface IDeckLinkIterator Interface ID IID_IDeckLinkIterator Description IDeckLinkIterator::Next returns IDeckLink interfaces representing each attached DeckLink device. An IDeckLinkOutput object interface may be obtained from IDeckLink using QueryInterface An IDeckLinkInput object interface may be obtained from IDeckLink using QueryInterface

2.4.2 IDeckLink Interface

IDeckLinkOutput

IID_IDeckLinkOutput

IDeckLinkInput

IID_IDeckLinkInput

IDeckLink Configuration IDeckLink Attributes IDeckLinkKeyer

IID_IDeckLinkConfiguration An IDeckLinkConfiguration object interface may be obtained from IDeckLink using QueryInterface IID_IDeckLinkAttributes An IDeckLinkAttributes object interface may be obtained from IDeckLink using QueryInterface. An IDeckLinkKeyer object interface may be obtained from IDeckLink using QueryInterface.

IID_IDeckLinkKeyer

SDK Software Developers Kit

23

SECTION

DeckLink API
Public Member Functions Method GetModelName Description Method to get DeckLink device model name.

SDK Software Developers Kit

24

SECTION

DeckLink API
The GetModelName method can be used to get DeckLink device model name. Syntax HRESULT Parameters Name modelName Direction Description out Hardware model name. This allocated string must be freed by the caller when no longer required.

2.4.2.1 IDeckLink::GetModelName method

GetModelName (string *modelName);

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

25

SECTION

DeckLink API
The IDeckLinkOutput object interface allows an application to output a video and audio stream from a DeckLink device. An IDeckLinkOutput interface can be obtained from an IDeckLink object interface using QueryInterface. Related Interfaces Interface IDeckLinkOutput IDeckLinkDisplayModeIterator IDeckLinkVideoFrame IDeckLinkVideoOutputCallback Interface ID IID_IDeckLinkOutput IID_IDeckLinkDisplayModeIterator IID_DeckLinkVideoFrame IID_DeckLinkVideoOutputCallback Description An IDeckLinkOutput object interface may be obtained from IDeckLink using QueryInterface IDeckLinkOutput::GetDisplayModeIterator returns an IDeckLinkDisplayModeIterator object interface IDeckLinkOutput::CreateVideoFrame may be used to create a new IDeckLinkVideoFrame object interface An IDeckLinkVideoOutputCallback object interface may be registered with IDeckLinkOutput::SetSchedule dFrameCompletionCallback An IDeckLinkAudioOutputCallback object interface may be registered with IDeckLinkOutput::SetAudioCallback

2.4.3 IDeckLinkOutput interface

IDeckLinkAudioOutputCallback

IID_DeckLinkAudioOutputCallback

SDK Software Developers Kit

26

SECTION

DeckLink API
Public Member Functions Method DoesSupportVideoMode GetDisplayModeIterator SetScreenPreviewCallback EnableVideoOutput DisableVideoOutput SetVideoOutputFrameMemoryAllocator CreateVideoFrame CreateAncillaryData DisplayVideoFrameSync ScheduleVideoFrame SetScheduledFrameCompletionCallback GetBufferedVideoFrameCount EnableAudioOutput DisableAudioOutput Description Check whether a given video mode is supported for output Get an iterator to enumerate the available output display modes Register screen preview callback Enable video output Disable video output Register custom memory allocator Create a video frame Create ancillary buffer Display a video frame synchronously Schedule a video frame for display Register completed frame callback Gets number of frames queued. Enable audio output Disable audio output

SDK Software Developers Kit

27

SECTION

DeckLink API
Public Member Functions Method WriteAudioSamplesSync BeginAudioPreroll EndAudioPreroll ScheduleAudioSamples GetBufferedAudioSampleFrameCount FlushBufferedAudioSamples SetAudioCallback StartScheduledPlayback StopScheduledPlayback IsScheduledPlaybackRunning GetHardwareReferenceClock Description Play audio synchronously Start pre-rolling audio Stop pre-rolling audio Schedule audio samples for play-back Returns the number of audio sample frames currently buffered for output Flush buffered audio Register audio output callback Start scheduled playback Stop scheduled playback Determine if the video output scheduler is running Get scheduling time

SDK Software Developers Kit

28

SECTION

DeckLink API
The DoesSupportVideoMode method indicates whether a given display mode is supported on output. Modes may be supported, unsupported or supported with conversion. Note: If a pixel format is not natively supported in the cards hardware it will be converted by software and bmdDisplayModeNotSupported will be returned. Syntax HRESULT Parameters Name displayMode pixelFormat result Direction Description in in out Display mode to check Pixel format to check (0 for any) Support type

2.4.3.1 IDeckLinkOutput::DoesSupportVideoMode method

DoesSupportVideoMode (BMDDisplayMode displayMode, BMDPixelFormat pixelFormat, BMDDisplayModeSupport *result);

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

29

SECTION

DeckLink API
The IsScheduledPlaybackRunning method is called to determine if the drivers video output scheduler is currently active. Syntax HRESULT Parameters Name active Return Values Value E_INVALIDARG E_FAIL S_OK Description Parameter active status variable is NULL Failure Success Direction Description out Active status of driver video output scheduler

2.4.3.2 IDeckLinkOutput::IsScheduledPlaybackRunning method

IsScheduledPlaybackRunning (boolean *active)

SDK Software Developers Kit

30

SECTION

DeckLink API
The GetDisplayModeIterator method returns an iterator which enumerates the available display modes. Syntax HRESULT Parameters Name iterator Return Values Value E_FAIL S_OK Description Failure Success Direction Description out Display mode iterator

2.4.3.3 IDeckLinkOutput::GetDisplayModeIterator method

GetDisplayModeIterator (IDeckLinkDisplayModeIterator **iterator);

SDK Software Developers Kit

31

SECTION

DeckLink API
The SetScreenPreviewCallback method is called to register an instance of an IDeckLinkScreenPreviewCallback object. The registered object facilitates the updating of an on-screen preview of a video stream being played. Syntax HRESULT Parameters Name previewCallback Return Values Value E_OUTOFMEMORY E_FAIL S_OK Description Unable to create kernel event (Windows only) Failure Success

2.4.3.4 IDeckLinkOutput::SetScreenPreviewCallback method

SetScreenPreviewCallback (IDeckLinkScreenPreviewCallback *previewCallback)

Direction Description in The IDeckLinkScreenPreview object to be registered.

SDK Software Developers Kit

32

SECTION

DeckLink API
The EnableVideoOutput method enables video output. Once video output is enabled, frames may be displayed immediately with DisplayVideoFrameSync or scheduled with ScheduleVideoFrame. Syntax HRESULT Parameters Name displayMode flags Return Values Value E_FAIL S_OK E_ACCESSDENIED E_OUTOFMEMORY Description Failure Success Unable to access the hardware Unable to create a new frame Direction Description in in Display mode for video output Flags to control ancillary data and video output features.

2.4.3.5 IDeckLinkOutput::EnableVideoOutput method

EnableVideoOutput (BMDDisplayMode displayMode, BMDVideoOutputFlags flags);

2.4.3.6 IDeckLinkOutput::DisableVideoOutput method


The DisableVideoOutput method disables video output. Syntax HRESULT Return Values Value E_FAIL S_OK Description Failure Success

DisableVideoOutput (BMDDisplayMode displayMode);

SDK Software Developers Kit

33

SECTION

DeckLink API
The SetVideoOutputFrameMemoryAllocator method sets a custom memory allocator for frame allocations. Use of a custom memory allocator is optional. Syntax HRESULT Parameters Name theAllocator Return Values Value E_FAIL S_OK Description Failure Success Direction Description in Allocator object with an IDeckLinkMemoryAllocator interface

2.4.3.7 IDeckLinkOutput::SetVideoOutputFrameMemoryAllocator method

SetVideoOutputFrameMemoryAllocator (IDeckLinkMemoryAllocator *theAllocator);

SDK Software Developers Kit

34

SECTION

DeckLink API
The CreateVideoFrame method creates a video frame for output (see IDeckLinkMutableVideoFrame for more information). Syntax HRESULT

2.4.3.8 IDeckLinkOutput::CreateVideoFrame method

CreateVideoFrame (long width, long height, long rowBytes, BMDPixelFormat pixelFormat, BMDFrameFlags flags, IDeckLinkMutableVideoFrame **outFrame);

Parameters Name width height rowBytes pixelFormat flags outFrame Return Values Value E_FAIL S_OK Description Failure Success Direction Description in in in in in out frame width in pixels frame height in pixels bytes per row pixel format frame flags newly created video frame

SDK Software Developers Kit

35

SECTION

DeckLink API
The CreateAncillaryData method creates an ancillary buffer that can be attached to an IDeckLinkMutable video frame. Syntax HRESULT Parameters Name displayMode pixelFormat outBuffer Return Values Value E_FAIL S_OK Description Failure Success Direction Description in in out Video mode for ancillary data Pixel format for ancillary data New video frame ancillary buffer

2.4.3.9 IDeckLinkOutput::CreateAncillaryData method

CreateAncillaryData (BMDDisplayMode displayMode, BMDPixelFormat pixelFormat, IDeckLinkVideoFrameAncillary** outBuffer);

SDK Software Developers Kit

36

SECTION

DeckLink API
The DisplayVideoFrameSync method is used to provide a frame to display as the next frame output. It should not be used during scheduled playback. Video output must be enabled with EnableVideoOutput before frames can be displayed. Syntax HRESULT Parameters Name theFrame Direction Description in frame to display after call return, the frame may be released

2.4.3.10 IDeckLinkOutput::DisplayVideoFrameSync method

DisplayVideoFrameSync (IDeckLinkVideoFrame *theFrame);

Return Values Value E_FAIL S_OK E_ACCESSDENIED E_INVALIDARG Description Failure Success The video output is not enabled. The frame attributes are invalid.

SDK Software Developers Kit

37

SECTION

DeckLink API
The ScheduleVideoFrame method is used to schedule a frame for asynchronous playback at a specified time. Video output must be enabled with EnableVideoOutput before frames can be displayed. Frames may be scheduled before calling StartScheduledPlayback to preroll. Once playback is initiated, new frames can be scheduled from IDeckLinkVideoOutputCallback. Syntax HRESULT

2.4.3.11 IDeckLinkOutput::ScheduleVideoFrame method

ScheduleVideoFrame (IDeckLinkVideoFrame *theFrame, BMDTimeValue displayTime, BMDTimeValue displayDuration, BMDTimeScale timeScale); Direction Description in in in in frame to display time at which to display the frame in timeScale units duration for which to display the frame in timeScale units time scale for displayTime and displayDuration

Parameters Name theFrame displayTime displayDuration timeScale Return Values Value E_FAIL S_OK E_ACCESSDENIED E_INVALIDARG E_OUTOFMEMORY Description Failure Success The video output is not enabled. The frame attributes are invalid. Too many frames are already scheduled

SDK Software Developers Kit

38

SECTION

DeckLink API
The SetScheduledFrameCompletionCallback method configures a callback which will be called when each scheduled frame is completed. Syntax HRESULT

2.4.3.12 IDeckLinkOutput::SetScheduledFrameCompletionCallback method

SetScheduledFrameCompletionCallback( IDeckLinkOutputCallback *theCallback);

Parameters Name theCallBack Direction Description in callback object implementing the IDeckLinkOutputCallback object interface

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

39

SECTION

DeckLink API
The GetBufferedVideoFrameCount method gets the number of frames queued. Syntax HRESULT Parameters Name bufferedFrameCount Return Values Value E_FAIL S_OK Description Failure Success Direction Description out The frame count.

2.4.3.13 IDeckLinkOutput::GetBufferedVideoFrameCount method

GetBufferedVideoFrameCount (uint32_t *bufferedFrameCount) ;

SDK Software Developers Kit

40

SECTION

DeckLink API
The EnableAudioOutput method puts the hardware into a specified audio output mode. Once audio output is enabled, sample frames may be output immediately using WriteAudioSamplesSync or as part of scheduled playback using ScheduleAudioSamples. Syntax HRESULT

2.4.3.14 IDeckLinkOutput::EnableAudioOutput method

EnableAudioOutput(BMDAudioSampleRate sampleRate, BMDAudioSampleType sampleType, uint32_t channelCount, BMDAudioOutputStreamType streamType);

Parameters Name sampleRate sampleType channelCount streamType Return Values Value E_FAIL E_INVALIDARG S_OK E_ACCESSDENIED E_OUTOFMEMORY Description Failure Invalid number of channels requested Success Unable to access the hardware or audio output not enabled. Unable to create internal object Direction Description in in in in Sample rate to output Sample type to output Number of audio channels to output only 2, 8 or 16 channel output is supported. Type of audio output stream.

SDK Software Developers Kit

41

SECTION

DeckLink API
The DisableAudioOutput method disables the hardware audio output mode. Syntax HRESULT Parameters none.

2.4.3.15 IDeckLinkOutput::DisableAudioOutput method

DisableAudioOutput ();

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

42

SECTION

DeckLink API
The WriteAudioSamplesSync method is used to play audio sample frames immediately. Audio output must be configured with EnableAudioOutput. WriteAudioSamplesSync should not be called during scheduled playback. Syntax HRESULT

2.4.3.16 IDeckLinkOutput::WriteAudioSamplesSync method [currently not supported]

WriteAudioSamplesSync (void *buffer, uint32_t sampleFrameCount, uint32_t *sampleFramesWritten);

Parameters Name buffer Direction Description in Buffer containing audio sample frames. Audio channel samples must be interleaved into a sample frame and sample frames must be contiguous. Number of sample frames available Actual number of sample frames queued

sampleFrameCount sampleFramesWritten

in out

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

43

SECTION

DeckLink API
The BeginAudioPreroll method requests the driver begin polling the registered IDeckLinkAudioOutputCallback::RenderAudioSamples object interface for audio-preroll. Syntax HRESULT Parameters none. Return Values Value E_FAIL S_OK Description Failure Success

2.4.3.17 IDeckLinkOutput::BeginAudioPreroll method

BeginAudioPreroll ();

SDK Software Developers Kit

44

SECTION

DeckLink API
The EndAudioPreroll method requests the driver stop polling the registered IDeckLinkAudioOutputCallback object interface for audio-preroll. Syntax HRESULT Parameters none. Return Values Value E_FAIL S_OK Description Failure Success

2.4.3.18 IDeckLinkOutput::EndAudioPreroll method

EndAudioPreroll ();

SDK Software Developers Kit

45

SECTION

DeckLink API
The ScheduleAudioSamples method is used to provide audio sample frames for scheduled playback. Audio output must be enabled with EnableAudioOutput before frames may be scheduled. Syntax HRESULT

2.4.3.19 IDeckLinkOutput::ScheduleAudioSamples method

ScheduleAudioSamples (void *buffer, uint32_t sampleFrameCount, BMDTimeValue streamTime, BMDTimeScale timeScale, uint32_t *sampleFramesWritten);

Parameters Name buffer Direction Description in Buffer containing audio sample frames. Audio channel samples must be interleaved into a sample frame and sample frames must be contiguous. Number of sample frames available time for audio playback in units of timeScale. To queue samples to play back immediately after currently buffered samples both streamTime and timeScale may be set to zero. Time scale for the audio stream. Actual number of sample frames scheduled

sampleFrameCount streamTime

in in

timeScale sampleFramesWritten Return Values Value E_FAIL S_OK

in out

Description Failure Success

SDK Software Developers Kit

46

SECTION

DeckLink API
The IDeckLinkOutput::GetBufferedAudioSampleFrameCount method returns the number of audio sample frames currently buffered for output. This method may be used to determine how much audio is currently buffered before scheduling more audio with ScheduleAudioSamples. Syntax HRESULT Parameters Name bufferedSampleFrameCount Return Values Value E_FAIL S_OK Description Failure Success Direction Description out Number of audio frames currently buffered.

2.4.3.20 IDeckLinkOutput::GetBufferedAudioSampleFrameCount method

GetBufferedAudioSampleFrameCount (uint32_t *bufferedSampleFrameCount)

SDK Software Developers Kit

47

SECTION

DeckLink API
The FlushBufferedAudioSamples method discards any buffered audio sample frames. FlushBufferedAudioSamples should be called when changing playback direction. Buffered audio is implicitly flushed when stopping audio playback with StopScheduledPlayback or DisableAudioOutput. Syntax HRESULT Parameters none. Return Values Value E_FAIL S_OK Description Failure Success

2.4.3.21 IDeckLinkOutput::FlushBufferedAudioSamples method

FlushBufferedAudioSamples ();

SDK Software Developers Kit

48

SECTION

DeckLink API
The SetAudioCallback method configures a callback which will be called regularly to allow the application to queue audio for scheduled playback. Use of this method is optional audio may alternately be queued from IDeckLinkVideoOutputCallback::ScheduledFrameCompleted. Syntax HRESULT Parameters Name theCallBack Direction Description in callback object implementing the IDeckLinkAudioOutputCallback object interface

2.4.3.22 IDeckLinkOutput::SetAudioCallback method

SetAudioCallback (IDeckLinkAudioOutputCallback *theCallback);

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

49

SECTION

DeckLink API
The StartScheduledPlayback method starts scheduled playback. Frames may be pre-rolled by scheduling them before starting playback. SetScheduledFrameCompletionCallback may be used to register a callback to be called when each frame is completed. Playback starts immediately when StartScheduledPlayback is called but at a specified playback start time. Scheduled frames are output as the playback time reaches the time at which the frames were scheduled. Syntax HRESULT Parameters Name playbackStartTime timeScale playbackSpeed Direction Description in in in Time at which the playback starts in units of timeScale Time scale for playbackStartTime and playbackSpeed. Speed at which to play back : 1.0 is normal playback, -1.0 is reverse playback. Fast or slow forward or reverse playback may also be specified.

2.4.3.23 IDeckLinkOutput::StartScheduledPlayback method

StartScheduledPlayback (BMDTimeValue playbackStartTime, BMDTimeScale timeScale, double playbackSpeed);

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

50

SECTION

DeckLink API
The StopScheduledPlayback method stops scheduled playback immediately or at a specified time. Any frames or audio scheduled after the stop time will be flushed. Syntax HRESULT Parameters Name stopPlaybackAtTime actualStopTime Direction Description in out Playback time at which to stop in units of timeScale. Specify 0 to stop immediately. Playback time at which playback actually stopped in units of timeScale. Specify NULL to stop immediately Time scale for stopPlaybackAtTime and actualStopTime. Specify 0 to stop immediately.

2.4.3.24 IDeckLinkOutput::StopScheduledPlayback method

StopScheduledPlayback (BMDTimeValue stopPlaybackAtTime, BMDTimeValue *actualStopTime, BMDTimeScale timeScale);

timeScale

in

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

51

SECTION

DeckLink API
The GetScheduledStreamTime method returns the elapsed time since scheduled playback began. Syntax HRESULT

2.4.3.25 IDeckLinkOutput::GetScheduledStreamTime method

GetScheduledStreamTime (BMDTimeScale desiredTimeScale, BMDTimeValue *streamTime, double *playbackSpeed);

Parameters Name desiredTimeScale streamTime playbackSpeed Return Values Value E_FAIL S_OK E_ACCESSDENIED Description Failure Success Video output is not enabled Direction Description in out out Time scale for elapsedTimeSinceSchedulerBegan Frame time Scheduled playback speed

SDK Software Developers Kit

52

SECTION

DeckLink API
The GetHardwareReferenceClock method returns a clock that is locked to the rate at which the DeckLink hardware is outputting frames. The absolute values returned by this method are meaningless, however the relative differences between subsequent calls can be used to determine elapsed time. This method can be called while video output is enabled (see IDeckLinkOutput::EnableVideoOutput for details). Syntax HRESULT

2.4.3.26 IDeckLinkOutput::GetHardwareReferenceClock method

GetHardwareReferenceClock (BMDTimeScale desiredTimeScale, BMDTimeValue *hardwareTime, BMDTimeValue *timeInFrame, BMDTimeValue *ticksPerFrame);

Parameters Name desiredTimeScale hardwareTime timeInFrame ticksPerFrame

Direction Description in out out out Desired time scale Hardware reference time (in units of desiredTimeScale) Time in frame (in units of desiredTimeScale) Number of ticks for a frame (in units of desiredTimeScale)

Return Values Value E_FAIL S_OK

Description Failure Success

SDK Software Developers Kit

53

SECTION

DeckLink API
The IDeckLinkInput object interface allows an application to capture a video and audio stream from a DeckLink device. An IDeckLinkInput interface can be obtained from an IDeckLink object interface using QueryInterface. Video capture operates in a push model with each video frame being delivered to an IDeckLinkInputCallback object interface. Audio capture is optional and may be handled either using the same push callback or by pulling audio with the ReadAudioSamples method. Related Interfaces Interface
IDeckLink

2.4.4 IDeckLinkInput interface

Interface ID
IID_IDeckLink

Description An IDeckLinkInput object interface may be obtained from IDeckLink using QueryInterface IDeckLinkInput::GetDisplay ModeIterator returns an IDeckLinkDisplayModeIterator object interface An IDeckLinkInputCallback object interface may be registered with IDeckLinkInput::SetCallback

IDeckLinkDisplay ModeIterator

IID_IDeckLinkDisplay ModeIterator

IDeckLinkInputCallback

IID_DeckLinkInput Callback

SDK Software Developers Kit

54

SECTION

DeckLink API
Public Member Functions Method DoesSupportVideoMode GetDisplayModeIterator SetScreenPreviewCallback EnableVideoInput DisableVideoInput EnableAudioInput DisableAudioInput GetBufferedAudioSampleFrameCount StartStreams StopStreams PauseStreams FlushStreams SetCallback Description Check whether a given video mode is supported for input Get an iterator to enumerate the available input display modes Register screen preview callback Configure video input Disable video input Configure audio input Disable audio input Query audio buffer status for pull model audio. Start synchronized capture Stop synchronized capture Pause synchronized capture Removes any buffered video and audio frames. Register input callback

SDK Software Developers Kit

55

SECTION

DeckLink API
The DoesSupportVideoMode method indicates whether a given display mode is supported on input. Modes may be supported, unsupported or supported with conversion. Syntax HRESULT Parameters Name displayMode pixelFormat result Return Values Value E_FAIL S_OK Description Failure Success

2.4.4.1 IDeckLinkInput::DoesSupportVideoMode method

DoesSupportVideoMode (BMDDisplayMode displayMode, BMDPixelFormat pixelFormat, BMDDisplayModeSupport *result); Direction Description in in in Display mode to check Pixel format to check (0 for any) Support type

SDK Software Developers Kit

56

SECTION

DeckLink API
The GetDisplayModeIterator method returns an iterator which enumerates the available display modes. Syntax HRESULT Parameters Name iterator Return Values Value E_FAIL S_OK Description Failure Success Direction Description out display mode iterator

2.4.4.2 IDeckLinkInput::GetDisplayModeIterator method

GetDisplayModeIterator (IDeckLinkDisplayModeIterator **iterator);

SDK Software Developers Kit

57

SECTION

DeckLink API
The SetScreenPreviewCallback method is called to register an instance of an IDeckLinkScreenPreviewCallback object. The registered object facilitates the updating of an on-screen preview of a video stream being captured. Syntax HRESULT Parameters Name previewCallback Direction Description in The IDeckLinkScreenPreview object to be registered.

2.4.4.3 IDeckLinkInput::SetScreenPreviewCallback method

SetScreenPreviewCallback (IDeckLinkScreenPreviewCallback *previewCallback)

Return Values Value S_OK Description Success

SDK Software Developers Kit

58

SECTION

DeckLink API
The EnableVideoInput method configures video input and puts the hardware into video capture mode. Video input (and optionally audio input) is started by calling StartStreams. Syntax HRESULT

2.4.4.4 IDeckLinkInput::EnableVideoInput method

EnableVideoInput(BMDDisplayMode displayMode, BMDPixelFormat pixelFormat, BMDVideoInputModeFlags flags);

Parameters Name displayMode pixelFormat flags Return Values Value E_FAIL S_OK E_INVALIDARG E_ACCESSDENIED E_OUTOFMEMORY Description Failure Success Is returned on invalid mode or video flags Unable to access the hardware or input stream currently active Unable to create a new frame Direction Description in in in Video mode to capture Pixel format to capture Capture flags

SDK Software Developers Kit

59

SECTION

DeckLink API
The GetAvailableVideoFrameCount method provides the number of available input frames. Syntax HRESULT Parameters Name availableFrameCount Direction Description out Number of available input frames.

2.4.4.5 IDeckLinkInput::GetAvailableVideoFrameCount method

GetAvailableVideoFrameCount (uint32_t *availableFrameCount);

Return Values Value S_OK Description Success

SDK Software Developers Kit

60

SECTION

DeckLink API
The DisableVideoInput method disables the hardware video capture mode. Syntax HRESULT Parameters none. Return Values Value E_FAIL S_OK Description Failure Success

2.4.4.6 IDeckLinkInput::DisableVideoInput method

DisableVideoInput ();

SDK Software Developers Kit

61

SECTION

DeckLink API
The EnableAudioInput method configures audio input and puts the hardware into audio capture mode. Synchronized audio and video input is started by calling StartStreams. Syntax HRESULT

2.4.4.7 IDeckLinkInput::EnableAudioInput method

EnableAudioInput(BMDAudioSampleRate sampleRate, BMDAudioSampleType sampleType, uint32_t channelCount);

Parameters Name sampleRate sampleType channelCount Direction Description in in in Sample rate to capture Sample type to capture Number of audio channels to capture only 2, 8 or 16 channel capture is supported.

Return Values Value E_FAIL E_INVALIDARG S_OK Description Failure Invalid number of channels requested Success

SDK Software Developers Kit

62

SECTION

DeckLink API
The DisableAudioInput method disables the hardware audio capture mode. Syntax HRESULT Parameters none. Return Values Value E_FAIL S_OK Description Failure Success

2.4.4.8 IDeckLinkInput::DisableAudioInput method

DisableAudioInput ();

SDK Software Developers Kit

63

SECTION

DeckLink API
The GetAvailableAudioSampleFrameCount method returns the number of audio sample frames currently buffered. Use of this method is only required when using pull model audio the same audio data is made available to IDeckLinkInputCallback and may be ignored. Syntax HRESULT Parameters Name bufferedFrameCount Direction Description out Number of buffered audio frames currently available to ReadAudioSamples.

2.4.4.9 IDeckLinkInput::GetAvailableAudioSampleFrameCount method

GetAvailableAudioSampleFrameCount (uint32_t *availableSampleFrameCount);

Return Values Value E_FAIL S_OK

Description Failure Success

SDK Software Developers Kit

64

SECTION

DeckLink API
The StartStreams method starts synchronized video and audio capture as configured with EnableVideoInput and optionally EnableAudioInput. Syntax HRESULT Parameters none. Return Values Value E_FAIL S_OK E_ACCESSDENIED E_UNEXPECTED Description Failure Success Input stream is already running. Video and Audio inputs are not enabled.

2.4.4.10 IDeckLinkInput::StartStreams method

StartStreams ();

2.4.4.11 IDeckLinkInput::StopStreams method


The StopStreams method stops synchronized video and audio capture. Syntax HRESULT Parameters none. Return Values Value S_OK E_ACCESSDENIED Description Success Input stream already stopped.

StopStreams ();

SDK Software Developers Kit

65

SECTION

DeckLink API
The FlushStreams method removes any buffered video and audio frames. Syntax HRESULT Parameters none. Return Values Value E_FAIL S_OK Description Failure Success

2.4.4.12 IDeckLinkInput::FlushStreams method

FlushStreams ();

SDK Software Developers Kit

66

SECTION

DeckLink API
The PauseStreams method pauses synchronized video and audio capture. Capture time continues while the streams are paused but no video or audio will be captured. Paused capture may be resumed by calling PauseStreams again. Capture may also be resumed by calling StartStreams but capture time will be reset. Syntax HRESULT Parameters none. Return Values Value E_FAIL S_OK Description Failure Success

2.4.4.13 IDeckLinkInput::PauseStreams method

PauseStreams ();

SDK Software Developers Kit

67

SECTION

DeckLink API
The SetCallback method configures a callback which will be called for each captured frame. Synchronized capture is started with StartStreams, stopped with StopStreams and may be paused with PauseStreams. Syntax HRESULT Parameters Name theCallBack Direction Description in callback object implementing the IDeckLinkInputCallback object interface

2.4.4.14 IDeckLinkInput::SetCallback method

SetCallback (IDeckLinkInputCallback *theCallback);

Return Values Value E_FAIL S_OK

Description Failure Success

SDK Software Developers Kit

68

SECTION

DeckLink API
The GetHardwareReferenceClock method returns a clock that is locked to the system clock. The absolute values returned by this method are meaningless, however the relative differences between subsequent calls can be used to determine elapsed time. This method can be called while video input is enabled (see IDeckLinkInput::EnableVideoInput for details). Syntax HRESULT

2.4.4.15 IDeckLinkInput::GetHardwareReferenceClock method

GetHardwareReferenceClock (BMDTimeScale desiredTimeScale, BMDTimeValue *hardwareTime, BMDTimeValue *timeInFrame, BMDTimeValue *ticksPerFrame);

Parameters Name desiredTimeScale hardwareTime timeInFrame ticksPerFrame

Direction Description in out out out Desired time scale Hardware reference time (in units of desiredTimeScale) Time in frame (in units of desiredTimeScale) Number of ticks for a frame (in units of desiredTimeScale)

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

69

SECTION

DeckLink API
The IDeckLinkVideoFrame object interface represents a video frame. The GetWidth, GetHeight methods may be used to determine the pixel dimensions of the frame buffer. Pixels on a given row are packed according to the pixel format returned by GetPixelFormat - see BMDPixelFormat for details. Note that in some formats (HD720 formats, for example), there is padding between rows - always use GetRowBytes to account for the row length, including padding. Developers may sub-class IDeckLinkVideoFrame to provide an implementation which fits well with their applications structure. Related Interfaces Interface
IDeckLinkMutable IDeckLink VideoInputFrame

2.4.5 IDeckLinkVideoFrame Interface

Interface ID
IID_IDeckLinkMutable IID_IDeckLink VideoInputFrame

Description IDeckLinkMutable subclasses IDeckLinkVideoFrame IDeckLinkVideoInputFrame subclasses IDeckLinkVideoFrame

Public Member Functions Method GetWidth GetHeight GetRowBytes GetPixelFormat Description Get video frame width in pixels Get video frame height in pixels Get bytes per row for video frame Get pixel format for video frame

SDK Software Developers Kit

70

SECTION

DeckLink API
Public Member Functions Method GetFlags GetBytes GetTimecode GetAncillaryData Description Get frame flags Get pointer to frame data Gets timecode information Gets ancillary data

SDK Software Developers Kit

71

SECTION

DeckLink API
The GetWidth method returns the width of a video frame. Syntax long Return Values Value Width Description Video frame width in pixels

2.4.5.1 IDeckLinkVideoFrame::GetWidth method

GetWidth ();

2.4.5.2 IDeckLinkVideoFrame::GetHeight method


The GetHeight method returns the height of a video frame. Syntax long Return Values Value Height Description Video frame height in pixels

GetHeight ();

SDK Software Developers Kit

72

SECTION

DeckLink API
The GetRowBytes method returns the number of bytes per row of a video frame. Syntax long Return Values Value BytesCount Description Number of bytes per row of video frame

2.4.5.3 IDeckLinkVideoFrame::GetRowBytes method

GetRowBytes ();

2.4.5.4 IDeckLinkVideoFrame::GetPixelFormat method


The GetPixelFormat method returns the pixel format of a video frame. Syntax BMDPixelFormat Return Values Value PixelFormat Description Pixel format of video frame (BMDPixelFormat)

GetPixelFormat ();

SDK Software Developers Kit

73

SECTION

DeckLink API
The GetFlags method returns status flags associated with a video frame. Syntax BMDFrameFlags Return Values Value FrameFlags Description Video frame flags (BMDFrameFlags)

2.4.5.5 IDeckLinkVideoFrame::GetFlags method

GetFlags ();

2.4.5.6 IDeckLinkVideoFrame::GetBytes method


The GetBytes method allows direct access to the data buffer of a video frame. Syntax HRESULT Parameters Name buffer Return Values Value E_FAIL S_OK Description Failure Success Direction Description out Pointer to raw frame buffer only valid while object remains valid.

GetBytes (void **buffer);

SDK Software Developers Kit

74

SECTION

DeckLink API
The GetTimecode method returns the value specified in the ancillary data for the specified timecode type. If the specified timecode type is not found or is invalid, GetTimecode returns S_FALSE. Syntax HRESULT Parameters Name format timecode Direction Description in out BMDTimecodeFormat to query New IDeckLinkTimecode object interface containing the requested timecode or NULL if requested timecode is not available.

2.4.5.7 IDeckLinkVideoFrame::GetTimecode method

GetTimecode (BMDTimecodeFormat format, IDeckLinkTimecode **timecode)

Return Values Value E_FAIL S_OK E_ACCESSDENIED S_FALSE

Description Failure Success An invalid or unsupported timecode format was requested. The requested timecode format was not present or valid in the ancillary data.

SDK Software Developers Kit

75

SECTION

DeckLink API
The GetAncillaryData method returns a pointer to a video frames ancillary data. Syntax HRESULT Parameters Name ancillary Direction Description out Pointer to a new IDeckLinkVideoFrameAncillary object. This object must be released by the caller when no longer required.

2.4.5.8 IDeckLinkVideoFrame::GetAncillaryData method

GetAncillaryData (IDeckLinkVideoFrameAncillary **ancillary)

Return Values Value S_OK S_FALSE Description Success No ancillary data present.

SDK Software Developers Kit

76

SECTION

DeckLink API
The IDeckLinkVideoOutputCallback object interface is a callback class which is called for each frame as its processing is completed by the DeckLink device. An object with an IDeckLinkVideoOutputCallback object interface may be registered as a callback with the IDeckLinkOutput object interface. IDeckLinkVideoOutputCallback should be used to monitor frame output statuses and queue a replacement frame to maintain streaming playback. If the application is managing its own frame buffers, they should be disposed or reused inside the ScheduledFrameCompleted callback. Related Interfaces Interface
IDeckLinkOutput

2.4.6 IDeckLinkVideoOutputCallback Interface

Interface ID
IID_IDeckLinkOutput

Description An IDeckLinkVideoOutputCallback object interface may be registered with IDeckLinkOutput:: SetScheduledFrame CompletionCallback

Public Member Functions Method ScheduledFrameCompleted ScheduledPlaybackHasStopped Description Called when playback of a scheduled frame is completed Called when playback has stopped.

SDK Software Developers Kit

77

SECTION

DeckLink API
The ScheduledFrameCompleted method is called when a scheduled video frame playback is completed. This method is abstract in the base interface and must be implemented by the application developer. The result parameter (required by COM) is ignored by the caller. The IDeckLinkVideoOutputCallback methods are called on a dedicated callback thread. To prevent video frames from being either dropped or delayed, ensure that any application processing on the callback thread takes less time than a frame time. If the application processing time is greater than a frame time, multiple threads should be used. Syntax HRESULT

2.4.6.1 IDeckLinkVideoOutputCallback::ScheduledFrameCompleted method

ScheduledFrameCompleted (IDeckLinkVideoFrame* completedFrame, BMDOutputFrameCompletionResult result);

Parameters Name completedFrame result Direction Description in in Completed frame Frame completion result see BMDOutputFrameCompletionResult for details.

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

78

SECTION

DeckLink API
The ScheduledPlaybackHasStopped method is called when a scheduled playback has stopped. Syntax HRESULT Return Values Value E_FAIL S_OK Description Failure Success

2.4.6.2 IDeckLinkVideoOutputCallback::ScheduledPlaybackHasStopped method

ScheduledPlaybackHasStopped(void)

SDK Software Developers Kit

79

SECTION

DeckLink API
The IDeckLinkMutableVideoFrame object interface represents a video frame created for output. Methods are provided to attach ancillary data and set timecodes within the frame. IDeckLinkMutableVideoFrame is a subclass of IDeckLinkVideoFrame and inherits all its methods. It is created by the IDeckLinkOutput::CreateVideoFrame method. Related Interfaces Interface
IDeckLink VideoFrame

2.4.7 IDeckLinkMutableVideoFrame Interface.

Interface ID
IID_IDeckLink VideoFrame

Description IDeckLinkMutableVideoFrame subclasses IDeckLinkVideoFrame

Public Member Functions Method SetFlags SetTimecode SetTimecodeFromComponents SetAncillaryData Description Set flags applicable to a video frame Set timecode Set components of specified timecode type Set frame ancillary data

SDK Software Developers Kit

80

SECTION

DeckLink API
The SetFlags method sets output flags associated with a video frame. Syntax HRESULT Parameters Name newFlags Direction Description in BMDFrameFlags to set - see BMDFrameFlags for details.

2.4.7.1 IDeckLinkMutableVideoFrame::SetFlags method

SetFlags (BMDFrameFlags newFlags);

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

81

SECTION

DeckLink API
The SetTimecode method sets the specified timecode type for the frame. Note: To set VITC an ancillary buffer must first be attached. Syntax HRESULT Parameters Name format timecode Direction Description in in BMDTimecodeFormat to update IDeckLinkTimecode object interface containing timecode to copy.

2.4.7.2 IDeckLinkMutableVideoFrame::SetTimecode method

SetTimecode (BMDTimecodeFormat format, BMDTimecode* timecode);

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

82

SECTION

DeckLink API
The SetTimecodeFromComponents method sets the components of the specified timecode type for the frame. Note: To set VITC an ancillary buffer must first be attached. Syntax HRESULT

2.4.7.3 IDeckLinkMutableVideoFrame::SetTimecodeFromComponents method

SetTimecodeFromComponents (BMDTimecodeFormat format, uint8_t hours, uint8_t minutes, uint8_t seconds, uint8_t frames, BMDTimecodeFlags flags);

Parameters Name format hours minutes seconds frames flags Return Values Value E_FAIL S_OK Description Failure Success Direction Description in in in in in in BMDTimecodeFormat to update Value of hours component of timecode Value of minutes component of timecode Value of seconds component of timecode Value of frames component of timecode Timecode flags (see BMDTimecodeFlags for details)

SDK Software Developers Kit

83

SECTION

DeckLink API
The SetAncillaryData method sets frame ancillary data. An IDeckLinkVideoFrameAncillary may be created using the IDeckLinkOutput::CreateAncillaryData method. Syntax HRESULT Parameters Name ancillary Direction Description in IDeckLinkVideoFrameAncillary data to output with the frame. SetAncillaryData (IDeckLinkVideoFrameAncillary* ancillary);

2.4.7.4 IDeckLinkMutableVideoFrame::SetAncillaryData method

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

84

SECTION

DeckLink API
The IDeckLinkAudioOutputCallback object interface is a callback class called regularly during playback to allow the application to check for the amount of audio currently buffered and buffer more audio if required. An IDeckLinkAudioOutputCallback object interface may be registered with IDeckLinkOutput::SetAudioCallback. Related Interfaces Interface
IDeckLinkOutput

2.4.8 IDeckLinkAudioOutputCallback interface

Interface ID
IID_IDeckLinkOutput

Description An IDeckLinkAudioOutputCallback object interface may be registered with IDeckLinkOutput::SetAudioCallback

Public Member Functions Method RenderAudioSamples Description Called to allow buffering of more audio samples if required

SDK Software Developers Kit

85

SECTION

DeckLink API
The RenderAudioSamples method is called at a rate of 50Hz during preroll and playback. This method is abstract in the base interface and must be implemented by the application developer. The result parameter (required by COM) is ignored by the caller. The method should check the count of buffered audio samples with IDeckLinkOutput::GetBuffered AudioSampleFrameCount and when required, schedule more audio samples with IDeckLinkOutput:: ScheduleAudioSamples. Syntax HRESULT Parameters Name preroll

2.4.8.1 IDeckLinkAudioOutputCallback::RenderAudioSamples method

RenderAudioSamples (boolean preroll);

Direction Description in Flag specifying whether driver is currently prerolling (TRUE) or playing (FALSE).

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

86

SECTION

DeckLink API
The IDeckLinkInputCallback object interface is a callback class which is called for each captured frame. An object with an IDeckLinkInputCallback interface may be registered as a callback with the IDeckLinkInput object interface. Related Interfaces Interface
IDeckLinkInput

2.4.9 IDeckLinkInputCallback Interface

Interface ID
IID_IDeckLinkInput

Description An IDeckLinkInputCallback object interface may be registered with IDeckLinkInput::SetCallback An IDeckLinkVideoInputFrame object interface is passed to IDeckLinkInput Callback::VideoInputFrameArrived An IDeckLinkAudioInputPacket object interface is passed to IDeckLinkInput Callback::VideoInputFrameArrived

IDeckLinkVideo InputFrame IDeckLinkAudioInputPacket

IID_DeckLinkVideoInputFrame IID_DeckLinkAudioInputPacket

Public Member Functions Method VideoInputFrameArrived VideoInputFormatChanged Description Called when new video data is available Called when a video input format change is detected

SDK Software Developers Kit

87

SECTION

DeckLink API
The VideoInputFrameArrived method is called when a video input frame or an audio input packet has arrived. This method is abstract in the base interface and must be implemented by the application developer. The result parameter (required by COM) is ignored by the caller. Syntax HRESULT

2.4.9.1 IDeckLinkInputCallback::VideoInputFrameArrived method

VideoInputFrameArrived( IDeckLinkVideoInputFrame *videoFrame, IDeckLinkAudioInputPacket *audioPacket); Direction Description in The video frame that has arrived. The video frame is only valid for the duration of the callback. To hold on to the video frame beyond the callback call AddRef, and to release the video frame when it is no longer required call Release. The video frame will be NULL under the following circumstances: - On Intensity Pro with progressive NTSC only, every video frame will have two audio packets. - With 3:2 pulldown there are five audio packets for each four video frames. - If video processing is not fast enough, audio will still be delivered.

Parameters Name videoFrame

SDK Software Developers Kit

88

SECTION

DeckLink API
Name audioPacket Direction Description in New audio packet-only valid if audio capture has been enabled with IDeckLinkInput::EnableAudioInput The audio packet will be NULL under the following circumstances: - Audio input is not enabled. - If video processing is sufficiently delayed old video may be received with no audio. Return Values Value E_FAIL S_OK Description Failure Success

2.4.9.1

SDK Software Developers Kit

89

SECTION

DeckLink API
The VideoInputFormatChanged method is called when a video input format change has been detected by the hardware. To enable this feature, the bmdVideoInputEnableFormatDetection flag must set when calling IDeckLinkInput::EnableVideoInput(). Note: The video format change detection feature is not currently supported on all hardware. Check the BMDDeckLinkSupportsInputFormatDetection attribute to determine if this feature is supported for a given device and driver (see IDeckLinkAttributes Interface for details). Syntax HRESULT

2.4.9.2 IDeckLinkInputCallback::VideoInputFormatChanged method

VideoInputFormatChanged (BMDVideoInputFormatChangedEvents notificationEvents, IDeckLinkDisplaymode *newDisplayMode, BMDDetectedVideoInputFormatFlags detectedSignalFlags);

Parameters Name notificationEvents newDisplayMode detectedSignalFlags Return Values Value E_FAIL S_OK Description Failure Success Direction Description in in in The notification events - enable input detection The new display mode. The detected signal flags

SDK Software Developers Kit

90

SECTION

DeckLink API
The IDeckLinkVideoInputFrame object interface represents a video frame which has been captured by an IDeckLinkInput object interface. IDeckLinkVideoInputFrame is a subclass of IDeckLinkVideoFrame and inherits all its methods. Objects with an IDeckLinkVideoInputFrame interface are passed to the IDeckLinkInputCall back::VideoInputFrameArrived callback. Related Interfaces Interface
IDeckLinkInput

2.4.10 IDeckLinkVideoInputFrame Interface

Interface ID
IID_IDeckLinkInput

Description New input frames are returned to IDeck LinkInputCallback::VideoInputFrameAr rived by the IDeckLinkInput interface IDeckLinkVideoInputFrame subclasses IDeckLinkVideoFrame

IDeckLink VideoFrame

IID_IDeckLink VideoFrame

Public Member Functions Method GetStreamTime GetHardwareReferenceTimestamp Description Get video frame timing information Get hardware reference timestamp

SDK Software Developers Kit

91

SECTION

DeckLink API
The GetStreamTime method returns the time and duration of a captured video frame for a given timescale. Syntax HRESULT

2.4.10.1 IDeckLinkVideoInputFrame::GetStreamTime method

GetStreamTime (BMDTimeValue *frameTime, BMDTimeValue *frameDuration, BMDTimeScale timeScale);

Parameters Name frameTime frameDuration timeScale

Direction Description out out in Frame time (in units of timeScale) Frame duration (in units of timeScale) Time scale for output parameters

Return Values Value E_FAIL S_OK

Description Failure Success

SDK Software Developers Kit

92

SECTION

DeckLink API
The GetHardwareReferenceTimestamp method returns frame time and frame duration for a given timescale. Syntax HRESULT

2.4.10.2 IDeckLinkVideoInputFrame::GetHardwareReferenceTimestamp method

GetHardwareReferenceTimestamp (BMDTimeScale timeScale, BMDTimeValue *frameTime, BMDTimeValue *frameDuration);

Parameters Name timeScale frameTime frameDuration Direction Description in out out The time scale - see BMDTimeScale for details. The frame time - see BMDTimeValue for details. The frame duration - see BMDTimeValue for details.

Return Values Value E_INVALIDARG S_OK Description Timescale is not set Success

SDK Software Developers Kit

93

SECTION

DeckLink API
The IDeckLinkAudioInputPacket object interface represents a packet of audio which has been captured by an IDeckLinkInput object interface. Objects with an IDeckLinkAudioInputPacket object interface are passed to the IDeckLinkInputCallback::VideoInputFrameArrived callback. Audio channel samples are interleaved into a sample frame and sample frames are contiguous. Related Interfaces Interface
IDeckLink InputCallback

2.4.11 IDeckLinkAudioInputPacket Interface

Interface ID
IID_IDeckLink InputCallback

Description New audio packets are returned to the IDeckLinkInputCallback::VideoInputFra meArrived callback

Public Member Functions Method GetSampleFrameCount GetBytes GetPacketTime Description Get number of sample frames in packet Get pointer to raw audio frame sequence Get corresponding video timestamp

SDK Software Developers Kit

94

SECTION

DeckLink API
The GetSampleFrameCount method returns the number of sample frames in the packet. Syntax Long Return Values Value Count Description Audio packet size in sample frames

2.4.11.1 IDeckLinkAudioInputPacket::GetSampleFrameCount method

GetSampleCount ();

2.4.11.2 IDeckLinkAudioInputPacket::GetBytes method


The GetBytes method returns a pointer to the data buffer of the audio packet. Syntax HRESULT Parameters Name buffer Return Values Value E_FAIL S_OK Description Failure Success Direction Description out pointer to audio data only valid while object remains valid

GetBytes (void **buffer);

SDK Software Developers Kit

95

SECTION

DeckLink API
The GetPacketTime method returns the time stamp of the video frame corresponding to the specified audio packet. Syntax HRESULT

2.4.11.3 IDeckLinkAudioInputPacket::GetPacketTime method

GetPacketTime(BMDTimeValue *packetTime, BMDTimeScale timeScale);

Parameters Name packetTime timeScale

Direction Description out in Video frame time corresponding to audio packet in timeScale units Time scale for time stamp to be returned

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

96

SECTION

DeckLink API
The IDeckLinkDisplayModeIterator object interface is used to enumerate the available display modes for a DeckLink device. An IDeckLinkDisplayModeIterator object interface may be obtained from an IDeckLinkInput or IDeckLinkOutput object interface using the GetDisplayModeIterator method. Related Interfaces Interface
IDeckLinkInput

2.4.12 IDeckLinkDisplayModeIterator Interface

Interface ID
IID_IDeckLinkInput

Description IDeckLinkInput::GetDispla yModeIterator returns an IDeckLinkDisplayModeIterator object interface IDeckLinkOutput::GetDisp layModeIterator returns an IDeckLinkDisplayModeIterator object interface IDeckLinkDisplayModeIterator::Next returns an IDeckLinkDisplayMode object interface for each available display mode

IDeckLinkOutput

IID_IDeckLinkOutput

IDeckLink InputCallback

IID_IDeckLink InputCallback

Public Member Functions Method Next Description Returns a pointer to an IDeckLinkDisplayMode interface for an available display mode

SDK Software Developers Kit

97

SECTION

DeckLink API
The Next method returns the next available IDeckLinkDisplayMode interface. Syntax HRESULT Parameters Name displayMode Direction Description out IDeckLinkDisplayMode object interface or NULL when no more display modes are available.

2.4.12.1 IDeckLinkDisplayModeIterator::Next method

Next (IDeckLinkDisplayMode **displayMode);

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

98

SECTION

DeckLink API
The IDeckLinkDisplayMode object interface represents a supported display mode. The IDeckLinkDisplayModeIterator object interface enumerates supported display modes, returning IDeckLinkDisplayMode object interfaces. Related Interfaces Interface
IDeckLink DisplayMode Iterator

2.4.13 IDeckLinkDisplayMode Interface

Interface ID
IID_IDeckLink DisplayModeIterator

Description IDeckLinkDisplayModeIterator::Next returns an IDeckLinkDisplayMode object interface for each available display mode

Public Member Functions Method GetWidth GetHeight GetName GetDisplayMode GetFrameRate GetFieldDominance Description Get video frame width in pixels Get video frame height in pixels Get descriptive text Get corresponding BMDDisplayMode Get the frame rate of the display mode Gets the field dominance of the frame

SDK Software Developers Kit

99

SECTION

DeckLink API
The GetWidth method returns the width of a video frame in the display mode. Syntax long Return Values Value Width Description Video frame width in pixels

2.4.13.1 IDeckLinkDisplayMode::GetWidth method

GetWidth ();

2.4.13.2 IDeckLinkDisplayMode::GetHeight method


The GetHeight method returns the height of a video frame in the display mode. Syntax long Return Values Value Height Description Video frame height in pixels

GetHeight ();

SDK Software Developers Kit

100

SECTION

DeckLink API
The GetName method returns a string describing the display mode. Syntax HRESULT Parameters Name name

2.4.13.3 IDeckLinkDisplayMode::GetName method

GetName (string *name);

Direction Description out Descriptive string This allocated string must be freed by the caller when no longer required. Description Failure Success

Return Values Value E_FAIL S_OK

2.4.13.4 IDeckLinkDisplayMode::GetDisplayMode method


The GetDisplayMode method returns the corresponding BMDDisplayMode for the selected display mode. Syntax BMDDisplayMode Return Values Value mode

GetDisplayMode ();

Description BMDDisplayMode corresponding to the display mode

SDK Software Developers Kit

101

SECTION

DeckLink API
The GetFrameRate method returns the frame rate of the display mode. The frame rate is represented as the two integer components of a rational number for accuracy. The actual frame rate can be calculated by timeScale / timeValue Syntax HRESULT

2.4.13.5 IDeckLinkDisplayMode::GetFrameRate method

GetFrameRate (BMDTimeValue *timeValue, BMDTimeScale *timeScale);

Parameters Name timeValue timeScale Return Values Value E_FAIL S_OK Description Failure Success Direction Description out out Frame rate value Frame rate scale

SDK Software Developers Kit

102

SECTION

DeckLink API
The GetFieldDominance method gets the field dominance of the frame. Syntax BMDFieldDominance Return Values Value FieldDominance Description The field dominance - see BMDFieldDominance for details.

2.4.13.6 IDeckLinkDisplayMode::GetFieldDominance method

GetFieldDominance ();

SDK Software Developers Kit

103

SECTION

DeckLink API
The IDeckLinkConfiguration object interface allows querying and modification of DeckLink configuration preferences. An IDeckLinkConfiguration object interface can be obtained from an IDeckLink interface using QueryInterface. Preferences are global (not limited to the current process) and persistent until system shutdown. The WriteConfigurationToPreferences method may be used to make the current configuration persist across restarts. The GetConfigurationValidator method may be used to create an IDeckLinkConfiguration object interface which may be used to validate desired configuration changes. Related Interfaces Interface
IDeckLink

2.4.14 IDeckLinkConfiguration Interface

Interface ID
IID_IDeckLink

Description DeckLink device interface

Public Member Functions Method GetConfigurationValidator WriteConfigurationToPreferences SetVideoOutputFormat IsVideoOutputActive Description Create a configuration validation object. Write configuration persistently. Set video output format. Get status of video output

SDK Software Developers Kit

104

SECTION

DeckLink API
Public Member Functions Method SetAnalogVideoOutputFlags GetAnalogVideoOutputFlags EnableFieldFlickerRemovalWhenPaused IsEnabledFieldFlickerRemovalWhenPaused Set444And3GBpsVideoOutput Get444And3GBpsVideoOutput SetVideoOutputConversionMode GetVideoOutputConversionMode Set_HD1080p24_to_HD1080i5994_Conversion Get_HD1080p24_to_HD1080i5994_Conversion SetVideoInputFormat GetVideoInputFormat SetAnalogVideoInputFlags GetAnalogVideoInputFlags Description Set analog video output options Get analog video output options Set field flicker removal option Get field flicker removal option status Set configuration of 444 video and 3GB/s options. Get configuration of 444 video and 3GB/s options. Set video output conversion options Get video output conversion options Configure HD1080p24 to HD1080i5994 conversion Get HD1080p24 to HD1080i5994 conversion status. Set video input format. Get video input format. Set analog video input options Get analog video input options

SDK Software Developers Kit

105

SECTION

DeckLink API
Public Member Functions Method SetVideoInputConversionMode GetVideoInputConversionMode SetBlackVideoOutputDuringCapture GetBlackVideoOutputDuringCapture Set32PulldownSequenceInitialTimecodeFrame Get32PulldownSequenceInitialTimecodeFrame SetVancSourceLineMapping GetVancSourceLineMapping SetAudioInputFormat GetAudioInputFormat Description Set video input conversion mode Get video input conversion mode Set black video output during capture option Get black video output during capture option Configure 3:2 pulldown Get 3:2 pulldown configuration Set VANC to active picture mapping Get VANC to active picture mapping configuration Set audio input format mode Get audio input format mode

SDK Software Developers Kit

106

SECTION

DeckLink API
The GetConfigurationValidator method returns a new IDeckLinkConfiguration interface which is unable to change the current system configuration or update the system configuration preferences. The new interface may be used to check if certain configuration changes are valid without changing the current state of the configuration. Syntax HRESULT Parameters Name configObject Return Values Value E_FAIL S_OK Description Failure Success Direction Description out IDeckLinkConfiguration object interface

2.4.14.1 IDeckLinkConfiguration::GetConfigurationValidator method

GetConfigurationValidator (IDeckLinkConfiguration** configObject);

SDK Software Developers Kit

107

SECTION

DeckLink API
The WriteConfigurationToPreferences method saves the current settings to system preferences so they will persist across system restarts. Syntax HRESULT Return Values Value E_FAIL S_OK Description Failure Success

2.4.14.2 IDeckLinkConfiguration::WriteConfigurationToPreferences method

WriteConfigurationToPreferences ();

SDK Software Developers Kit

108

SECTION

DeckLink API
The SetVideoOutputFormat method allows setting of the desired video output connection. The BMDVideoConnection type enumerates the possible connection types. Enabling video output on one connection will enable output on other available output connections which are compatible. The status of any given output connection can be queried with IsVideoOutputActive. Syntax HRESULT Parameters Name
videoOutputConnection

2.4.14.3 IDeckLinkConfiguration::SetVideoOutputFormat method

SetVideoOutputFormat (BMDVideoConnection videoOutputConnection);

Direction Description in primary connection for output

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

109

SECTION

DeckLink API
The IsVideoOutputActive method returns the status of a selected output connection. The BMDVideoConnection type enumerates the possible output connection types. Syntax HRESULT

2.4.14.4 IDeckLinkConfiguration::IsVideoOutputActive method

IsVideoOutputActive (BMDVideoConnection videoOutputConnection, boolean *active);

Parameters Name
videoOutputConnection

Direction Description in out Video output connection to be queried Status of video output connection TRUE for active

active

Return Values Value E_FAIL E_INVALIDARG S_OK Description Failure Invalid format Success

SDK Software Developers Kit

110

SECTION

DeckLink API
The Set444And3GBpsVideoOutput method allows configuration of the 444 video and 3Gb/s output options. Syntax HRESULT

2.4.14.5 IDeckLinkConfiguration::Set444And3GBpsVideoOutput method

Set444And3GBpsVideoOutput (boolean enable444VideoOutput, boolean enable3GbsOutput)

Parameters Name
enable444VideoOutput

Direction Description in in Boolean value to enable (TRUE) or disable (FALSE) 444 video output Boolean value to enable (TRUE) or disable (FALSE) 3Gb/s output

enable3GbsOutput

Return Values Value E_INVALIDARG E_FAIL S_OK Description The hardware does not support 444 video output. Failure Success

SDK Software Developers Kit

111

SECTION

DeckLink API
The Get444And3GBpsVideoOutput method returns the current configuration of the 444 video and 3Gb/s output options. Syntax HRESULT

2.4.14.6 IDeckLinkConfiguration::Get444And3GBpsVideoOutput method

Get444And3GBpsVideoOutput (boolean *enable444VideoOutput, boolean *enable3GbsOutput)

Parameters Name
enable444VideoOutput

Direction Description out out current 444 video output setting: enable (TRUE) disabled (FALSE) current 3 Gb/s output setting: enable (TRUE) disabled (FALSE)

enable3GbsOutput

Return Values Value E_INVALIDARG E_FAIL S_OK Description The hardware does not support 444 output video. Failure Success

SDK Software Developers Kit

112

SECTION

DeckLink API
The SetAnalogVideoOutputFlags method allows configuration of the analog video output if available. BMDAnalogVideoFlags enumerates the available analog video flags. Syntax HRESULT Parameters Name analogVideoFlags Return Values Value E_FAIL E_INVALIDARG S_OK Description Failure No analog output available Success Direction Description out New analog video output flags

2.4.14.7 IDeckLinkConfiguration::SetAnalogVideoOutputFlags method

SetAnalogVideoOutputFlags (BMDAnalogVideoFlags analogVideoFlags);

SDK Software Developers Kit

113

SECTION

DeckLink API
The GetAnalogVideoOutputFlags returns the current analog video output flags. BMDAnalogVideoFlags enumerates the available analog video flags. Syntax HRESULT Parameters Name analogVideoFlags Return Values Value E_FAIL E_INVALIDARG S_OK Description Failure No analog output available Success Direction Description out current flags

2.4.14.8 IDeckLinkConfiguration::GetAnalogVideoOutputFlags method

GetAnalogVideoOutputFlags (BMDAnalogVideoFlags *analogVideoFlags);

SDK Software Developers Kit

114

SECTION

DeckLink API
The EnableFieldFlickerRemovalWhenPaused method allows configuration of the field flicker removal when paused option. Syntax HRESULT Parameters Name enable Return Values Value E_FAIL S_OK Description Failure Success Direction Description in A Boolean value to enable (TRUE) or disable (FALSE) field flicker removal when paused

2.4.14.9 IDeckLinkConfiguration::EnableFieldFlickerRemovalWhenPaused method

EnableFieldFlickerRemovalWhenPaused (boolean enable);

SDK Software Developers Kit

115

SECTION

DeckLink API
The IsEnabledFieldFlickerRemovalWhenPaused method returns the current state of the field flicker removal when paused option. Syntax HRESULT Parameters Name enable Return Values Value E_FAIL S_OK Description Failure Success Direction Description out enabled (TRUE) or disabled (FALSE)

2.4.14.10 IDeckLinkConfiguration::IsEnabledFieldFlickerRemovalWhenPaused method

IsEnabledFieldFlickerRemovalWhenPaused (boolean *enabled);

SDK Software Developers Kit

116

SECTION

DeckLink API
The SetVideoOutputConversionMode method sets the video output conversion mode. The possible output modes are enumerated by BMDVideoOutputConversionMode. Syntax HRESULT

2.4.14.11 IDeckLinkConfiguration::SetVideoOutputConversionMode method

SetVideoOutputConversionMode ( BMDVideoOutputConversionMode conversionMode);

Parameters Name conversionMode Direction Description in Desired video output conversion mode

Return Values Value E_FAIL E_INVALIDARG S_OK Description Failure Requested conversion is not supported by this device Success

SDK Software Developers Kit

117

SECTION

DeckLink API
The GetVideoOutputConversionMode method gets the current video output conversion mode. Syntax HRESULT

2.4.14.12 IDeckLinkConfiguration::GetVideoOutputConversionMode method

GetVideoOutputConversionMode ( BMDVideoOutputConversionMode *conversionMode);

Parameters Name conversionMode Direction Description out current video output conversion mode

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

118

SECTION

DeckLink API
The Set_HD1080p24_to_HD1080i5994_Conversion method allows configuration of the HD1080p24 to HD1080i5994 conversion mode. Syntax HRESULT

2.4.14.13 IDeckLinkConfiguration::Set_HD1080p24_to_HD1080i5994_Conversion method

Set_HD1080p24_to_HD1080i5994_Conversion (boolean enable);

Parameters Name enable Direction Description in enable (TRUE) or disable (FALSE)

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

119

SECTION

DeckLink API
The Get_HD1080p24_to_HD1080i5994_Conversion method returns the current status of the HD1080p24 to HD1080i5994 conversion mode. Syntax HRESULT

2.4.14.14 IDeckLinkConfiguration::Get_HD1080p24_to_HD1080i5994_Conversion method

Get_HD1080p24_to_HD1080i5994_Conversion (boolean *enabled);

Parameters Name enable Direction Description out conversion status - enabled (TRUE) or disabled (FALSE)

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

120

SECTION

DeckLink API
The SetVideoInputFormat method sets the video connection to use for video input. Syntax HRESULT

2.4.14.15 IDeckLinkConfiguration::SetVideoInputFormat method

SetVideoInputFormat (BMDVideoConnection videoInputFormat);

Parameters Name videoInputFormat Direction Description in Variable of type BMDVideoConnection containing the desired video input connection

Return Values Value E_FAIL E_INVALIDARG S_OK Description Failure Input format not supported on this device Success

SDK Software Developers Kit

121

SECTION

DeckLink API
The GetVideoInputFormat method returns the current video connection used for video input. Syntax HRESULT

2.4.14.16 IDeckLinkConfiguration::GetVideoInputFormat method

GetVideoInputFormat (BMDVideoConnection *videoInputFormat);

Parameters Name videoInputFormat Direction Description out current connection used for video input

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

122

SECTION

DeckLink API
The SetAnalogVideoInputFlags method allows configuration of analog video input flags. Syntax HRESULT

2.4.14.17 IDeckLinkConfiguration::SetAnalogVideoInputFlags method

SetAnalogVideoInputFlags (BMDAnalogVideoFlags analogVideoFlags);

Parameters Name analogVideoFlags Direction Description in Variable of type BMDAnalogVideoFlags containing desired analog video input flags

Return Values Value E_FAIL E_INVALIDARG S_OK Description Failure Device does not support analog video input Success

SDK Software Developers Kit

123

SECTION

DeckLink API
The GetAnalogVideoInputFlags method returns the currently enabled analog video input flags. Syntax HRESULT

2.4.14.18 IDeckLinkConfiguration::GetAnalogVideoInputFlags method

GetAnalogVideoInputFlags (BMDAnalogVideoFlags *analogVideoFlags);

Parameters Name analogVideoFlags Direction Description out current analog video input flags

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

124

SECTION

DeckLink API
The SetVideoInputConversionMode method allows setting of the current video input conversion mode. Syntax HRESULT

2.4.14.19 IDeckLinkConfiguration::SetVideoInputConversionMode method

SetVideoInputConversionMode ( BMDVideoInputConversionMode conversionMode);

Parameters Name conversionMode Direction Description in New video input conversion mode

Return Values Value E_FAIL E_INVALIDARG S_OK Description Failure Requested mode is not supported by device Success

SDK Software Developers Kit

125

SECTION

DeckLink API
The GetVideoInputConversionMode method returns the currently selected video input conversion mode. Syntax HRESULT

2.4.14.20 IDeckLinkConfiguration::GetVideoInputConversionMode method

GetVideoInputConversionMode ( BMDVideoInputConversionMode *conversionMode;

Parameters Name conversionMode Direction Description out current video input conversion mode

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

126

SECTION

DeckLink API
The SetBlackVideoOutputDuringCapture method allows configuration of the black video output during capture mode. Note: This feature is only supported on legacy DeckLink devices. Syntax HRESULT Parameters Name blackOutInCapture Direction Description in New setting - enabled (TRUE) or disabled (FALSE) SetBlackVideoOutputDuringCapture (boolean blackOutInCapture);

2.4.14.21 IDeckLinkConfiguration::SetBlackVideoOutputDuringCapture method

Return Values Value E_FAIL E_INVALIDARG S_OK Description Failure black video output during capture mode not supported Mode not supported on this device Success

SDK Software Developers Kit

127

SECTION

DeckLink API
The GetBlackVideoOutputDuringCapture returns the current setting of the black video output during capture mode. Note: This feature is only supported on legacy DeckLink devices. Syntax HRESULT Parameters Name blackOutInCapture Direction Description out Current mode - enabled (TRUE) or disabled (FALSE) GetBlackVideoOutputDuringCapture (boolean *blackOutInCapture);

2.4.14.22 IDeckLinkConfiguration::GetBlackVideoOutputDuringCapture method

Return Values Value E_FAIL E_INVALIDARG S_OK Description Failure Mode not supported on this device Success

SDK Software Developers Kit

128

SECTION

DeckLink API
The Set32PulldownSequenceInitialTimecodeFrame method sets the time-code corresponding to the initial frame of a 3:2 pull down sequence. Syntax HRESULT Parameters Name aFrameTimecode Direction Description in Time-code of the initial frame of 3:2 pulldown sequence

2.4.14.23 IDeckLinkConfiguration::Set32PulldownSequenceInitialTimecodeFrame method

Set32PulldownSequenceInitialTimecodeFrame (unsigned long aFrameTimecode);

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

129

SECTION

DeckLink API
The Get32PulldownSequenceInitialTimecodeFrame method returns the time-code of the initial frame in a 3:2 pulldown sequence. Syntax HRESULT Parameters Name aFrameTimecode Direction Description out time-code of initial frame of 3:2 pulldown sequence

2.4.14.24 IDeckLinkConfiguration::Get32PulldownSequenceInitialTimecodeFrame method

Get32PulldownSequenceInitialTimecodeFrame (unsigned long *aFrameTimecode);

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

130

SECTION

DeckLink API
The SetVancSourceLineMapping method allows configuration of up to three lines of VANC to be transferred to or from the active picture on capture or output. Syntax HRESULT

2.4.14.25 IDeckLinkConfiguration::SetVancSourceLineMapping method

SetVancSourceLineMapping (unsigned long activeLine1VANCsource, unsigned long activeLine2VANCsource, unsigned long activeLine3VANCsource);

Parameters Name activeLine1 VANCsource activeLine2 VANCsource activeLine3 VANCsource Return Values Value E_FAIL S_OK Description Failure Success Direction Description in in in First VANC line to transfer or 0 for none Second VANC line to transfer or 0 for none Third VANC line to transfer or 0 for none

SDK Software Developers Kit

131

SECTION

DeckLink API
The GetVancSourceLineMapping method returns the current VANC to active picture line mapping. Syntax HRESULT

2.4.14.26 IDeckLinkConfiguration::GetVancSourceLineMapping method

GetVancSourceLineMapping (unsigned long *activeLine1VANCsource, unsigned long *activeLine2VANCsource, unsigned long *activeLine3VANCsource);

Parameters Name activeLine1 VANCsource activeLine2 VANCsource activeLine3 VANCsource Return Values Value E_FAIL S_OK Description Failure Success Direction Description in in in first line of VANC to be transferred or 0 if no mapping is configured for this line second line of VANC to be transferred or 0 if no mapping is configured for this line third line of VANC to be transferred or 0 if no mapping is configured for this line

SDK Software Developers Kit

132

SECTION

DeckLink API
The SetAudioInputFormat method configures the desired audio input connection. Syntax HRESULT Parameters Name audioInputFormat Direction Description in new audio input connection

2.4.14.27 IDeckLinkConfiguration::SetAudioInputFormat method

SetAudioInputFormat (BMDAudioConnection audioInputFormat);

Return Values Value E_FAIL S_OK

Description Failure Success

SDK Software Developers Kit

133

SECTION

DeckLink API
The GetAudioInputFormat method returns the currently active audio input connection. Syntax HRESULT Parameters Name audioInputFormat Direction Description out current audio input connection

2.4.14.28 IDeckLinkConfiguration::GetAudioInputFormat method

GetAudioInputFormat (BMDAudioConnection *audioInputFormat);

Return Values Value E_FAIL S_OK

Description Failure Success

SDK Software Developers Kit

134

SECTION

DeckLink API
The IDeckLinkAPIInformation object interface provides global API information. An IDeckLinkAPIInformation object interface can be obtained from IDeckLinkIterator using QueryInterface. Related Interfaces Interface
IDeckLinkIterator

2.4.15 IDeckLinkAPIInformation Interface

Interface ID
IID_IDeckLinkIterator

Description Decklink device interface

Public Member Functions Method GetFlag GetInt GetFloat GetString Description Gets a boolean flag associated with specified BMDDeckLinkAPIInformationID Gets an int64_t associated with specified BMDDeckLinkAPIInformationID Gets a float associated with specified BMDDeckLinkAPIInformationID Gets a string associated with specified BMDDeckLinkAPIInformationID

SDK Software Developers Kit

135

SECTION

DeckLink API
The GetFlag method gets a boolean flag associated with a given BMDDeckLinkAPIInformationID. Syntax HRESULT Parameters Name cfgID value Direction Description in out BMDDeckLinkAPIInformationID to get flag value. Value of flag corresponding to cfgID.

2.4.15.1 IDeckLinkAPIInformation::GetFlag method

GetFlag (BMDDeckLinkAPIInformationID cfgID, bool *value);

Return Values Value E_FAIL S_OK E_INVALIDARG Description Failure Success There is no flag type attribute corresponding to cfgID.

SDK Software Developers Kit

136

SECTION

DeckLink API
The GetInt method gets an int64_t value associated with a given BMDDeckLinkAPIInformationID. Syntax HRESULT Parameters Name cfgID value Direction Description in out BMDDeckLinkAPIInformationID to get int value. Value of int corresponding to cfgID.

2.4.15.2 IDeckLinkAPIInformation::GetInt method

GetInt (BMDDeckLinkAPIInformationID cfgID, int64_t *value);

Return Values Value S_OK E_INVALIDARG Description Success There is no int type attribute corresponding to cfgID.

SDK Software Developers Kit

137

SECTION

DeckLink API
The GetFloat method gets a float value associated with a given BMDDeckLinkAPIInformationID. Syntax HRESULT Parameters Name cfgID value Direction Description in out BMDDeckLinkAPIInformationID to get float value. Value of float corresponding to cfgID.

2.4.15.3 IDeckLinkAPIInformation::GetFloat method

GetFloat (BMDDeckLinkAPIInformationID cfgID, double *value);

Return Values Value S_OK E_INVALIDARG Description Success There is no float type attribute corresponding to cfgID.

SDK Software Developers Kit

138

SECTION

DeckLink API
The GetString method gets a string value associated with a given BMDDeckLinkAPIInformationID. Syntax HRESULT Parameters Name cfgID value Direction Description in out BMDDeckLinkAPIInformationID to get string value. Value of string corresponding to cfgID.

2.4.15.4 IDeckLinkAPIInformation::GetString method

GetString (BMDDeckLinkAPIInformationID cfgID, String *value);

Return Values Value S_OK E_INVALIDARG E_OUTOFMEMORY Description Success There is no string type attribute corresponding to cfgID. Unable to allocate memory for string

SDK Software Developers Kit

139

SECTION

DeckLink API
The IDeckLinkAttributes object interface provides details about the capabilities of a DeckLink card. The detail types that are available for various capabilities are: flag, int, float, and string. The DeckLink Attribute ID section lists the hardware capabilities and associated attributes identifiers that can be queried using this object interface. An IDeckLinkAttributes object interface can be obtained from the IDeckLink interface using QueryInterface. Related Interfaces Interface
IDeckLink

2.4.16 IDeckLinkAttributes Interface

Interface ID
IID_IDeckLink

Description Decklink device interface

Public Member Functions Method GetFlag GetInt GetFloat GetString Description Gets a boolean flag corresponding to a BMDDeckLinkAttributeID Gets an int64_t corresponding to a BMDDeckLinkAttributeID Gets a float corresponding to a BMDDeckLinkAttributeID Gets a string corresponding to a BMDDeckLinkAttributeID

SDK Software Developers Kit

140

SECTION

DeckLink API
The GetFlag method gets a boolean flag associated with a given BMDDeckLinkAttributeID. (See BMDDeckLinkAttributeID for a list of attribute IDs) Syntax HRESULT Parameters Name cfgID value

2.4.16.1 IDeckLinkAttributes::GetFlag method

GetFlag (BMDDeckLinkAttributeID cfgID, boolean *value);

Direction Description in out BMDDeckLinkAttributeID to get flag value. The value corresponding to cfgID.

Return Values Value E_FAIL S_OK E_INVALIDARG

Description Failure Success There is no flag type attribute corresponding to cfgID.

SDK Software Developers Kit

141

SECTION

DeckLink API
The GetInt method gets an int64_t value associated with a given BMDDeckLinkAttributeID. Syntax HRESULT Parameters Name cfgID value Direction Description in out BMDDeckLinkAttributeID to get int value. The value corresponding to cfgID.

2.4.16.2 IDeckLinkAttributes::GetInt method

GetInt ( BMDDeckLinkAttributeID cfgID, int64_t *value);

Return Values Value E_FAIL S_OK E_INVALIDARG Description Failure Success There is no int type attribute corresponding to cfgID.

SDK Software Developers Kit

142

SECTION

DeckLink API
The GetFloat method gets a float value associated with a given BMDDeckLinkAttributeID. Syntax HRESULT Parameters Name cfgID value Direction Description in out BMDDeckLinkAttributeID to get float value. The value corresponding to cfgID.

2.4.16.3 IDeckLinkAttributes::GetFloat method

GetFloat (BMDDeckLinkAttributeID cfgID, double *value);

Return Values Value E_FAIL S_OK E_INVALIDARG Description Failure Success There is no float type attribute corresponding to cfgID.

SDK Software Developers Kit

143

SECTION

DeckLink API
The GetString method gets a string value associated with a given BMDDeckLinkAttributeID. Syntax HRESULT Parameters Name cfgID value Direction Description in out BMDDeckLinkAttributeID to get string value. The value corresponding to cfgID. This allocated string must be freed by the caller when no longer required.

2.4.16.4 IDeckLinkAttributes::GetString method

GetString (BMDDeckLinkAttributeID cfgID, string *value);

Return Values Value E_FAIL S_OK E_INVALIDARG

Description Failure Success There is no string type attribute corresponding to cfgID.

SDK Software Developers Kit

144

SECTION

DeckLink API
The IDeckLinkMemoryAllocator interface may be registered as a callback with the IDeckLinkOutput interface. IDeckLinkOutput will call back to the interface for frame memory management. Implementation of this interface is optional - if this callback is not registered, a default allocator will be used. Related Interfaces Interface
IDeckLinkOutput

2.4.17 IDeckLinkMemoryAllocator interface

Interface ID
IID_IDeckLinkOutput

Description An IDeckLinkMemoryAllocator object interface may be registered with IDeckLinkOutput::SetVideoOutputFra meMemoryAllocator

Public Member Functions Method AllocateBuffer ReleaseBuffer Commit Decommit Description Called to allocate memory for a frame Called to release a previously allocated frame Called to notify the allocator that frame buffers will be required Called to notify the allocator that frame buffers will no longer be required (until next call to Commit).

SDK Software Developers Kit

145

SECTION

DeckLink API
The AllocateBuffer method is called by the owner interface to allocate a buffer for a video frame. This method is abstract in the base interface and must be implemented by the application developer. Syntax HRESULT

2.4.17.1 IDeckLinkMemoryAllocator::AllocateBuffer method

AllocateBuffer (unsigned long bufferSize, void **allocatedBuffer);

Parameters Name bufferSize allocatedBuffer Direction Description in out Size of the memory to be allocated for a new video frame Address of newly allocated buffer Note: Returned address for buffer must be aligned on a 16-byte boundary.

Return Values Value S_OK E_OUTOFMEMORY Description Success There is insufficient memory to allocate a buffer of the requested size.

SDK Software Developers Kit

146

SECTION

DeckLink API
The ReleaseBuffer method is called by the owner interface to release previously allocated memory. This method is abstract in the base interface and must be implemented by the application developer. Syntax HRESULT Parameters Name buffer

2.4.17.2 IDeckLinkMemoryAllocator::ReleaseBuffer method

ReleaseBuffer ( void *buffer);

Direction Description in Pointer to the buffer to be released

Return Values Value S_OK Description Success

SDK Software Developers Kit

147

SECTION

DeckLink API
The Commit method is called by the owner interface to notify the allocator that frame buffers will be required. The allocator should allocate any structures required for memory pool management in this callback. This method is abstract in the base interface and must be implemented by the application developer. Syntax HRESULT Parameters none. Return Values Value S_OK E_OUTOFMEMORY Description Success There is insufficient memory to allocate a buffer of the requested size.

2.4.17.3 IDeckLinkMemoryAllocator::Commit method

Commit ();

SDK Software Developers Kit

148

SECTION

DeckLink API
The Decommit method is called by the owner interface to notify the allocator that frame buffers will no longer be required. The allocator should de-allocate any structures required for memory pool management in this callback. The owner interface will call the Commit method again before allocating more frames. This method is abstract in the base interface and must be implemented by the application developer. Syntax HRESULT Parameters none. Return Values Value S_OK Description Success

2.4.17.4 IDeckLinkMemoryAllocator::Decommit method

Decommit ();

SDK Software Developers Kit

149

SECTION

DeckLink API
The IDeckLinkKeyer object interface allows configuration of the keying functionality available on most DeckLink cards. An IDeckLinkKeyer object interface can be obtained from the IDeckLink interface using QueryInterface. Related Interfaces Interface
IDeckLink

2.4.18 IDeckLinkKeyer Interface

Interface ID
IID_IDeckLink

Description DeckLink device interface

Public Member Functions Method Enable SetLevel RampUp RampDown Disable Description Turn on keyer. Set the level that the image is blended into the frame. Progressively blends in an image over a given number of frames Progressively blends out an image over a given number of frames Turn off keyer

SDK Software Developers Kit

150

SECTION

DeckLink API
The Enable method turns on the keyer functionality. The IDeckLinkAttributes interface can be used to determine if hardware supports the keyer functionality. If external keying is selected, the mask is output on CH A and the key on CH B. The following table lists the hardware that support various keyer capabilities. The following table displays hardware which supports the keyer functionality. Device Intensity Pro DeckLink SDI DeckLink Optical Fiber DeckLink Studio DeckLink HD Extreme Multibridge Pro Multibridge Eclipse Syntax HRESULT Parameters Name isExternal Return Values Value E_FAIL S_OK Description Failure Success Direction Description in Specifies internal or external keying. Internal no yes yes yes yes yes yes External no no no yes yes yes yes HD no no no no yes yes yes

2.4.18.1 IDeckLinkKeyer::Enable method

Enable (boolean isExternal);

SDK Software Developers Kit

151

SECTION

DeckLink API
The SetLevel method sets the level that the image is blended onto the frame. 0 is no blend, 255 is completely blended onto the frame. Syntax HRESULT Parameters Name level Return Values Value S_OK Description Success Direction Description in The level that the image is to be blended onto the frame. SetLevel (uint8_t level);

2.4.18.2 IDeckLinkKeyer::SetLevel method

SDK Software Developers Kit

152

SECTION

DeckLink API
The RampUp method progressively blends in an image over a given number of frames from 0 to 255. Syntax HRESULT Parameters Name numberOfFrames Return Values Value E_FAIL S_OK Description Failure Success Direction Description in The number of frames that the image is progressively blended in. RampUp (uint32_t numberOfFrames);

2.4.18.3 IDeckLinkKeyer::RampUp method

SDK Software Developers Kit

153

SECTION

DeckLink API
The RampDown method progressively blends out an image over a given number of frames from 255 to 0. Syntax HRESULT Parameters Name numberOfFrames Return Values Value E_FAIL S_OK Description Failure Success Direction Description in The number of frames that the image is progressively blended out. RampDown (uint32_t numberOfFrames);

2.4.18.4 IDeckLinkKeyer::RampDown method

SDK Software Developers Kit

154

SECTION

DeckLink API
The Disable method turns off the keyer functionality. Syntax HRESULT Return Values Value E_FAIL S_OK Description Failure Success Disable();

2.4.18.5 IDeckLinkKeyer::Disable method

SDK Software Developers Kit

155

SECTION

DeckLink API
The IDeckLinkVideoFrameAncillary object interface represents the ancillary data associated with a video frame. Related Interfaces Interface
IDeckLink Timecode

2.4.19 IDeckLinkVideoFrameAncillary Interface

Interface ID
IID_IDeckLinkTimeCode

Description IDeckLinkVideoFrameAncillary::Get TimeCode and IDeckLinkVideoFrame Ancillary::SetTimeCode, get and set timecodes in ancillary data from an IDeckLinkTimecode object interface.

Public Member Functions Method GetPixelFormat GetDisplayMode GetBufferForVerticalBlankingLine Description Gets pixel format of a video frame. Gets corresponding BMDDisplayMode for the selected display mode. Access vertical blanking line buffer.

SDK Software Developers Kit

156

SECTION

DeckLink API
The GetPixelFormat method gets the pixel format of a video frame. Syntax BMDPixelFormat GetPixelFormat (); Return Values Value PixelFormat Description Pixel format of video frame (BMDPixelFormat)

2.4.19.1 IDeckLinkVideoFrameAncillary::GetPixelFormat method

2.4.19.2 IDeckLinkVideoFrameAncillary::GetDisplayMode method


The GetDisplayMode method returns the corresponding BMDDisplayMode for the selected display mode. Syntax BMDDisplayMode Return Values Value mode Description BMDDisplayMode corresponding to the display mode.

GetDisplayMode ();

SDK Software Developers Kit

157

SECTION

DeckLink API
The GetBufferForVerticalBlankingLine method allows access to a specified vertical blanking line within the ancillary for the associated frame. Ancillary lines are numbered from one. For NTSC video, the top ancillary lines are numbered starting from four, with lines 1 to 3 referring to the ancillary lines at the bottom of the picture, as per convention. The pointer returned by GetBufferForVerticalBlankingLine is in the same format as the associated active picture data and is valid while the IDeckLinkVideoFrameAncillary object interface is valid. Syntax HRESULT Parameters Name lineNumber buffer Direction Description in out Ancillary line number to access. Pointer into ancillary buffer for requested line or NULL if line number was invalid.

2.4.19.3 IDeckLinkVideoFrameAncillary::GetBufferForVerticalBlankingLine method

GetBufferForVerticalBlankingLine (uint32_t lineNumber, void* *buffer)

Return Values Value E_FAIL S_OK E_INVALIDARG Description Failure Success An invalid ancillary line number was requested

SDK Software Developers Kit

158

SECTION

DeckLink API
The IDeckLinkTimecode object interface represents a video timecode and provides methods to access the timecode or its components. Related Interfaces Interface
IDeckLinkVideo FrameAncillary

2.4.20 IDeckLinkTimecode Interface

Interface ID
IID_IDeckLinkVideo FrameAncillary

Description IDeckLinkVideoFrameAncillary::GetTi mecode returns an IDeckLinkTimecode object interface

Public Member Functions Method GetBCD GetComponents GetString GetFlags Description Get timecode in BCD Get timecode components Get timecode as formatted string Get timecode flags

SDK Software Developers Kit

159

SECTION

DeckLink API
The GetBCD method returns the timecode in Binary Coded Decimal representation. Syntax BMDTimecodeBCD GetBCD(); Return Values Value Timecode Description Timecode value in BCD format (See BMDTimecodeBCD for details)

2.4.20.1 IDeckLinkTimecode::GetBCD method

SDK Software Developers Kit

160

SECTION

DeckLink API
The GetComponents method returns individual components of the timecode. Specify NULL for any unwanted parameters. Syntax HRESULT Parameters Name hours minutes seconds frames Direction Description out out out out Hours component of timecode Minutes component of timecode Seconds component of timecode Frames component of timecode

2.4.20.2 IDeckLinkTimecode::GetComponents method

GetComponents(uint8_t *hours, uint8_t *minutes, uint8_t *seconds, uint8_t *frames);

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

161

SECTION

DeckLink API
The GetString method returns the timecode formatted as a standard timecode string. Syntax HRESULT Parameters Name timecode Direction Description out Timecode formatted as a standard timecode string: HH:MM:SS:FF. This allocated string must be freed by the caller when no longer required

2.4.20.3 IDeckLinkTimecode::GetString method

GetString(string *timecode);

Return Values Value E_FAIL S_OK Description Failure Success

2.4.20.4 IDeckLinkTimecode::GetFlags method


The GetFlags method returns the flags accompanying a timecode. Syntax HRESULT Return Values Value timecodeFlags Description Timecode flags (see BMDTimecodeFlags for details)

BMDTimecodeFlags GetFlags();

SDK Software Developers Kit

162

SECTION

DeckLink API
The IDeckLinkScreenPreviewCallback object interface is a callback class which is called to facilitate updating of an on-screen preview of a video stream being played or captured. An object with the IDeckLinkScreenPreviewCallback object interface may be registered as a callbackwith the IDeckLinkInput or IDeckLinkOutput interfaces. During playback or capture, frames will be delivered to the preview callback. A dedicated preview thread waits for the next available frame before calling the callback. The frame delivery rate may be rate limited by the preview callback - it is not required to maintain full frame rate and missing frames in preview will have no impact on capture or playback. Related Interfaces Interface
IDeckLinkInput

2.4.21 IDeckLinkScreenPreviewCallback Interface

Interface ID
IID_IDeckLinkInput

Description An IDeckLinkScreenPreviewCallback object interface may be registered with IDeckLinkInput::SetScreenPreview Callback An IDeckLinkScreenPreviewCallback object interface may be registered with IDeckLinkOutput::SetScreenPrevi ewCallback

IDeckLinkOutput

IID_IDeckLinkOutput

Public Member Functions Method DrawFrame Description Called when a new frame is available for the preview display

SDK Software Developers Kit

163

SECTION

DeckLink API
The DrawFrame method is called on every frame boundary while scheduled playback is running. For example: Scheduled NTSC which runs at 29.97 frames per second, will result in the preview callbacks DrawFrame() method being called 29.97 times per second while scheduled playback is running. The return value (required by COM) is ignored by the caller. Note: If the frame to be drawn to the preview hasnt changed since the last time the callback was called, the frame parameter will be NULL. Syntax HRESULT Parameters Name theFrame Return Values Value E_FAIL S_OK Direction Description in Video frame to preview

2.4.21.1 IDeckLinkScreenPreviewCallback::DrawFrame method

DrawFrame(IDeckLinkVideoFrame *theFrame);

Description Failure Success

SDK Software Developers Kit

164

SECTION

DeckLink API
The IDeckLinkGLScreenPreviewHelper object interface may be used with a simple IDeckLinkScreenPreviewCallback implementation to provide OpenGL based preview rendering which is decoupled from the incoming or outgoing video stream being previewed. A reference to an IDeckLinkGLScreenPreviewHelper object interface may be obtained from CoCreateInstance on platforms with native COM support or from CreateOpenGLScreenPreviewHelper on other platforms. Typical usage of IDeckLinkGLScreenPreviewHelper is as follows: Configure an OpenGL context as an orthographic projection using code similar to the following: glViewport(0, 0, (GLsizei)newSize.width, (GLsizei)newSize.height); glMatrixMode(GL_PROJECTION); glLoadIdentity(); glOrtho(0.0, 1.0, 0.0, 1.0, -1.0, 1.0); glMatrixMode(GL_MODELVIEW); Create an IDeckLinkGLScreenPreviewHelper object interface using CoCreateInstance or CreateOpenGLScreenPreviewHelper Call IDeckLinkGLScreenPreviewHelper::InitializeGL from the OpenGL context When repainting the OpenGL context, call IDeckLinkGLScreenPreviewHelper::PaintGL. The preview image will be drawn between (-1,-1) and (1,1) in the GL space. Add any graphical overlays on the preview window as desired. Create a subclass of IDeckLinkScreenPreviewCallback which calls IDeckLinkGLScreenPreview Helper::SetFrame from IDeckLinkScreenPreviewCallback::DrawFrame

2.4.22 IDeckLinkGLScreenPreviewHelper Interface

SDK Software Developers Kit

165

SECTION

DeckLink API
Register an instance of the IDeckLinkScreenPreviewCallback subclass with IDeckLink Input::SetScreenPreviewCallback or IDeckLinkOutput::SetScreenPreviewCallback as appropriate. Related Interfaces Interface
IDeckLinkScreen Preview

Interface ID
IID_IDeckLinkScreen Preview

Description IDeckLinkGLScreenPreviewHelper::Set Frame may be called from IDeckLink ScreenPreview::DrawFrame

Public Member Functions Method InitializeGL PaintGL SetFrame Description Initialize GL previewing Repaint the GL preview Set the preview frame to display on the next PaintGL call

SDK Software Developers Kit

166

SECTION

DeckLink API
The InitializeGL method should be called from the preview OpenGL context during initialization of that context. Syntax HRESULT Return Values Value E_FAIL S_OK Description Failure Success

2.4.22.1 IDeckLinkGLScreenPreviewHelper::InitializeGL method

InitializeGL();

2.4.22.2 IDeckLinkGLScreenPreviewHelper::PaintGL method


The PaintGL method should be called from the preview OpenGL context whenever the preview frame needs to be repainted. Frames to be displayed should be provided to IDeckLinkGLScreenPreviewHelper::SetFrame. PaintGL and SetFrame allow OpenGL updates to be decoupled from new frame availability. Syntax HRESULT Return Values Value E_FAIL S_OK Description Failure Success

PaintGL();

SDK Software Developers Kit

167

SECTION

DeckLink API
The SetFrame method is used to set the preview frame to display on the next call to IDeckLinkGLScreenPreviewHelper::PaintGL. Depending on the rate and timing of calls to SetFrame and PaintGL, some frames may no be displayed or may be displayed multiple times. Syntax HRESULT Parameters Name theFrame Direction Description in Video frame to preview

2.4.22.3 IDeckLinkGLScreenPreviewHelper::SetFrame method

SetFrame(IDeckLinkVideoFrame *theFrame)

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

168

SECTION

DeckLink API
The IDeckLinkCocoaScreenPreviewCallback object interface is a cocoa callback class which is called to facilitate updating of an on-screen preview of a video stream being played or captured. An IDeckLinkCocoaScreenPreviewCallback object can be created by calling CreateCocoaScreenPreview. This object can registered as a callback with IDeckLinkInput::SetScreenPreviewCallback or IDeckLinkOutput::SetScreenPreviewCallback as appropriate. During playback or capture, frames will be delivered to the preview callback. A dedicated preview thread waits for the next available frame before calling the callback. The frame delivery rate may be rate limited by the preview callback - it is not required to maintain full frame rate and missing frames in preview will have no impact on capture or playback. Related Interfaces Interface
IDeckLinkInput

2.4.23 IDeckLinkCocoaScreenPreviewCallback Interface

Interface ID
IID_IDeckLinkInput

Description An IDeckLinkCocoaScreenPreview Callback object interface may be registered with IDeckLinkInput::Set ScreenPreviewCallback An IDeckLinkCocoaScreenPreview Callback object interface may be registered with IDeckLinkOutput::Set ScreenPreviewCallback

IDeckLinkOutput

IID_IDeckLinkOutput

SDK Software Developers Kit

169

SECTION

DeckLink API
The IDeckLinkVideoConversion object interface provides the capability to copy an image from a source frame into a destination frame converting between the formats as required. Public Member Functions Method ConvertFrame Description Copies and converts a source frame into a destination frame.

2.4.24 IDeckLinkVideoConversion Interface [new in DeckLink 7.6]

2.4.24.1 IDeckLinkVideoConversion::ConvertFrame method


The ConvertFrame method copies the source frame (srcFrame) to the destination frame (dstFrame). The frame dimension and pixel format of the video frame will be converted if possible. The return value for this method should be checked to ensure that the desired conversion is supported. The destination frame with the desired properties should be created using IDeckLinkOutput::CreateVideoFrame. The created frame can then be passed into this method. The following table displays the conversions that are currently supported with IDeckLinkVideoConversion class. Frame dimension Frame resizing is currently not supported. Pixel conversions Source frame bmdFormat8BitRGBA bmdFormat8BitBGRA bmdFormat8BitARGB Target frame bmdFormat8BitYUV bmdFormat8BitARGB bmdFormat8BitYUV bmdFormat8BitYUV

SDK Software Developers Kit

170

SECTION

DeckLink API
Syntax HRESULT ConvertFrame (IDeckLinkVideoFrame* srcFrame, IDeckLinkVideoFrame* dstFrame) Parameters Name srcFrame dstFrame Return Values Value E_FAIL S_OK E_NOTIMPL Description Failure Success Conversion not currently supported Direction Description in in The properties of the source frame The properties of the destination frame

SDK Software Developers Kit

171

SECTION

DeckLink API
The IDeckLinkDeckControl object interface provides the capability to control a deck via the RS422 port (if available) of a DeckLink device. An IDeckLinkDeckControl object interface can be obtained from the IDeckLink interface using QueryInterface. Related Interfaces Interface
IDeckLink DeckControl IDeckLink DeckControl StatusCallback

2.4.25 IDeckLinkDeckControl Interface [new in DeckLink 7.6]

Interface ID
IID_IDeckLinkDeck Control IID_ IDeckLinkDeck ControlStatusCallback

Description An IDecklinkDeckControl object interface may be obtained from IDeckLink using QueryInterface. An IDeckLinkDeckControlStatusCallback object interface may be registered with IDeckLinkDeckControl::SetCallback.

Public Member Functions Method Open Close GetCurrentState SetStandby Description Open a connection to the deck. Close the connection to the deck. Get the current state of the deck. Put the deck into standby mode.

SDK Software Developers Kit

172

SECTION

DeckLink API
Public Member Functions Method Play Stop TogglePlayStop Eject GoToTimecode FastForward Rewind StepForward StepBack Jog Shuttle GetTimecodeString GetTimecode GetTimecodeBCD Description Send a play command to the deck. Send a stop command to the deck. Toggle between play and stop mode. Send an eject command to the deck. Set the deck to go the specified timecode on the tape. Send a fast forward command to the deck. Send a rewind command to the deck. Send a step forward command to the deck. Send a step back command to the deck. Send a jog forward / reverse command to the deck. Send a shuttle forward / reverse command to the deck. Get a timecode from deck in string format. Get a timecode from deck in IDeckLinkTimeCode format. Get a timecode from deck in BMDTimecodeBCD format.

SDK Software Developers Kit

173

SECTION

DeckLink API
Public Member Functions Method SetPreroll GetPreroll SetCaptureOffset GetCaptureOffset SetExportOffset GetExportOffset GetManualExportOffset StartExport StartCapture GetDeviceID Abort CrashRecordStart CrashRecordStop SetCallback Description Set the preroll period. Get the preroll period. Set the field accurate capture timecode offset. Current capture timecode offset Set the field accurate export timecode offset. Get the current setting of the field accurate export timecode offset. Get the recommended delay fields of the current deck. Start an export to tape. Start a capture. Get deck device ID. Stop current deck operation. Send a record command to the deck. Send a stop record command to the deck. Set a deck control status callback.

SDK Software Developers Kit

174

SECTION

DeckLink API
The Open method configures a deck control session and opens a connection to a deck. This command will fail if a RS422 serial port is not available on the DeckLink device. Syntax HRESULT Parameters Name timeScale timeValue timecodeIsDropFrame error Direction Description in in in out The time scale. The time value in units of BMDTimeScale. Timecode is drop frame (TRUE) or a non drop frame (FALSE). The error code from the deck - see BMDDeckControlError for details.

2.4.25.1 IDeckLinkDeckControl::Open method

SetFrame(IDeckLinkVideoFrame *theFrame)

Return Values Value E_FAIL S_OK E_INVALIDARG Description Failure - check error parameter. Success One or more parameters are invalid.

SDK Software Developers Kit

175

SECTION

DeckLink API
The Close method will optionally place the deck in standby mode before closing the connection. Syntax HRESULT Parameters Name standbyOn Direction Description in Place the deck into standby mode (TRUE) before disconnection.

2.4.25.2 IDeckLinkDeckControl::Close method

Close (boolean standbyOn)

Return Values Value S_OK Description Success

SDK Software Developers Kit

176

SECTION

DeckLink API
The GetCurrentState method will get the current state of the deck. Syntax HRESULT

2.4.25.3 IDeckLinkDeckControl::GetCurrentState method

GetCurrentState (BMDDeckControlMode *mode, BMDDeckControlVTRControlState *vtrControlState, BMDDeckControlStatusFlags *flags);

Parameters Name mode vtrControlState flags Direction Description out out out The deck control mode - see BMDDeckControlMode for details. The deck control state - see BMDDeckControlVTRControlState for details. The deck control status flags - see BMDDeckControlStatusFlags for details.

Return Values Value S_OK E_INVALIDARG Description Success One or more parameters are invalid.

SDK Software Developers Kit

177

SECTION

DeckLink API
The SetStandby method will send a set standby command to the deck. The IDeckLinkDeckControl object must be in VTR control mode for this command to succeed. Syntax HRESULT Parameters Name standbyOn Direction Description in Set standby on (TRUE) , or set standby off (FALSE)

2.4.25.4 IDeckLinkDeckControl::SetStandby method

SetStandby (boolean standbyOn);

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

178

SECTION

DeckLink API
The Play method will send a play command to the deck. The IDeckLinkDeckControl object must be in VTR control mode for this command to succeed. Syntax HRESULT Parameters Name error Direction Description out The error code sent by the deck - see BMDDeckControlError for details.

2.4.25.5 IDeckLinkDeckControl::Play method

Play (BMDDeckControlError *error);

Return Values Value E_FAIL S_OK E_INVALIDARG Description Failure - check error parameter. Success The parameter is invalid.

SDK Software Developers Kit

179

SECTION

DeckLink API
The Stop method will send a stop command to the deck. The IDeckLinkDeckControl object must be in VTR control mode for this command to succeed. Syntax HRESULT Parameters Name error Direction Description out The error code sent by the deck - see BMDDeckControlError for details.

2.4.25.6 IDeckLinkDeckControl::Stop method

Stop (BMDDeckControlError *error);

Return Values Value E_FAIL S_OK E_INVALIDARG Description Failure - check error parameter. Success The parameter is invalid.

SDK Software Developers Kit

180

SECTION

DeckLink API
The TogglePlayStop method will send a play command to the deck, if the deck is currently paused or stopped. If the deck is currently playing, a pause command will be sent to the deck. The IDeckLinkDeckControl object must be in VTR control mode for this command to succeed. Syntax HRESULT Parameters Name error

2.4.25.7 IDeckLinkDeckControl::TogglePlayStop method

TogglePlayStop (BMDDeckControlError *error); Direction Description out The error code sent by the deck - see BMDDeckControlError for details.

Return Values Value E_FAIL S_OK E_INVALIDARG

Description Failure - check error parameter. Success The parameter is invalid.

SDK Software Developers Kit

181

SECTION

DeckLink API
The Eject method will send an eject tape command to the deck. The IDeckLinkDeckControl object must be in VTR control mode for this command to succeed. Syntax HRESULT Parameters Name error Direction Description out The error code sent by the deck - see BMDDeckControlError for details.

2.4.25.8 IDeckLinkDeckControl::Eject method

Eject (BMDDeckControlError *error);

Return Values Value E_FAIL S_OK E_INVALIDARG Description Failure - check error parameter. Success The parameter is invalid.

SDK Software Developers Kit

182

SECTION

DeckLink API
The GoToTimecode method will send a go to timecode command to the deck. Syntax HRESULT Parameters Name timecode error Direction Description in out The timecode to go to. The error code sent by the deck - see BMDDeckControlError for details.

2.4.25.9 IDeckLinkDeckControl::GoToTimecode method

GoToTimecode (BMDTimecodeBCD timecode, BMDDeckControlError *error);

Return Values Value E_FAIL S_OK E_INVALIDARG Description Failure - check error parameter. Success One or more parameters are invalid.

SDK Software Developers Kit

183

SECTION

DeckLink API
The FastForward method will send a fast forward command to the deck. The IDeckLinkDeckControl object must be in VTR control mode for this command to succeed. Syntax HRESULT Parameters Name viewTape

2.4.25.10 IDeckLinkDeckControl::FastForward method

FastForward (boolean viewTape,

BMDDeckControlError *error);

Direction Description in View the tape (TRUE) or enable automatic selection of tape view or end to end view (FALSE) The error code sent by the deck - see BMDDeckControlError for details.

error

out

Return Values Value E_FAIL S_OK E_INVALIDARG

Description Failure - check error parameter. Success One or more parameters are invalid.

SDK Software Developers Kit

184

SECTION

DeckLink API
The Rewind method will send a rewind command to the deck. The IDeckLinkDeckControl object must be in VTR control mode for this command to succeed. Syntax HRESULT Parameters Name viewTape

2.4.25.11 IDeckLinkDeckControl::Rewind method

Rewind (boolean viewTape, BMDDeckControlError *error);

Direction Description in View the tape (TRUE) or enable automatic selection of tape view or end to end view (FALSE) The error code sent by the deck - see BMDDeckControlError for details.

error

out

Return Values Value E_FAIL S_OK E_INVALIDARG

Description Failure Success One or more parameters are invalid.

SDK Software Developers Kit

185

SECTION

DeckLink API
The StepForward method will send a step forward command to the deck. The IDeckLinkDeckControl object must be in VTR control mode for this command to succeed. Syntax HRESULT Parameters Name error

2.4.25.12 IDeckLinkDeckControl::StepForward method

StepForward (BMDDeckControlError *error);

Direction Description out The error code sent by the deck - see BMDDeckControlError for details.

Return Values Value E_FAIL S_OK E_INVALIDARG Description Failure - check error parameter. Success The parameter is invalid.

SDK Software Developers Kit

186

SECTION

DeckLink API
The StepBack method will send a step back command to the deck. The IDeckLinkDeckControl object must be in VTR control mode for this command to succeed. Syntax HRESULT Parameters Name error

2.4.25.13 IDeckLinkDeckControl::StepBack method

StepBack (BMDDeckControlError *error);

Direction Description out The error code sent by the deck - see BMDDeckControlError for details.

Return Values Value E_FAIL S_OK E_INVALIDARG Description Failure - check error parameter. Success The parameter is invalid.

SDK Software Developers Kit

187

SECTION

DeckLink API
The Jog method will send a jog playback command to the deck. The IDeckLinkDeckControl object must be in VTR control mode for this command to succeed. Syntax HRESULT Parameters Name rate

2.4.25.14 IDeckLinkDeckControl::Jog method

Jog (double rate, BMDDeckControlError *error);

Direction Description in The rate at which to jog playback. A value greater than 0 will enable forward playback, value less than 0 will enable reverse playback. The rate range is from -50.0 to 50.0 The error code sent by the deck - see BMDDeckControlError for details.

error

out

Return Values Value E_FAIL S_OK E_INVALIDARG

Description Failure - check error parameter. Success One or more parameters are invalid.

SDK Software Developers Kit

188

SECTION

DeckLink API
The Shuttle method will send a shuttle playback command to the deck. The IDeckLinkDeckControl object must be in VTR control mode for this command to succeed. Syntax HRESULT Parameters Name rate

2.4.25.15 IDeckLinkDeckControl::Shuttle method

Shuttle (double rate, BMDDeckControlError *error);

Direction Description in The rate at which to shuttle playback. A value greater than 0 will enable forward playback, a value less than 0 will enable reverse playback. The rate range is from -50.0 to 50.0 The error code sent by the deck - see BMDDeckControlError for details.

error

out

Return Values Value E_FAIL S_OK E_INVALIDARG

Description Failure - check error parameter. Success One or more parameters are invalid.

SDK Software Developers Kit

189

SECTION

DeckLink API
The GetTimecodeString method will return the current timecode in string format. Syntax HRESULT Parameters Name currentTimeCode error Direction Description out out The current timecode in string format. The error code sent by the deck - see BMDDeckControlError for details.

2.4.25.16 IDeckLinkDeckControl::GetTimecodeString method

GetTimecodeString (string currentTimeCode, BMDDeckControlError *error);

Return Values Value E_FAIL S_OK E_INVALIDARG

Description Failure - check error parameter. Success One or more parameters are invalid.

SDK Software Developers Kit

190

SECTION

DeckLink API
The GetTimecode method will return the current timecode in IDeckLinkTimecode format. Syntax HRESULT Parameters Name currentTimeCode error Direction Description out out The current timecode in IDeckLinkTimecode format. The error code sent by the deck - see BMDDeckControlError for details.

2.4.25.17 IDeckLinkDeckControl::GetTimecode method

GetTimecode (IDeckLinkTimecode currentTimecode, BMDDeckControlError *error);

Return Values Value E_FAIL S_OK E_INVALIDARG

Description Failure - check error parameter. Success One or more parameters are invalid.

SDK Software Developers Kit

191

SECTION

DeckLink API
The GetTimecodeBCD method will return the current timecode in BCD format. Syntax HRESULT Parameters Name currentTimeCode error Direction Description out out The timecode in BCD format. The error code sent by the deck - see BMDDeckControlError for details.

2.4.25.18 IDeckLinkDeckControl::GetTimecodeBCD method

GetTimecodeBCD (BMDTimecodeBCD *currentTimecode, BMDDeckControlError *error);

Return Values Value E_FAIL S_OK E_INVALIDARG

Description Failure - check error parameter. Success One or more parameters are invalid.

SDK Software Developers Kit

192

SECTION

DeckLink API
The SetPreroll method will set the preroll time period. Syntax HRESULT Parameters Name prerollSeconds Direction Description in The preroll period in seconds to set.

2.4.25.19 IDeckLinkDeckControl::SetPreroll method

SetPreroll (uint32_t prerollSeconds);

Return Values Value S_OK Description Success

SDK Software Developers Kit

193

SECTION

DeckLink API
The GetPreroll method will get the preroll period setting. Syntax HRESULT Parameters Name prerollSeconds Direction Description out The current preroll period.

2.4.25.20 IDeckLinkDeckControl::GetPreroll method

GetPreroll (uint32_t *prerollSeconds);

Return Values Value E_FAIL S_OK E_INVALIDARG

Description Failure Success The parameter is invalid.

SDK Software Developers Kit

194

SECTION

DeckLink API
The capture offset may be used to compensate for a deck specific offset between the inpoint and the time at which the capture starts. Syntax HRESULT Parameters Name captureOffsetFields Direction Description in The timecode offset to set in fields.

2.4.25.21 IDeckLinkDeckControl::SetCaptureOffset method

SetCaptureOffset (int32_t captureOffsetFields);

Return Values Value S_OK Description Success

SDK Software Developers Kit

195

SECTION

DeckLink API
The GetCaptureOffset method will return the current setting of the field accurate capture timecode offset in fields. Syntax HRESULT Parameters Name captureOffsetFields Direction Description out The current timecode offset in fields.

2.4.25.22 IDeckLinkDeckControl::GetCaptureOffset method

GetCaptureOffset (int32_t *captureOffsetFields);

Return Values Value S_OK E_INVALIDARG

Description Success The parameter is invalid.

SDK Software Developers Kit

196

SECTION

DeckLink API
The SetExportOffset method will set the current export timecode offset in fields. This method permits fine control of the timecode offset to tailor for the response of an individual deck by adjusting the number of fields prior to the in or out point where an export will begin or end. Syntax HRESULT Parameters Name exportOffsetFields Direction Description in The timecode offset in fields.

2.4.25.23 IDeckLinkDeckControl::SetExportOffset method

SetExportOffset (int32_t exportOffsetFields);

Return Values Value S_OK Description Success

SDK Software Developers Kit

197

SECTION

DeckLink API
The GetExportOffset method will return the current setting of the export offset in fields. Syntax HRESULT Parameters Name exportOffsetFields Direction Description out The current timecode offset in fields.

2.4.25.24 IDeckLinkDeckControl::GetExportOffset method

GetExportOffset (int32_t * exportOffsetFields);

Return Values Value S_OK E_INVALIDARG

Description Success The parameter is invalid.

SDK Software Developers Kit

198

SECTION

DeckLink API
The GetManualExportOffset method will return the manual export offset for the current deck. This is only applicable for manual exports and may be adjusted with the main export offset if required. Syntax HRESULT Parameters Name deckManualExportOffsetFields

2.4.25.25 IDeckLinkDeckControl::GetManualExportOffset method

GetManualExportOffset (int32_t * deckManualExportOffsetFields);

Direction Description out The current timecode offset.

Return Values Value S_OK E_INVALIDARG

Description Success The parameter is invalid.

SDK Software Developers Kit

199

SECTION

DeckLink API
The StartExport method starts an export to tape operation using the given parameters. Prior to calling this method, the output interface should be set up as normal (refer to the Playback and IDeckLinkOutput interface sections). StartScheduledPlayback should be called in the bmdDeckControlPrepareForExportEvent event in IDeckLinkDeckControl StatusCallback::DeckControlEventReceived callback. The callback object should be set using IDeckLinkDeckControl::SetCallback. A connection to the deck should then be opened using IDeckLinkDeckControl::Open. The preroll period can be set using IDeckLink DeckControl::SetPreroll and an offset period set using IDeckLinkDeckControl::SetExportOffset. After StartExport is called, the export will commence when the current time code current equals the inTimecode. Scheduled frames are exported until the current timecode equals the outTimecode. During this period the IDeckLinkDeckControlStatusCallback will be called when deck control events occur. At the completion of the export operation the bmdDeckControlExportCompleteEvent in the IDeckLinkDeckControlStatusCallback::DeckControlEventReceived will occur several frames from the outTimecode. Resources may be released at this point or another export may be commenced.

2.4.25.26 IDeckLinkDeckControl::StartExport method

SDK Software Developers Kit

200

SECTION

DeckLink API
Syntax HRESULT StartExport (BMDTimecodeBCD inTimecode, BMDTimecodeBCD outTimecode, BMDDeckControlExportModeOpsFlags exportModeOps, BMDDeckControlError *error);

Parameters Name inTimecode outTimecode exportModeOps error

Direction Description in in in out The timecode to start the export sequence. The timecode to stop the export sequence. The export mode operations - see BMDDeckControlExportModeOpsFlags for details. The error code sent by the deck - see BMDDeckControlError for details.

Return Values Value E_FAIL S_OK E_INVALIDARG Description Failure - check error parameter. Success The parameter is invalid.

SDK Software Developers Kit

201

SECTION

DeckLink API
The StartCapture method starts a capture operation using the given parameters. Prior to calling this method, the input interface should be set up as normal (refer to the Capture and IDeckLinkInput interface sections), IDeckLinkDeckControl should be configured (see description below) and a connection to the deck established using IDeckLinkDeckControl::Open. A callback object should be set using IDeckLinkDeckControl::SetCallback and an offset period set using IDeckLinkDeckControl::SetCaptureOffset. After StartCapture is called, the application must wait until the bmdDeckControlPrepareForCaptureEvent event is received via IDeckLinkDeckControl StatusCallback::DeckControlEventReceived callback. Reception of that event signals that the serial timecodes attached to the IDeckLinkVideoFrame objects (received via IDeckLink InputCallback::VideoInputFrameArrived) can be used to determine if the frame is between the inTimecode and outTimecode timecodes. The application must take into account that the serial timecode values should be adjusted by the value set using IDeckLinkDeckControl::SetCaptureOffset. During this period IDeckLinkDeckControlStatusCallback will be called when deck control events occur. At the completion of the capture operation the bmdDeckControlCaptureCompleteEvent event in the IDeckLinkDeckControlStatusCallback::DeckControlEventReceived method will occur several frames from the outTimecode. Resources may be released at this point. IDeckLinkDeckControl will return to VTR control mode.

2.4.25.27 IDeckLinkDeckControl::StartCapture method

SDK Software Developers Kit

202

SECTION

DeckLink API
Syntax HRESULT StartCapture (boolean useVITC, BMDTimecodeBCD inTimecode, BMDTimecodeBCD outTimecode, BMDDeckControlError *error);

Parameters Name useVITC inTimecode outTimecode error

Direction Description in in in out If true use VITC as the source of timecodes. The timecode to start the capture sequence. The timecode to stop the capture sequence. Error code sent by the deck - see BMDDeckControlError for details.

Return Values Value E_FAIL S_OK E_INVALIDARG Description Failure - check error parameter. Success One or more parameters are invalid.

SDK Software Developers Kit

203

SECTION

DeckLink API
The GetDeviceID method gets the device ID returned by the deck. The IDeckLinkDeckControl must be in VTR control mode for this command to succeed. Syntax HRESULT Parameters Name deviceId error

2.4.25.28 IDeckLinkDeckControl::GetDeviceID method

GetDeviceID (uint16_t *deviceId, BMDDeckControlError *error);

Direction Description out out The code for the device model. The error code sent by the deck - see BMDDeckControlError for details.

Return Values Value E_FAIL S_OK E_INVALIDARG Description Failure - check error parameter. Success One or more parameters are invalid.

SDK Software Developers Kit

204

SECTION

DeckLink API
The Abort operation is synchronous. Completion is signaled with a bmdDeckControlAbortedEvent event. Syntax HRESULT Return Values Value E_FAIL S_OK Description Failure Success

2.4.25.29 IDeckLinkDeckControl::Abort method

Abort (void);

SDK Software Developers Kit

205

SECTION

DeckLink API
The CrashRecordStart method sets the deck to record. The IDeckLinkDeckControl object must be in VTR control mode for this command to succeed. Syntax HRESULT Parameters Name error Direction Description out The error code sent by the deck - see BMDDeckControlError for details.

2.4.25.30 IDeckLinkDeckControl::CrashRecordStart method

CrashRecordStart (BMDDeckControlError *error);

Return Values Value E_FAIL S_OK E_INVALIDARG Description Failure - check error parameter. Success The parameter is invalid.

SDK Software Developers Kit

206

SECTION

DeckLink API
The CrashRecordStop method stops the deck record operation. The IDeckLinkDeckControl object must be in VTR control mode for this command to succeed. Syntax HRESULT Parameters Name error Direction Description out The error code sent by the deck - see BMDDeckControlError for details.

2.4.25.31 IDeckLinkDeckControl::CrashRecordStop method

CrashRecordStop (BMDDeckControlError *error);

Return Values Value E_FAIL S_OK E_INVALIDARG Description Failure - check error parameter. Success The parameter is invalid.

SDK Software Developers Kit

207

SECTION

DeckLink API
The SetCallback method installs a callback object to be called when deck control events occur. Syntax HRESULT Parameters Name callback Direction Description in The callback object implementing the IDeckLinkDeckControlStatusCallback object interface

2.4.25.32 IDeckLinkDeckControl::SetCallback method

SetCallback ( IDeckLinkDeckControlStatusCallback *callback);

Return Values Value S_OK Description Success

SDK Software Developers Kit

208

SECTION

DeckLink API
The IDeckLinkDeckControlStatusCallback object interface is a callback class which is called when the Deck control status has changed. An object with the IDeckLinkDeckControlStatusCallback object interface may be registered as a callback with the IDeckLinkDeckControl interface. Related Interfaces Interface
IDeckLink DeckControl

2.4.26 IDeckLinkDeckControlStatusCallback Interface [new in DeckLink 7.6]

Interface ID
IID_IDeckLinkDeck Control

Description An IDeckLinkDeckControlStatusCallBack object interface may be registered with IDeckLinkDeckControl::SetCallback

Public Member Functions Method TimecodeUpdate VTRControlStateChanged DeckControlEventReceived DeckControlStatusChanged Description Called when there is a change to the timecode. Called when the control state of the deck changes. Called when a deck control event occurs. Called when deck control status has changed.

SDK Software Developers Kit

209

SECTION

DeckLink API
The TimecodeUpdate method is called when there is a change to the timecode. Timecodes may be missed when playing at non 1x speed. This method will not be called during capture, and the serial timecode attached to each frame delivered by the API should be used instead. Syntax HRESULT Parameters Name currentTimecode Direction Description in The current timecode.

2.4.26.1 IDeckLinkDeckControlStatusCallback::TimecodeUpdate method

TimecodeUpdate (BMDTimecodeBCD currentTimecode);

Return Values Value E_FAIL S_OK Description Failure Success

SDK Software Developers Kit

210

SECTION

DeckLink API
The VTRControlStateChanged method is called when there is a change in the deck control state. Refer to BMDDeckControlVTRControlState for the possible states. This method is only called while in VTR control mode. Syntax HRESULT Parameters Name newState error Return Values Value E_FAIL S_OK Description Failure Success

2.4.26.2 IDeckLinkDeckControlStatusCallback::VTRControlStateChanged method

VTRControlStateChanged (BMDDeckControlVTRControlState newState, BMDDeckControlError error);

Direction Description in in The new deck control state - see BMDDeckControlVTRControlState for details. The deck control error code.

SDK Software Developers Kit

211

SECTION

DeckLink API
The DeckControlEventReceived method is called when a deck control event occurs. Syntax HRESULT Parameters Name event error Return Values Value E_FAIL S_OK Description Failure Success Direction Description in in The deck control event that has occurred - see BMDDeckControlEvent for details. The deck control error that has occurred.

2.4.26.3 IDeckLinkDeckControlStatusCallback::DeckControlEventReceived method

DeckControlEventReceived (BMDDeckControlEvent event, BMDDeckControlError error);

SDK Software Developers Kit

212

SECTION

DeckLink API
The DeckControlStatusChanged method is called when the deck control status has changed. Syntax HRESULT Parameters Name flags mask Return Values Value E_FAIL S_OK Description Failure Success Direction Description in in The deck control current status - see BMDDeckControlStatusFlags for details. The deck control status event flag(s) that has changed.

2.4.26.4 IDeckLinkDeckControlStatusCallback::DeckControlStatusChanged method

DeckControlStatusChanged (BMDDeckControlStatusFlags flags, uint32_t mask);

SDK Software Developers Kit

213

SECTION

DeckLink API

2.5 Common Data Types 2.5.1 Basic Types


boolean boolean is represented differently on each platform by using its system type: Windows Mac OS X Linux Strings Strings are represented differently on each platform, using the most appropriate system type: Windows Mac OS X Linux BSTR CFStringRef char * BOOL bool bool

2.5.2 Time Representation


The API uses a flexible scheme to represent time values which can maintain accuracy for any video or audio rate. Time is always represented as a time scale and a time value. The time scale is a unit of ticks per second specified by the API user. Time values are represented as a number of time units since playback or capture began. The API user should choose a time scale value appropriate to the type of video or audio stream being handled. Some examples are provided below: Stream type 24 fps video 23.98 fps video Suggested time scale 24000 30000 Frame time values 0, 1000, 2000, 3000 0, 1001, 2002, 3003

SDK Software Developers Kit

214

SECTION

DeckLink API
BMDTimeScale BMDTimeScale is a large integer type which specifies the time scale for a time measurement in ticks per second. BMDTimeValue BMDTimeValue is a large integer type which represents a time in units of BMDTimeScale.

2.5.3 Display Modes


BMDDisplayMode enumerates the video modes supported for output and input. Mode bmdModeNTSC bmdModeNTSC2398 bmdModePAL bmdModeHD720p50 bmdModeHD720p5994 bmdModeHD720p60 bmdModeHD1080p2398 bmdModeHD1080p24 bmdModeHD1080p25 bmdModeHD1080p2997 bmdModeHD1080p30 bmdModeHD1080i50 bmdModeHD1080i5994 bmdModeHD1080i6000 bmdModeHD1080p50
continued over page...

Width 720 720 720 1280 1280 1280 1920 1920 1920 1920 1920 1920 1920 1920 1920

Height 486 486 576 720 720 720 1080 1080 1080 1080 1080 1080 1080 1080 1080

Frames per Second 30/1.001 30/1.001* 25 50 60/1.001 60 24/1.001 24 25 30/1.001 30 25 30/1.001 30 50

Fields per Frame 2 2 2 1 1 1 2 2 1 1 1 2 2 2 1

Suggested Time Scale 30000 24000* 25 50 60000 60 24000 24 25000 30000 30000 25 30000 30000 50000

Display Duration 1001 1001 1 1 1001 1 1001 1 1000 1001 1000 1 1001 1000 1000

SDK Software Developers Kit

215

SECTION

DeckLink API
Mode bmdModeHD1080p5994 bmdModeHD1080p6000 bmdMode2k2398 bmdMode2k24 bmdMode2k25 Width 1920 1920 2048 2048 2048 Height 1080 1080 1556 1556 1556 Frames per Second 60/1.001 60 24/1.001 24 25 Fields per Frame 1 1 2 2 2 Suggested Time Scale 60000 60000 24000 24 25000 Display Duration 1001 1000 1001 1 1000

Note: bmdModeNTSC2398 mode will be played out on the SDI output with a frame rate of 29.97 frames per second with 3:2 pull down. Some cards may not support all of these models

SDK Software Developers Kit

216

SECTION

DeckLink API
BMDPixelFormat enumerates the pixel formats supported for output and input. bmdFormat8BitYUV : UYVY 4:2:2 Representation Four 8-bit unsigned components (CCIR 601) are packed into one 32-bit little-endian word. Word Decreasing Address Order Byte 3 Y 1 7 6 5 4 3 2 1 0 7 6 5 Byte 2 Cr 0 4 3 2 1 0 7 6 5 Byte 1 Y 0 4 3 2 1 0 7 6 5 B yte 0 Cb 0 4 3 2 1 0

2.5.4 Pixel Formats

int framesize

= =

(Width * 16 / 8) * Height rowbytes * Height

In this format, two pixels fit 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 row bytes are simply multiplied by the number of rows in the frame.

SDK Software Developers Kit

217

SECTION

DeckLink API
bmdFormat10BitYUV : v210 4:2:2 Representation Twelve 10-bit unsigned components are packed into four 32-bit little-endian words. Word 0 Decreasing Address Order Byte 3 X X Cr 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 Word 1 Decreasing Address Order Byte 3 X X Y 2 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 Word 2 Decreasing Address Order Byte 3 X X Cb 4 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 Word 3 Decreasing Address Order Byte 3 X X Y 5 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 Byte 2 Cr 4 4 3 2 1 0 9 8 7 6 5 Byte 1 Byte 0 Y 4 4 3 2 1 0 Byte 2 Y3 4 3 2 1 0 9 8 7 6 5 Byte 1 Byte 0 Cr 2 4 3 2 1 0 Byte 2 Cb 2 4 3 2 1 0 9 8 7 6 5 Byte 1 Byte 0 Y 1 4 3 2 1 0 Byte 2 Y 0 4 3 2 1 0 9 8 7 6 5 Byte 1 Byte 0 Cb 0 4 3 2 1 0

SDK Software Developers Kit

218

SECTION

DeckLink API
int framesize = = ((Width + 47) / 48) * 128 * Height rowbytes * Height

In this format, each line of video must be aligned on a 128 byte boundary. 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 row bytes are simply multiplied by the number of rows in the frame. bmdFormat8BitARGB : ARGB (or ARGB32) 4:4:4:4 raw Four 8-bit unsigned components are packed into one 32-bit little-endian word. Alpha channel is valid. Word Decreasing Address Order Byte 3 B 7 6 5 4 3 2 1 0 7 6 5 Byte 2 G 4 3 2 1 0 7 6 5 Byte 1 R 4 3 2 1 0 7 6 5 Byte 0 A 4 3 2 1 0

int framesize

= =

(Width * 32 / 8) * Height rowbytes * Height

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 row bytes are simply multiplied by the number of rows in the frame.

SDK Software Developers Kit

219

SECTION

DeckLink API
bmdFormat8BitBGRA : BGRA (or RGB32) 4:4:4:x raw Four 8-bit unsigned components are packed into one 32-bit little-endian word. The alpha channel may be valid. Word Decreasing Address Order Byte 3 X 7 6 5 4 3 2 1 0 7 6 5 Byte 2 R 4 3 2 1 0 7 6 5 Byte 1 G 4 3 2 1 0 7 6 5 Byte 0 B 4 3 2 1 0

int framesize

= =

(Width * 32 / 8) * Height rowbytes * Height

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 row bytes are simply multiplied by the number of rows in the frame.

SDK Software Developers Kit

220

SECTION

DeckLink API
bmdFormat10BitRGB : r210 4:4:4 raw Three 10-bit unsigned components are packed into one 32-bit big-endian word. Word Decreasing Address Order Byte 3 B Lo 7 6 5 4 3 2 1 0 5 4 Byte 2 G Lo 3 2 1 0 Byte 1 B Hi 9 8 3 R Lo 2 1 0 9 G Hi 8 7 6 X x X x 9 Byte 0 R Hi 8 7 6 5 4

int framesize

= =

((Width + 63) / 64) * 256 * Height rowbytes * Height

In this format each line of video must be aligned a 256 byte boundary. One pixel fits into 4 bytes so 64 pixels fit into 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 row bytes are simply multiplied by the number of rows in the frame.

2.5.5 Field Dominance


BMDFieldDominance bmdUnknownFieldDominance bmdLowerFieldFirst bmdUpperFieldFirst bmdProgressiveFrame enumerates settings applicable to video fields. Indeterminate field dominance. The first frame starts with the lower field (the second-from-the-top scan line). The first frame starts with the upper field (the top scan line). A complete frame containing all scan lines.

SDK Software Developers Kit

221

SECTION

DeckLink API
BMDFrameFlags enumerates a set of flags applicable to a video frame. bmdFrameFlagDefault bmdFrameFlagFlipVertical bmdFrameHasNoInputSource bmdProgressiveSegmentedFrame No other flags applicable. Frame should be flipped vertically on output No input source was detected frame is invalid A progressive frame encoded as a PsF. (See IDeckLinkDisplayMode::GetFieldDominance for details)

2.5.6 Frame Flags

2.5.7 Input Video Mode Flags


BMDVideoInputModeFlags enumerates a set of flags applicable to video input. bmdVideoInputFlagDefault No other flags applicable (See IDeckLinkInputCallback::VideoInputFormatChanged for details)

bmdVideoInputEnableFormatDetection Enable video input mode detection.

2.5.8 Video Output Flags


BMDVideoOutputFlags enumerates flags which control the output of video data. bmdVideoOutputFlagDefault bmdVideoOutputRP188 bmdVideoOutputVANC No flags applicable. Output RP188 timecode. If supplied see: IDeckLinkMutableVideoFrame::SetTimecode Output VANC data If supplied see: IDeckLinkMutableVideoFrame::SetAncillaryData

SDK Software Developers Kit

222

SECTION

DeckLink API
BMDOutputFrameCompletionResult enumerates the possible frame output completion statuses. bmdOutputFrameCompleted bmdOutputFrameDisplayedLate bmdOutputFrameDropped bmdOutputFrameFlushed Frame was displayed normally Frame was displayed late Frame was dropped Frame was flushed

2.5.9 Output Frame Completion Results Flags

Frames are flushed when they have been scheduled but are no longer needed due to an action initiated by the API user e.g. a speed or direction change. If frame scheduling falls behind frame output, the hardware will output the least late frame available. When this happens, the frame will receive a completion status of displayed late. Frames that are never displayed due to a less late frame being available will receive a completion status of dropped.

SDK Software Developers Kit

223

SECTION

DeckLink API
BMDVideoConnection enumerates the possible video connection interfaces. bmdVideoConnectionSDI bmdVideoConnectionHDMI bmdVideoConnectionOpticalSDI bmdVideoConnectionComponent bmdVideoConnectionComposite bmdVideoConnectionSVideo SDI video connection HDMI video connection Optical SDI connection Component video connection Composite video connection S-Video connection

2.5.10 Video Connection Modes

2.5.11 Audio Sample Rates


BMDAudioSampleRate enumerates the possible audio sample rates. bmdAudioSampleRate48kHz 48 kHz sample rate

2.5.12 Audio Sample Types


BMDAudioSampleType enumerates the possible audio sample types. bmdAudioSampleType16bitInteger bmdAudioSampleType32bitInteger 16 bit audio sample 32 bit audio sample

SDK Software Developers Kit

224

SECTION

DeckLink API
BMDDeckLinkAPIInformationID enumerates a set of information details which may be queried (see IDeckLinkAPIInformation Interface for details). Name BMDDeckLinkAPIVersion BMDDeckLinkAPIVersion Type Description

2.5.13 DeckLink Information ID

String The user viewable API version number. This allocated string must be freed by the caller when no longer required. Int The API version number. Format:
Word Decreasing Address Order Byte 4
Major Version

Byte 3
Minor Version

Byte 2
Sub Version

Byte 1
Extra

SDK Software Developers Kit

225

SECTION

DeckLink API
BMDDeckLinkAttributeID enumerates a set of attributes of a DeckLink device which may be queried (see IDeckLinkAttributes Interface for details). Name
BMDDeckLinkSupportsInternalKeying BMDDeckLinkSupportsExternalKeying BMDDeckLinkSupportsHDKeying BMDDeckLinkSerialDevicePortName

2.5.14 DeckLink Attribute ID

Type Flag Flag Flag

Description True if internal keying is supported on this device. True if external keying is supported on this device. True if HD keying is supported on this device.

String The operating system name of the RS422 serial port on this device. This allocated string must be freed by the caller when no longer required. Int Flag Flag Int The maximum number of audio channels supported by this device. True if input format detection is supported on this device. True if device has a serial port. Some DeckLink hardware devices contain multiple independent sub-devices. This attribute will be equal to one for most devices, or two or more on a card with multiple sub-devices (eg DeckLink Duo). Some DeckLink hardware devices contain multiple independent sub-devices. This attribute indicates the index of the sub-device, starting from zero.

BMDDeckLinkMaximumAudioChannels
BMDDeckLinkSupportsInputFormatDetection BMDDeckLinkHasSerialPort BMDDeckLinkNumberOfSubDevices

BMDDeckLinkSubDeviceIndex

Int

2.5.15 Audio Output Stream Type


BMDAudioOutputStreamType enumerates the Audio output stream type (see IDeckLinkOutput::EnableAudioOutput for details). Name
bmdAudioOutputStreamContinuous bmdAudioOutputStreamContinuousDontResample
bmdAudioOutputStreamTimestamped

Description Audio stream is continuous. Lock audio sample rate. (not currently supported) Audio stream is time stamped.

SDK Software Developers Kit

226

SECTION

DeckLink API
BMDAnalogVideoFlags enumerates a set of flags applicable to analog video. bmdAnalogVideoFlagCompositeSetup75 This flag is only applicable to NTSC composite video and sets the black level to 7.5 IRE, which is used in the USA, rather than the default of 0.0 IRE which is used in Japan. bmdAnalogVideoFlagComponentBetacamLevels This flag is only applicable to the component analog video levels. It sets the levels of the color difference channels in accordance to the SMPTE standard or boosts them by a factor of 4/3 for the Betacam format.

2.5.16 Analog Video Flags

2.5.17 Audio Connection Modes


BMDAudioConnection enumerates the possible audio connection interfaces. bmdAudioConnectionEmbedded bmdAudioConnectionAESEBU bmdAudioConnectionAnalog Embedded SDI or HDMI audio connection AES/EBU audio connection Analog audio connection

SDK Software Developers Kit

227

SECTION

DeckLink API
BMDVideoOutputConversionMode enumerates the possible video output conversions. bmdNoVideoOutputConversion bmdVideoOutputLetterboxDownconversion bmdVideoOutputAnamorphicDownconversion bmdVideoOutputHD720toHD1080Conversion bmdVideoOutputHardwareLetterboxDownconversion bmdVideoOutputHardwareAnamorphicDownconversion bmdVideoOutputHardwareCenterCutDownconversion bmdVideoOutputHardware720p1080pCrossconversion bmdVideoOutputHardwareAnamorphic720pUpconversion bmdVideoOutputHardwareAnamorphic1080iUpconversion bmdVideoOutputHardwarePillarbox720pUpconversion bmdVideoOutputHardwarePillarbox1080iUpconversion No video output conversion Down-converted letterbox SD output Down-converted anamorphic SD output HD720 to HD1080 conversion output Simultaneous output of HD and down-converted letterbox SD Simultaneous output of HD and down-converted anamorphic SD Simultaneous output of HD and center cut SD The simultaneous output of 720p and 1080p cross-conversion The simultaneous output of SD and up-converted anamorphic 720p The simultaneous output of SD and up-converted anamorphic 1080i The simultaneous output of SD and up-converted pillarbox 720p The simultaneous output of SD and up-converted pillarbox 1080i

2.5.18 Output Conversion Modes

SDK Software Developers Kit

228

SECTION

DeckLink API
BMDVideoInputConversionMode enumerates the possible video input conversions. bmdNoVideoInputConversion bmdVideoInputLetterboxDownconversionFromHD1080 bmdVideoInputAnamorphicDownconversionFromHD1080 bmdVideoInputLetterboxDownconversionFromHD720 bmdVideoInputAnamorphicDownconversionFromHD720 bmdVideoInputLetterboxUpconversion bmdVideoInputAnamorphicUpconversion No video input conversion HD1080 to SD video input down conversion Anamorphic from HD1080 to SD video input down conversion Letter box from HD720 to SD video input down conversion Anamorphic from HD720 to SD video input down conversion Letterbox video input up conversion Anamorphic video input up conversion

2.5.19 Input Conversion Modes

2.5.20 Video Input Format Changed Events


BMDVideoInputFormatChangedEvents enumerates the properties of the video input signal format that have changed. (See IDeckLinkInputCallback:: VideoInputFormatChanged for details). bmdVideoInputDisplayModeChanged bmdVideoInputFieldDominanceChanged bmdVideoInputColorspaceChanged Video input display mode has changed (see BMDDisplayMode for details) Video input field dominance has changed (see BMDFieldDominance for details) Video input color space has changed (see BMDDetectedVideoInputFormatFlags for details))

2.5.21 Display Mode Support


BMDDisplayModeSupport enumerates the possible display mode support types. bmdDisplayModeNotSupported bmdDisplayModeSupported bmdDisplayModeSupportedWithConversion Display mode is not supported Display mode is supported natively Display mode is supported with conversion

SDK Software Developers Kit

229

SECTION

DeckLink API
BMDTimecodeFormat enumerates the possible video frame timecode formats. bmdTimecodeRP188 bmdTimecodeVITC bmdTimecodeSerial RP188 timecode VITC timecode Serial timecode

2.5.22 BMDTimecodeFormat

2.5.23 BMDTimecodeFlags
BMDTimecodeFlags enumerates the possible flags that accompany a timecode. bmdTimecodeFlagDefault bmdTimecodeIsDropFrame timecode is a non-drop timecode timecode is a drop timecode

SDK Software Developers Kit

230

SECTION

DeckLink API
Each four bits represent a single decimal digit: digit 0 1 2 3 4 5 6 7 8 9 bit 3 0 0 0 0 0 0 0 0 1 1 bit 2 0 0 0 0 1 1 1 1 0 0 bit 1 0 0 1 1 0 0 1 1 0 0 Word Decreasing Address Order Byte 4 Tens of hours 7 6 5 4 3 hours 2 1 0 7 6 5 Byte 3 Tens of minutes 4 3 minutes 2 1 0 7 6 5 Byte 2 Tens of seconds 4 3 seconds 2 1 0 7 6 5 Byte 1 Tens of frames 4 3 frames 2 1 0 bit 0 0 1 0 1 0 1 0 1 0 1

2.5.24 BMDTimecodeBCD

SDK Software Developers Kit

231

SECTION

DeckLink API
BMDDeckControlMode enumerates the possible deck control modes. bmdDeckControlNotOpened bmdDeckControlVTRControlMode bmdDeckControlExportMode bmdDeckControlCaptureMode Deck control is not opened Deck control VTR control mode Deck control export mode Deck control capture mode

2.5.25 Deck Control Mode [new in DeckLink 7.6]

2.5.26 Deck Control Event [new in DeckLink 7.6]


BMDDeckControlEvent enumerates the possible deck control events. bmdDeckControlAbortedEvent bmdDeckControlPrepareForExportEvent bmdDeckControlExportCompleteEvent This event is triggered when a capture or edit-to-tape operation is aborted. This export-to-tape event is triggered a few frames before reaching the in-point. At this stage, IDeckLinkOutput::StartScheduledPlayback() must be called. This export-to-tape event is triggered a few frames after reaching the out-point. At this point, it is safe to stop playback. Upon reception of this event the decks control mode is set back to bmdDeckControlVTRControlMode. This capture event is triggered a few frames before reaching the in-point. The serial timecode attached to IDeckLinkVideoInputFrames is now valid. This capture event is triggered a few frames after reaching the out-point. Upon reception of this event the decks control mode is set back to bmdDeckControlVTRControlMode.

bmdDeckControlPrepareForCaptureEvent bmdDeckControlCaptureCompleteEvent

SDK Software Developers Kit

232

SECTION

DeckLink API
BMDDeckControlVTRControlState enumerates the possible deck control VTR control states. bmdDeckControlNotInVTRControlMode bmdDeckControlVTRControlPlaying bmdDeckControlVTRControlRecording bmdDeckControlVTRControlStill bmdDeckControlVTRControlSeeking bmdDeckControlVTRControlStopped The deck is currently not in VTR control mode. The deck is currently playing. The deck is currently recording The deck is currently paused. The deck is currently seeking The deck is currently stopped.

2.5.27 Deck Control VTR Control States [new in DeckLink 7.6]

2.5.28 Deck Control Status Flags [new in DeckLink 7.6]


BMDDeckControlStatusFlags enumerates the possible deck control status flags. bmdDeckControlStatusDeckConnected bmdDeckControlStatusRemoteMode bmdDeckControlStatusRecordInhibited bmdDeckControlStatusCassetteOut The deck has been connected (TRUE) / disconnected (FALSE). The deck is in remote (TRUE) / local mode (FALSE). Recording is inhibited (TRUE) / allowed(FALSE). The deck does not have a cassette (TRUE).

SDK Software Developers Kit

233

SECTION

DeckLink API
BMDDeckControlExportModeOpsFlags enumerates the possible deck control edit-to-tape and export-to-tape mode operations. bmdDeckControlExportModeInsertVideo bmdDeckControlExportModeInsertAudio1 bmdDeckControlExportModeInsertAudio2 bmdDeckControlExportModeInsertAudio3 bmdDeckControlExportModeInsertAudio4 bmdDeckControlExportModeInsertAudio5 bmdDeckControlExportModeInsertAudio6 bmdDeckControlExportModeInsertAudio7 bmdDeckControlExportModeInsertAudio8 bmdDeckControlExportModeInsertAudio9 bmdDeckControlExportModeInsertAudio10 bmdDeckControlExportModeInsertAudio11 bmdDeckControlExportModeInsertAudio12 bmdDeckControlExportModeInsertTimeCode bmdDeckControlExportModeInsertAssemble bmdDeckControlExportModeInsertPreview bmdDeckControlUseManualExport Insert video Insert audio track 1 Insert audio track 2 Insert audio track 3 Insert audio track 4 Insert audio track 5 Insert audio track 6 Insert audio track 7 Insert audio track 8 Insert audio track 9 Insert audio track 10 Insert audio track 11 Insert audio track 12 Insert timecode Enable assemble editing. Enable preview auto editing Use edit on/off (TRUE) or autoedit (FALSE). Edit on/off is currently not supported.

2.5.29 Deck Control Export Mode Ops Flags [new in DeckLink 7.6]

SDK Software Developers Kit

234

SECTION

DeckLink API
BMDDeckControlError enumerates the possible deck control errors. bmdDeckControlNoError bmdDeckControlModeError bmdDeckControlMissedInPointError bmdDeckControlDeckTimeoutError bmdDeckControlCommandFailedError bmdDeckControlDeviceAlreadyOpenedError bmdDeckControlFailedToOpenDeviceError bmdDeckControlInLocalModeError bmdDeckControlEndOfTapeError bmdDeckControlUserAbortError bmdDeckControlNoTapeInDeckError bmdDeckControlNoVideoFromCardError bmdDeckControlNoCommunicationError bmdDeckControlUnknownError The deck is not in the correct mode for the desired operation. Eg. A play command is issued, but the current mode is not VTRControlMode The in point was missed while prerolling as the current timecode has passed the begin in / capture timecode. Deck control timeout error A deck control command request has failed. The deck control device is already open. Deck control failed to open the serial device. The deck in local mode and is no longer controllable. Deck control has reached or is trying to move past the end of the tape. Abort an export-to-tape or capture operation. There is currently no tape in the deck. A capture or export operation was attempted when the input signal was invalid. The deck is not responding to requests. Deck control unknown error

2.5.30 Deck Control error [new in DeckLink 7.6]

SDK Software Developers Kit

235

www.blackmagic-design.com

SDK Software Developers Kit

You might also like