Professional Documents
Culture Documents
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
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
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
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
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
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
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
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
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
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
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.
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.
13
SECTION
API DESIGN
1.4 Interface Reference
Every object interface subclasses the IUnknown interface.
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.
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.
AddRef();
Release();
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
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
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.
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
20
SECTION
DeckLink API
Public Member Functions Method Next Description Returns a an IDeckLink object interface corresponding to an individual DeckLink device.
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
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
IDeckLinkOutput
IID_IDeckLinkOutput
IDeckLinkInput
IID_IDeckLinkInput
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
23
SECTION
DeckLink API
Public Member Functions Method GetModelName Description Method to get DeckLink device model name.
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.
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
IDeckLinkAudioOutputCallback
IID_DeckLinkAudioOutputCallback
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
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
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
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
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
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
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.
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
34
SECTION
DeckLink API
The CreateVideoFrame method creates a video frame for output (see IDeckLinkMutableVideoFrame for more information). Syntax HRESULT
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
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
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
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.
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
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
38
SECTION
DeckLink API
The SetScheduledFrameCompletionCallback method configures a callback which will be called when each scheduled frame is completed. Syntax HRESULT
Parameters Name theCallBack Direction Description in callback object implementing the IDeckLinkOutputCallback object interface
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.
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
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.
41
SECTION
DeckLink API
The DisableAudioOutput method disables the hardware audio output mode. Syntax HRESULT Parameters none.
DisableAudioOutput ();
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
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
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
BeginAudioPreroll ();
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
EndAudioPreroll ();
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
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
in out
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.
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
FlushBufferedAudioSamples ();
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
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.
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.
timeScale
in
51
SECTION
DeckLink API
The GetScheduledStreamTime method returns the elapsed time since scheduled playback began. Syntax HRESULT
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
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
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)
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
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
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
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
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
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
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.
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
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
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.
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
DisableVideoInput ();
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
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
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
DisableAudioInput ();
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.
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.
StartStreams ();
StopStreams ();
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
FlushStreams ();
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
PauseStreams ();
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
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
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)
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
Interface ID
IID_IDeckLinkMutable IID_IDeckLink VideoInputFrame
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
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
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
GetWidth ();
GetHeight ();
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
GetRowBytes ();
GetPixelFormat ();
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)
GetFlags ();
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.
Description Failure Success An invalid or unsupported timecode format was requested. The requested timecode format was not present or valid in the ancillary data.
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.
Return Values Value S_OK S_FALSE Description Success No ancillary data present.
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
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.
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
Parameters Name completedFrame result Direction Description in in Completed frame Frame completion result see BMDOutputFrameCompletionResult for details.
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
ScheduledPlaybackHasStopped(void)
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
Interface ID
IID_IDeckLink VideoFrame
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
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.
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.
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
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)
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);
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
Interface ID
IID_IDeckLinkOutput
Public Member Functions Method RenderAudioSamples Description Called to allow buffering of more audio samples if required
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
Direction Description in Flag specifying whether driver is currently prerolling (TRUE) or playing (FALSE).
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
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
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
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
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.
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
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
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
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
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
91
SECTION
DeckLink API
The GetStreamTime method returns the time and duration of a captured video frame for a given timescale. Syntax HRESULT
Direction Description out out in Frame time (in units of timeScale) Frame duration (in units of timeScale) Time scale for output parameters
92
SECTION
DeckLink API
The GetHardwareReferenceTimestamp method returns frame time and frame duration for a given timescale. Syntax HRESULT
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
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
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
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
GetSampleCount ();
95
SECTION
DeckLink API
The GetPacketTime method returns the time stamp of the video frame corresponding to the specified audio packet. Syntax HRESULT
Direction Description out in Video frame time corresponding to audio packet in timeScale units Time scale for time stamp to be returned
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
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
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.
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
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
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
GetWidth ();
GetHeight ();
100
SECTION
DeckLink API
The GetName method returns a string describing the display mode. Syntax HRESULT Parameters Name name
Direction Description out Descriptive string This allocated string must be freed by the caller when no longer required. Description Failure Success
GetDisplayMode ();
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
Parameters Name timeValue timeScale Return Values Value E_FAIL S_OK Description Failure Success Direction Description out out Frame rate value Frame rate scale
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.
GetFieldDominance ();
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
Interface ID
IID_IDeckLink
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
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
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
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
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
WriteConfigurationToPreferences ();
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
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
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
110
SECTION
DeckLink API
The Set444And3GBpsVideoOutput method allows configuration of the 444 video and 3Gb/s output options. Syntax HRESULT
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
111
SECTION
DeckLink API
The Get444And3GBpsVideoOutput method returns the current configuration of the 444 video and 3Gb/s output options. Syntax HRESULT
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
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
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
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
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)
116
SECTION
DeckLink API
The SetVideoOutputConversionMode method sets the video output conversion mode. The possible output modes are enumerated by BMDVideoOutputConversionMode. Syntax HRESULT
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
117
SECTION
DeckLink API
The GetVideoOutputConversionMode method gets the current video output conversion mode. Syntax HRESULT
Parameters Name conversionMode Direction Description out current video output conversion mode
118
SECTION
DeckLink API
The Set_HD1080p24_to_HD1080i5994_Conversion method allows configuration of the HD1080p24 to HD1080i5994 conversion mode. Syntax HRESULT
119
SECTION
DeckLink API
The Get_HD1080p24_to_HD1080i5994_Conversion method returns the current status of the HD1080p24 to HD1080i5994 conversion mode. Syntax HRESULT
Parameters Name enable Direction Description out conversion status - enabled (TRUE) or disabled (FALSE)
120
SECTION
DeckLink API
The SetVideoInputFormat method sets the video connection to use for video input. Syntax HRESULT
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
121
SECTION
DeckLink API
The GetVideoInputFormat method returns the current video connection used for video input. Syntax HRESULT
Parameters Name videoInputFormat Direction Description out current connection used for video input
122
SECTION
DeckLink API
The SetAnalogVideoInputFlags method allows configuration of analog video input flags. Syntax HRESULT
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
123
SECTION
DeckLink API
The GetAnalogVideoInputFlags method returns the currently enabled analog video input flags. Syntax HRESULT
Parameters Name analogVideoFlags Direction Description out current analog video input flags
124
SECTION
DeckLink API
The SetVideoInputConversionMode method allows setting of the current video input conversion mode. Syntax HRESULT
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
125
SECTION
DeckLink API
The GetVideoInputConversionMode method returns the currently selected video input conversion mode. Syntax HRESULT
Parameters Name conversionMode Direction Description out current video input conversion mode
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);
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
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);
Return Values Value E_FAIL E_INVALIDARG S_OK Description Failure Mode not supported on this device Success
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
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
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
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
131
SECTION
DeckLink API
The GetVancSourceLineMapping method returns the current VANC to active picture line mapping. Syntax HRESULT
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
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
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
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
Interface ID
IID_IDeckLinkIterator
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
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.
Return Values Value E_FAIL S_OK E_INVALIDARG Description Failure Success There is no flag type attribute corresponding to cfgID.
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.
Return Values Value S_OK E_INVALIDARG Description Success There is no int type attribute corresponding to cfgID.
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.
Return Values Value S_OK E_INVALIDARG Description Success There is no float type attribute corresponding to cfgID.
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.
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
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
Interface ID
IID_IDeckLink
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
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
Direction Description in out BMDDeckLinkAttributeID to get flag value. The value corresponding to cfgID.
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.
Return Values Value E_FAIL S_OK E_INVALIDARG Description Failure Success There is no int type attribute corresponding to cfgID.
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.
Return Values Value E_FAIL S_OK E_INVALIDARG Description Failure Success There is no float type attribute corresponding to cfgID.
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.
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
Interface ID
IID_IDeckLinkOutput
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).
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
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.
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
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.
Commit ();
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
Decommit ();
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
Interface ID
IID_IDeckLink
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
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
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);
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);
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);
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();
155
SECTION
DeckLink API
The IDeckLinkVideoFrameAncillary object interface represents the ancillary data associated with a video frame. Related Interfaces Interface
IDeckLink Timecode
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.
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)
GetDisplayMode ();
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.
Return Values Value E_FAIL S_OK E_INVALIDARG Description Failure Success An invalid ancillary line number was requested
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
Interface ID
IID_IDeckLinkVideo FrameAncillary
Public Member Functions Method GetBCD GetComponents GetString GetFlags Description Get timecode in BCD Get timecode components Get timecode as formatted string Get timecode flags
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)
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
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
GetString(string *timecode);
BMDTimecodeFlags GetFlags();
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
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
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
DrawFrame(IDeckLinkVideoFrame *theFrame);
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
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
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
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
InitializeGL();
PaintGL();
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
SetFrame(IDeckLinkVideoFrame *theFrame)
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
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
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.
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
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
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.
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.
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.
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.
SetFrame(IDeckLinkVideoFrame *theFrame)
Return Values Value E_FAIL S_OK E_INVALIDARG Description Failure - check error parameter. Success One or more parameters are invalid.
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.
176
SECTION
DeckLink API
The GetCurrentState method will get the current state of the deck. Syntax HRESULT
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.
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)
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.
Return Values Value E_FAIL S_OK E_INVALIDARG Description Failure - check error parameter. Success The parameter is invalid.
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.
Return Values Value E_FAIL S_OK E_INVALIDARG Description Failure - check error parameter. Success The parameter is invalid.
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
TogglePlayStop (BMDDeckControlError *error); Direction Description out The error code sent by the deck - see BMDDeckControlError for details.
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.
Return Values Value E_FAIL S_OK E_INVALIDARG Description Failure - check error parameter. Success The parameter is invalid.
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.
Return Values Value E_FAIL S_OK E_INVALIDARG Description Failure - check error parameter. Success One or more parameters are invalid.
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
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
Description Failure - check error parameter. Success One or more parameters are invalid.
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
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
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
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.
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
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.
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
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
Description Failure - check error parameter. Success One or more parameters are invalid.
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
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
Description Failure - check error parameter. Success One or more parameters are invalid.
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.
Description Failure - check error parameter. Success One or more parameters are invalid.
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.
Description Failure - check error parameter. Success One or more parameters are invalid.
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.
Description Failure - check error parameter. Success One or more parameters are invalid.
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.
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.
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.
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.
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.
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.
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
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.
200
SECTION
DeckLink API
Syntax HRESULT StartExport (BMDTimecodeBCD inTimecode, BMDTimecodeBCD outTimecode, BMDDeckControlExportModeOpsFlags exportModeOps, BMDDeckControlError *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.
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.
202
SECTION
DeckLink API
Syntax HRESULT StartCapture (boolean useVITC, BMDTimecodeBCD inTimecode, BMDTimecodeBCD outTimecode, BMDDeckControlError *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.
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
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.
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
Abort (void);
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.
Return Values Value E_FAIL S_OK E_INVALIDARG Description Failure - check error parameter. Success The parameter is invalid.
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.
Return Values Value E_FAIL S_OK E_INVALIDARG Description Failure - check error parameter. Success The parameter is invalid.
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
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
Interface ID
IID_IDeckLinkDeck Control
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.
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.
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
Direction Description in in The new deck control state - see BMDDeckControlVTRControlState for details. The deck control error code.
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.
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.
213
SECTION
DeckLink API
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.
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
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
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
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
int framesize
= =
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.
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
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
= =
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.
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
= =
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.
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
= =
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.
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)
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
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.
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
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
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
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
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
Description Audio stream is continuous. Lock audio sample rate. (not currently supported) Audio stream is time stamped.
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.
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
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
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
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
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
bmdDeckControlPrepareForCaptureEvent bmdDeckControlCaptureCompleteEvent
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.
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]
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
235
www.blackmagic-design.com